Skip to main content

Module selection

Module selection 

Source
Expand description

Inventory-based sandbox backend registry + fail-closed selection (#507).

This is the spine of the unified sandbox taxonomy: one SandboxBackend seam, one selection model shared by every call site (no per-site ad-hoc match with a silent _ => nspawn catch-all).

Backends are not a hardcoded enum. Each concrete backend self-registers a BackendRegistration via inventory::submit! next to its implementation, feature-gated by the #[cfg] that compiles that backend in (#518). The registry is therefore exactly the set of backends built into this binary:

  • nspawn — registered only under the nspawn feature (systemd-nspawn lightweight container).
  • kata — registered only under the kata feature (full VM isolation; kata-vm is a backward-compat alias for kata).
  • oci — registered only under the oci feature (rootless OCI/podman container, #346).
  • wasm — registered only under the wasm feature (in-process WebAssembly, explicit-name-only).
  • cri — registered only under the cri feature (#510: a gRPC client of an external, already-running CRI runtime service — containerd’s CRI plugin, or CRI-O — not an embedded runtime). Explicit-name-only, like wasm: driving an external runtime is an auth-surface decision "auto" must never reach for on its own.

YAGNI: still-speculative tiers are intentionally not registered. They gain a submit! when their phase actually builds them; until then they simply do not exist as selectable names (an explicit request errors).

Selection is config-driven via worker.backend (a string: a registered backend name, or "auto"):

  • "auto" → among registrations that are auto_selectable, pick the highest-priority one whose is_available probe passes. The choice is logged. If none qualifies, error — never run a workload without isolation, and never auto-pick a backend that opted out of auto-selection (a silent isolation downgrade; see the in-process wasm tier, #547 ZSP).
  • a concrete name → that registration, iff it is registered and its prerequisites are present. Otherwise error. We never substitute a different (weaker) backend (the #486 fail-open bug). An explicit name resolves regardless of auto_selectable, so an auto-excluded backend (e.g. wasm) is still reachable when deliberately requested by name.

The cardinal rule is fail-closed: an unavailable or unknown backend returns an error, never a silent downgrade to weaker isolation.

Structs§

BackendCandidate
A cloneable projection of a BackendRegistration for the substrate’s generic pipeline (SelectionReport<C> requires C: Clone; a registration holds fn pointers and is not cloneable). Carries exactly what selection filtering, ranking, and the explain trace need.
BackendCtx
Per-call construction context threaded to a backend’s construct fn.
BackendRegistration
A compile-time sandbox-backend registration, collected via inventory.

Functions§

backend_injects_9p_socket
Does the registered backend named backend_type advertise 9P socket injection? Returns false for an unknown/unregistered name.
explain_selection
Explain what "auto" selection would decide over the compiled-in registry, as the shared SelectionReport. The winning candidate is the highest- priority backend that is both auto-eligible and available; every other candidate carries the RejectionReason that excluded it.
require_9p_socket_capability
Fail-closed guard used at the workload seam: error unless backend_type advertises 9P socket injection (#506).
require_fuse_mount_capability
Fail-closed gate for Model B (#715): assert backend_type advertises the mounts_fuse_vfs capability before a caller FUSE-mounts the composed tenant VFS as that backend’s root.
resolve_backend
Resolve worker.backend to a constructed SandboxBackend, fail-closed.
resolve_backend_9p_capable
Resolve worker.backend to a SandboxBackend that is guaranteed capable of 9P socket injection (#506), fail-closed.