cellos_host_gvisor/lib.rs
1//! gVisor [`CellBackend`] — uses `runsc`, the gVisor OCI runtime, to isolate
2//! a cell without `/dev/kvm`.
3//!
4//! L2-06-5 status: **skeleton**.
5//!
6//! This backend is targeted at environments where a hardware-virt backend
7//! (Firecracker) is unavailable — primarily GKE pods (KVM is gated behind the
8//! `kvm` feature flag, and nested virt is paid) and a subset of CI runners
9//! (e.g. GitHub `ubuntu-latest` without `/dev/kvm` exposed). gVisor's
10//! user-mode kernel (`runsc`) intercepts the workload's syscalls and provides
11//! a defence-in-depth boundary that Linux namespaces alone do not.
12//!
13//! ## Scope of the skeleton
14//!
15//! The OCI bundle generator and the command-line plumbing for `runsc run` /
16//! `runsc kill` / `runsc delete` are stubs that:
17//!
18//! 1. translate an [`ExecutionCellDocument`] into the on-disk pieces `runsc`
19//! expects (bundle directory containing `config.json` and a `rootfs/`),
20//! 2. shell out to `runsc` with the documented argument shape,
21//! 3. wait for the container process to exit and surface its exit code.
22//!
23//! The skeleton is **unit-tested for the bundle generator** (pure function,
24//! no `runsc` required) and is gated behind `#[cfg(target_os = "linux")]`
25//! because:
26//!
27//! - `runsc` is Linux-only (it relies on `ptrace`/`KVM`/`systrap` switches
28//! that exist nowhere else),
29//! - the OCI runtime spec referenced in `config.json` uses Linux namespaces
30//! directly, so a portable stub would lie about what the backend does.
31//!
32//! On non-Linux hosts the crate compiles to an empty surface so downstream
33//! workspace crates can still `use cellos_host_gvisor::*;` in
34//! `cfg(target_os = "linux")` blocks without breaking macOS/dev builds.
35
36#![forbid(unsafe_code)]
37
38// Re-export the bundle generator at the crate root so it is reachable from
39// host-independent unit tests on every platform. Everything that talks to a
40// real `runsc` binary lives behind `#[cfg(target_os = "linux")]` below.
41mod bundle;
42
43pub use bundle::{generate_bundle_config, BundleConfig, BundleConfigError};
44
45#[cfg(target_os = "linux")]
46mod backend;
47
48#[cfg(target_os = "linux")]
49pub use backend::GVisorCellBackend;