Struct FirecrackerCellBackend 

pub struct FirecrackerCellBackend { /* private fields */ }

Firecracker-backed CellBackend (L2-06).

On non-Linux hosts the live-VM table collapses to an unused unit field — the backend still constructs (so the supervisor’s composition root keeps compiling) but every CellBackend method short-circuits to an Unsupported-shaped CellosError::Host. This shapes Windows/macOS cargo check builds without dragging Linux-only kernel surface (tokio::net::UnixStream, TAP, nftables) into the cross-platform side of the workspace.

Implementations

impl FirecrackerCellBackend

pub fn new(config: FirecrackerConfig) -> Self

pub fn from_env() -> Result<Self, CellosError>

pub fn with_event_sink(self, event_sink: Arc<dyn EventSink>) -> Self

Attach a CellOS EventSink for best-effort emission of warm-pool checkout CloudEvents.

When set, every create() call emits one dev.cellos.events.cell.firecracker.v1.pool_checkout event after consulting the warm pool, recording whether the boot took the snapshot fast path (poolHit) and the pre-checkout Available slot count. Emission failures are logged at warn and never abort VM creation — the audit event must not become a critical-path dependency.

pub fn config(&self) -> &FirecrackerConfig

pub async fn pool_size(&self) -> usize

Number of warm-pool slots configured (any state). Returns the value of CELLOS_FIRECRACKER_POOL_SIZE resolved at backend construction. Useful for the supervisor composition root to decide whether to spawn the background fill task at all.

pub async fn pool_available(&self) -> usize

Number of warm-pool slots currently in Available state (callable from tests to observe that a fill cycle has run).

pub async fn fill_pool(&self)

Drive one fill() cycle on the warm pool using the validated firecracker binary / kernel / rootfs paths from FirecrackerConfig.

Best-effort: per-slot failures are logged and leave the slot Empty (see pool::FirecrackerPool::fill). Intended to be called once at supervisor startup from a detached tokio::spawn so that subsequent create() calls can take the fast snapshot-restore path.

pub async fn tracked_vm_count(&self) -> usize

Number of VMs the backend currently tracks (for tests and operators).

pub async fn wait_for_command_exit( &self, cell_id: &str, ) -> Result<i32, CellosError>

Wait until cellos-init inside the VM reports the cell command’s exit code over vsock, then return it.

Returns Err if the cell is not tracked or the vsock channel closes before the exit code arrives. The lock is released before awaiting, so other operations on the backend can proceed concurrently.

Trait Implementations

impl CellBackend for FirecrackerCellBackend

fn create<'life0, 'life1, 'async_trait>( &'life0 self, spec: &'life1 ExecutionCellDocument, ) -> Pin<Box<dyn Future<Output = Result<CellHandle, CellosError>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

Boot a Firecracker microVM for the cell.

The VM is configured with the image paths from FirecrackerConfig. If spec.environment.imageDigest is set it is recorded but not yet verified by this crate (digest verification is a future L2-06 milestone).

fn wait_for_in_vm_exit<'life0, 'life1, 'async_trait>( &'life0 self, cell_id: &'life1 str, ) -> Pin<Box<dyn Future<Output = Option<Result<i32, CellosError>>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

Wait for cellos-init inside the VM to report the cell command’s exit code over vsock, then return it.

This overrides the default None so the supervisor skips its host-side run_cell_command path and waits for the in-VM result instead.

fn destroy<'life0, 'life1, 'async_trait>( &'life0 self, handle: &'life1 CellHandle, ) -> Pin<Box<dyn Future<Output = Result<TeardownReport, CellosError>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

Gracefully shut down the Firecracker VM, then SIGKILL if it does not exit within the cell’s graceful-shutdown window.

The window is the per-spec run.limits.gracefulShutdownSeconds (FC-21), captured into [VmRecord::graceful_shutdown_timeout] at create(), or [GRACEFUL_SHUTDOWN_TIMEOUT] when the spec omits the field.