Trait ComputeBackend 

pub trait ComputeBackend: Send + Sync {
    // Required methods
    fn id(&self) -> &'static str;
    fn capabilities(&self) -> Capabilities;
    fn materialize<'life0, 'life1, 'async_trait>(
        &'life0 self,
        spec: &'life1 ComputeSpec,
    ) -> Pin<Box<dyn Future<Output = Result<Artifact, BackendError>> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait,
             'life1: 'async_trait;
    fn launch<'life0, 'life1, 'async_trait>(
        &'life0 self,
        req: &'life1 LaunchRequest,
    ) -> Pin<Box<dyn Future<Output = Result<Instance, BackendError>> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait,
             'life1: 'async_trait;
    fn stop<'life0, 'life1, 'async_trait>(
        &'life0 self,
        handle: &'life1 InstanceHandle,
    ) -> Pin<Box<dyn Future<Output = Result<(), BackendError>> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait,
             'life1: 'async_trait;
    fn health<'life0, 'life1, 'async_trait>(
        &'life0 self,
        handle: &'life1 InstanceHandle,
    ) -> Pin<Box<dyn Future<Output = Result<Health, BackendError>> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait,
             'life1: 'async_trait;

    // Provided methods
    fn reserve_in_use<'life0, 'life1, 'async_trait>(
        &'life0 self,
        _replicas: &'life1 [(String, String, u32, Ipv4Addr)],
    ) -> Pin<Box<dyn Future<Output = ()> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait,
             'life1: 'async_trait { ... }
    fn gc_ip_pool<'life0, 'life1, 'async_trait>(
        &'life0 self,
        _parked: &'life1 [(String, String, u32)],
    ) -> Pin<Box<dyn Future<Output = ()> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait,
             'life1: 'async_trait { ... }
    fn snapshot<'life0, 'life1, 'async_trait>(
        &'life0 self,
        _handle: &'life1 InstanceHandle,
    ) -> Pin<Box<dyn Future<Output = Result<Option<Snapshot>, BackendError>> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait,
             'life1: 'async_trait { ... }
    fn restore<'life0, 'life1, 'async_trait>(
        &'life0 self,
        _snapshot: &'life1 Snapshot,
    ) -> Pin<Box<dyn Future<Output = Result<Instance, BackendError>> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait,
             'life1: 'async_trait { ... }
    fn exec<'life0, 'life1, 'life2, 'life3, 'async_trait>(
        &'life0 self,
        _handle: &'life1 InstanceHandle,
        _argv: &'life2 [String],
        _stdin: Option<&'life3 [u8]>,
    ) -> Pin<Box<dyn Future<Output = Result<ExecOutput, BackendError>> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait,
             'life1: 'async_trait,
             'life2: 'async_trait,
             'life3: 'async_trait { ... }
    fn list_volumes<'life0, 'async_trait>(
        &'life0 self,
    ) -> Pin<Box<dyn Future<Output = Result<Vec<VolumeInfo>, BackendError>> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait { ... }
    fn remove_volume<'life0, 'life1, 'async_trait>(
        &'life0 self,
        _name: &'life1 str,
    ) -> Pin<Box<dyn Future<Output = Result<bool, BackendError>> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait,
             'life1: 'async_trait { ... }
}

Required Methods

fn id(&self) -> &'static str

Stable backend id ("vmm" / "container" / "cloudflare" / "docker").

fn capabilities(&self) -> Capabilities

What this backend can do here (used by the scheduler + policy gate).

fn materialize<'life0, 'life1, 'async_trait>( &'life0 self, spec: &'life1 ComputeSpec, ) -> Pin<Box<dyn Future<Output = Result<Artifact, BackendError>> + Send + 'async_trait>>

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

Stage spec’s artifact into whatever this backend boots from. Idempotent + content-addressed (cache/dedup by spec id).

fn launch<'life0, 'life1, 'async_trait>( &'life0 self, req: &'life1 LaunchRequest, ) -> Pin<Box<dyn Future<Output = Result<Instance, BackendError>> + Send + 'async_trait>>

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

Launch one replica; returns its handle + routable endpoint.

fn stop<'life0, 'life1, 'async_trait>( &'life0 self, handle: &'life1 InstanceHandle, ) -> Pin<Box<dyn Future<Output = Result<(), BackendError>> + Send + 'async_trait>>

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

Stop + clean up a replica (idempotent; safe on a half-launched instance).

