Skip to main content

cellos_host_windows/
lib.rs

1//! Windows [`cellos_core::ports::CellBackend`] — isolates a cell in a Windows
2//! **Job Object** for hosts where the Linux-only backends (Firecracker, gVisor)
3//! cannot run.
4//!
5//! ## What a Job Object gives us
6//!
7//! A [Job Object](https://learn.microsoft.com/windows/win32/procthread/job-objects)
8//! is the closest Windows analogue to a cgroup-v2 leaf: a kernel object that
9//! owns a set of processes and enforces aggregate limits over them. This
10//! backend creates one job per cell and uses it for three things:
11//!
12//! 1. **Process-tree containment** — the workload and every descendant it
13//!    spawns are members of the job, so teardown is a single kernel call that
14//!    cannot leak orphans.
15//! 2. **Resource caps** — `spec.run.limits.memoryMaxBytes` maps to a job-wide
16//!    `JOB_OBJECT_LIMIT_JOB_MEMORY` cap, and `spec.run.limits.cpuMax` maps to a
17//!    hard CPU-rate cap (`JOBOBJECT_CPU_RATE_CONTROL_INFORMATION`).
18//! 3. **Residue-free teardown** — the job is created with
19//!    `JOB_OBJECT_LIMIT_KILL_ON_JOB_CLOSE`, so closing the last handle (or an
20//!    explicit `TerminateJobObject` in `destroy`) kills everything still inside.
21//!
22//! ## Honest scope (v1)
23//!
24//! A Job Object is **process-level containment, not a virtualization boundary.**
25//! It does not provide a separate kernel, syscall emulation, a filesystem mount
26//! namespace, or network-egress enforcement. Its isolation strength is in the
27//! same tier as the Linux proprietary (`cellos-host-cellos`) cgroup-only
28//! backend — weaker than gVisor (`runsc`) and far weaker than a Firecracker
29//! microVM. Operators who need a hardware/syscall boundary must run the cell on
30//! a Linux host with `CELLOS_CELL_BACKEND=firecracker` (or `gvisor`).
31//!
32//! Two limitations are enforced **fail-closed** rather than silently ignored:
33//!
34//! - **Network egress is not enforced.** Windows has no `nft` equivalent wired
35//!   here, so a spec that declares `authority.egressRules` gets a prominent
36//!   per-cell warning. `CellHandle.nft_rules_applied` is always `None`.
37//! - **`secretDelivery: env` is refused** when the spec also declares
38//!   `secretRefs`. This backend *owns execution* (it spawns the workload
39//!   itself), so the supervisor's host-subprocess env-injection path is
40//!   bypassed; rather than run the workload without its secrets, `create`
41//!   returns `InvalidSpec`. Use a broker-socket delivery mode (the default,
42//!   `runtimeLeasedBroker`) where the child fetches secrets over a socket.
43//!
44//! ## Platform gating
45//!
46//! The real implementation (`backend`, `job`) is compiled only on Windows. On
47//! every other target the crate exposes a small stub `WindowsCellBackend` whose
48//! `CellBackend` methods return a clear `Host` error, so `cargo check
49//! --workspace` and `cargo doc` stay green on Linux/macOS.
50
51#[cfg(windows)]
52mod backend;
53#[cfg(windows)]
54mod job;
55
56#[cfg(windows)]
57pub use backend::WindowsCellBackend;
58
59#[cfg(not(windows))]
60mod stub;
61#[cfg(not(windows))]
62pub use stub::WindowsCellBackend;