Struct DockerBackend 

pub struct DockerBackend { /* private fields */ }

The remote-Docker compute backend: a connected Engine API client.

Implementations

impl DockerBackend

pub fn connect() -> Result<Self, BackendError>

Connect to the Docker daemon configured by the environment (DOCKER_HOST + TLS/SSH vars, or the platform default socket).

pub fn with_client(docker: Docker) -> Self

Wrap an already-connected client (for tests / custom transports).

pub fn with_endpoint(self, endpoint: DockerEndpoint) -> Self

Select how a launched workload’s endpoint is reported (see DockerEndpoint).

pub fn with_writable_root_allowed(self, allowed: bool) -> Self

Allow a spec’s writable_root to relax the read-only root here (single-tenant posture). Off by default, so the multi-tenant guard keeps the hardened root.

pub fn with_cap_add_allowed(self, allowed: bool) -> Self

Allow a spec’s cap_add to add capabilities back on top of the dropped-ALL default here (single-tenant posture). Off by default, so the multi-tenant guard keeps every capability dropped.

pub fn with_volume_mode(self, mode: DockerVolumeMode) -> Self

Select how persistent volumes are backed (see DockerVolumeMode).

pub fn with_data_dir(self, data_dir: impl Into<PathBuf>) -> Self

Set the node data directory used for Bind-mode volume host paths.

pub async fn reachable(&self) -> bool

Whether the daemon answers a ping — used to decide whether to register this backend (a connected client doesn’t imply a reachable daemon).

Trait Implementations

impl ComputeBackend for DockerBackend

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 the running container via the Engine exec API and buffer its output. argv is the command + args (no shell); stdin, when present, is written to the command’s standard input and the stream is then half-closed so the command sees EOF. stdout/stderr are captured to completion, and the command’s exit status is read back from inspect_exec after the output stream ends.

The container name is the one encoded in the handle (falling back to the deterministic boatramp-<workload>-<replica>, mirroring health/stop).

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.

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 'life0: 'async_trait, 'life1: 'async_trait, Self: '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 'life0: 'async_trait, 'life1: 'async_trait, Self: '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 'life0: 'async_trait, 'life1: 'async_trait, Self: '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 'life0: 'async_trait, 'life1: 'async_trait, Self: 'async_trait,

Restore a snapshotted replica.

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

where 'life0: 'async_trait, Self: '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 'life0: 'async_trait, 'life1: 'async_trait, Self: '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}.