fn health<'life0, 'life1, 'async_trait>( &'life0 self, handle: &'life1 InstanceHandle, ) -> Pin<Box<dyn Future<Output = Result<Health, BackendError>> + Send + 'async_trait>>

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

Liveness/readiness of a running replica.

Provided Methods

fn reserve_in_use<'life0, 'life1, 'async_trait>( &'life0 self, _replicas: &'life1 [(String, String, u32, Ipv4Addr)], ) -> Pin<Box<dyn Future<Output = ()> + Send + 'async_trait>>

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

Adopt the guest IPs already assigned to persisted/running replicas of this backend, so a fresh-on-boot IP pool reflects addresses in use before it hands out any new one. Called once at node startup with every known replica as (project, workload, replica, endpoint_ip); the backend reserves the ones it owns (those in its own subnet), skipping the rest, and remembers each replica’s address — keyed by (project, workload, replica) so two projects’ same-named workloads never share a slot — so a relaunch reclaims the same endpoint (stable) rather than a fresh one. Without this a backend that rebuilds its pool each process start (the native container backend) could re-hand a live address to a different workload — the container-IP collision. Backends that don’t own a per-node IP pool (docker / cloudflare delegate addressing) default to a no-op, so they are unaffected.

fn gc_ip_pool<'life0, 'life1, 'async_trait>( &'life0 self, _parked: &'life1 [(String, String, u32)], ) -> Pin<Box<dyn Future<Output = ()> + Send + 'async_trait>>

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

Reconcile the IP pool against reality (A2): reclaim addresses this backend still holds for replicas whose container is actually gone. Adoption reserves the IP of every persisted replica at boot; a replica whose container has since crashed (or whose state was removed out-of-band) would otherwise keep its IP reserved for the life of the process, slowly leaking the pool. This is called periodically with parked — the (project, workload, replica) keys that are intentionally down (scale-to-zero Zero) and MUST keep their IP for the wake — so the backend releases only the addresses it holds for a key that is neither live (no running container) nor parked. Backends without a per-node IP pool default to a no-op. Conservative by construction: a key is reclaimed only when the backend is sure the container is gone.

fn snapshot<'life0, 'life1, 'async_trait>( &'life0 self, _handle: &'life1 InstanceHandle, ) -> Pin<Box<dyn Future<Output = Result<Option<Snapshot>, BackendError>> + Send + 'async_trait>>

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

Snapshot a replica for scale-to-zero (backends that support it).

fn restore<'life0, 'life1, 'async_trait>( &'life0 self, _snapshot: &'life1 Snapshot, ) -> Pin<Box<dyn Future<Output = Result<Instance, BackendError>> + Send + 'async_trait>>

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

Restore a snapshotted replica.

fn exec<'life0, 'life1, 'life2, 'life3, 'async_trait>( &'life0 self, _handle: &'life1 InstanceHandle, _argv: &'life2 [String], _stdin: Option<&'life3 [u8]>, ) -> Pin<Box<dyn Future<Output = Result<ExecOutput, BackendError>> + Send + 'async_trait>>

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

Run a one-shot command inside a running replica (docker-exec style) and return its buffered output — for operator ops (migrations, pg_dump, debug). stdin is fed to the command’s standard input when present. Only the shared-kernel backends that can re-enter a running container implement it (native container via setns, remote docker via the exec API); the VM/edge backends return BackendError::Unsupported. The caller gates this behind the allow_compute_exec security posture.

fn list_volumes<'life0, 'async_trait>( &'life0 self, ) -> Pin<Box<dyn Future<Output = Result<Vec<VolumeInfo>, BackendError>> + Send + 'async_trait>>

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

List this backend’s persistent volumes (the host-side backing for a spec’s VolumeRefs). Only the backends that own an on-node volume directory implement it (the native container backend, under <data_dir>/compute/volumes/<name>); the rest return the empty default, so a listing across a mixed fleet simply omits them. Backs the operator GET /api/compute/volumes volume-reclamation surface.

fn remove_volume<'life0, 'life1, 'async_trait>( &'life0 self, _name: &'life1 str, ) -> Pin<Box<dyn Future<Output = Result<bool, BackendError>> + Send + 'async_trait>>

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

Remove the backing for persistent volume name, returning whether it existed. Only the backends that own an on-node volume directory implement it (native container); the rest return BackendError::Unsupported. The caller (the node volume capability) refuses to remove a volume still referenced by a registered workload’s spec unless forced — see ComputeVolumes. Backs DELETE /api/compute/volumes/{name}.

Dyn Compatibility

This trait is dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety".

Implementors