Interface LifecycleExtension

crates/openshell-driver-vm/src/lifecycle.rs:308–435

/// registration order**, so cleanup mirrors setup.
#[tonic::async_trait]
pub trait LifecycleExtension: std::fmt::Debug + Send + Sync {
    fn name(&self) -> &str;

    /// Declare when this extension participates in a sandbox's lifecycle.
    ///
    /// Defaults to [`ExtensionActivation::Global`] (runs for every sandbox).
    /// Override and return [`ExtensionActivation::OnRequest`] for an opt-in
    /// extension that should only run when the sandbox carries the matching
    /// request label.
    fn activation(&self) -> ExtensionActivation {
        ExtensionActivation::Global
    }

    fn descriptor(&self) -> ExtensionDescriptor {
        ExtensionDescriptor::new(self.name())
    }

    /// Contribute backend requirements and provisioning inputs to the plan
    /// before the driver picks a backend.
    ///
    /// Use this hook to:
    /// - Declare backend requirements with
    ///   [`LaunchPlan::require_backend`] or
    ///   [`LaunchPlan::require_backend_feature`].
    /// - Set [`LaunchPlan::kernel_profile`] or
    ///   [`LaunchPlan::kernel_image`].
    /// - Append [`LaunchPlan::guest_init_dropins`] entries.
    ///
    /// At this point [`LaunchPlan::backend`] is the driver's tentative
    /// choice and may still change during backend resolution. Do not perform
    /// host-side side effects here — defer them to
    /// [`before_launch`](Self::before_launch).
    async fn configure_launch(
        &self,
        _sandbox: &Sandbox,
        _state_dir: &Path,
        _plan: &mut LaunchPlan,
    ) -> LifecycleResult<()> {
        Ok(())
    }

    /// Perform host-side preparation with the resolved launch plan.
    ///
    /// At this point [`LaunchPlan::backend`],
    /// [`LaunchPlan::required_backends`], and
    /// [`LaunchPlan::required_backend_features`] are finalized and any
    /// backend-specific host resources (subnet, tap, vsock) have been
    /// allocated. This hook is the right place to bind PCI devices, set
    /// up filesystem state, or otherwise prepare the host.
    ///
    /// Implementations MAY append entries to [`LaunchPlan::env`] to
    /// inject additional guest environment variables, and MAY return an
    /// error to abort the launch. Implementations MUST NOT change
    /// [`LaunchPlan::backend`], [`LaunchPlan::required_backends`], or
    /// [`LaunchPlan::required_backend_features`]; those changes are
    /// ignored by the driver once `before_launch` is reached.
    ///
    /// If this hook performs allocations that must be released on failure