Skip to main content

hyprstream_workers/runtime/
mod.rs

1//! CRI runtime service implementation
2//!
3//! Provides Kubernetes CRI-aligned APIs for managing pod sandboxes (Kata VMs)
4//! and containers. PodSandbox maps to a Kata VM, Container to an OCI container
5//! within that VM.
6//!
7//! # Architecture
8//!
9//! ```text
10//! WorkerService (RequestService)
11//!     │
12//!     ├── canonical RuntimeClient contract (`hyprstream-rpc-std`)
13//!     │     ├── run_pod_sandbox()    → Creates Kata VM
14//!     │     ├── create_container()   → Creates container in VM
15//!     │     ├── start_container()    → Starts container
16//!     │     └── exec_sync()          → Executes command
17//!     │
18//!     └── SandboxPool
19//!           ├── Warm pool (pre-created VMs)
20//!           └── Active sandboxes
21//! ```
22
23// Admission control (#525 P2): fail-closed identity, per-Subject/per-group
24// quotas, bounded wait-queue, resource-aware fit over the #628 scheduling
25// substrate. Consumed by `pool::SandboxPool::acquire`.
26mod admission;
27pub mod backend;
28mod container;
29mod status;
30// CRI-client sandbox backend (#510) — gated behind `cri`. A tonic gRPC
31// client of an external, already-running CRI runtime service (containerd's
32// CRI plugin, or CRI-O) — the kubelet role, not an embedded runtime. Sibling
33// of `oci_backend` (which drives podman via CLI shell-out) under the same
34// SandboxBackend seam; does NOT replace `kata_backend` (embedded Kata stays).
35#[cfg(feature = "cri")]
36pub mod cri_backend;
37// Kubernetes API-server sandbox backend (#781, epic #778) — gated behind `k8s`.
38// A kube-rs client that emits real Pod/Job objects against the cluster API
39// server (scheduler-placed, quota'd, kubectl-visible), i.e. hyprstream as
40// orchestrator/client. Distinct from `cri_backend`, which drives a node's CRI
41// socket directly (shadow pods, same-node, invisible to Kubernetes). Off by
42// default so the lean build assumes no cluster.
43#[cfg(feature = "k8s")]
44pub mod k8s_backend;
45// `/exec/instances/` VFS projection of `SandboxPool` (#608 P2 / #610) — a
46// `hyprstream_vfs::Mount` impl, so it has no `kata-vm`/`wasm` dependency.
47pub mod exec_mount;
48// Kata/CH VM backend — gated behind `kata` (pulls the kata/nydus toolchain).
49// `kata-vm` is a backward-compat alias for `kata` (#518).
50#[cfg(feature = "kata")]
51pub mod kata_backend;
52// kata-agent ttrpc/vsock client (#344): CreateContainer/StartContainer/
53// ExecProcess/WaitProcess against the guest's kata-agent. Used by
54// `kata_backend::KataBackend::exec_sync`.
55#[cfg(feature = "kata")]
56pub mod kata_agent;
57// systemd-nspawn lightweight-container backend (#518: per-BackendType feature).
58// The lowest-isolation auto-selectable tier; torch-free, no heavy deps.
59#[cfg(feature = "nspawn")]
60pub mod nspawn;
61// Rootless OCI container backend (#346) — gated behind `oci`. Drives a rootless
62// OCI runtime (podman by default) via CLI shell-out; torch-free, no VM toolchain.
63// A subprocess sibling of nspawn under the SandboxBackend seam. Off by default so
64// the lean build doesn't assume a container runtime is installed.
65#[cfg(feature = "oci")]
66pub mod oci_backend;
67mod pool;
68mod sandbox;
69// In-process WebAssembly sandbox backend (#505 P2) — gated behind `wasm`
70// (pulls the wasmtime-bearing `hyprstream-workers-wasmtime` substrate). A native in-process
71// sibling under the SandboxBackend seam; the default build stays lean + torch-free.
72#[cfg(feature = "wasm")]
73pub mod wasm_backend;
74// Per-sandbox VFS composition + serve (FS-D, #365): composes the image Mount +
75// injected mounts into a Namespace and serves it over vhost-user-fs. Needs the
76// image filesystem service (`oci-image`) but NOT the VM toolchain, so any
77// backend that hands a guest a composed 9P/VFS namespace consumes it (#632).
78#[cfg(all(not(target_arch = "wasm32"), feature = "oci-image"))]
79pub mod sandbox_fs;
80// Canonical backend taxonomy + fail-closed selection (Phase 0 of #508, #507).
81pub mod selection;
82mod service;
83pub mod spawner;
84// Wanix-guest workload wiring (#506 deliverable 3): allocate a per-workload UDS,
85// serve a tenant's Subject-scoped VFS `Mount` as 9P2000.L over it, and inject the
86// socket + env into a sandbox so the native Wanix guest dials back. Native only
87// (needs tokio `net` for the 9P UDS server).
88#[cfg(not(target_arch = "wasm32"))]
89pub mod wanix_workload;
90
91// Wire clients and data types are intentionally not re-exported from this
92// service crate. `StatusResponse` is the one local composite retained here.
93pub use status::StatusResponse;
94// Backend trait and implementations
95pub use backend::{SandboxBackend, SandboxHandle};
96#[cfg(feature = "cri")]
97pub use cri_backend::{CriBackend, CriConfig, CriHandle};
98// `/exec/instances/` Plan9 projection of the pool (#608 P2 / #610)
99pub use exec_mount::ExecMount;
100#[cfg(feature = "kata")]
101pub use kata_backend::{KataBackend, KataHandle};
102#[cfg(feature = "nspawn")]
103pub use nspawn::{NspawnBackend, NspawnConfig, NspawnHandle};
104#[cfg(feature = "oci")]
105pub use oci_backend::{OciBackend, OciConfig, OciHandle};
106#[cfg(feature = "wasm")]
107pub use wasm_backend::{WasmBackend, WasmConfig, WasmHandle};
108// Inventory-based backend registry + fail-closed selection spine (#507)
109pub use selection::{
110    backend_injects_9p_socket, require_9p_socket_capability, require_fuse_mount_capability,
111    resolve_backend, resolve_backend_9p_capable, BackendCtx, BackendRegistration,
112};
113// Scheduling-substrate explain (#628): the shared SelectionReport<C> trace.
114pub use selection::{explain_selection, BackendCandidate};
115// Domain entities (business logic only)
116pub use container::Container;
117pub use pool::{PoolStats, SandboxPool};
118pub use sandbox::PodSandbox;
119// Admission control (#525 P2) — quota/queue configuration + the request
120// annotations it reads (GPU count demand, group key).
121pub use admission::{
122    AdmissionConfig, DenyUnknownGroupValidator, GroupSelectorValidator, StaticGroupMembership,
123    ANN_GPU_REQUEST, ANN_GROUP,
124};
125#[cfg(all(not(target_arch = "wasm32"), feature = "oci-image"))]
126pub use sandbox_fs::{
127    InjectedMounts, SandboxFs, SandboxFsLocalMount, SandboxFsServer, VFS_SOCKET_NAME,
128};
129pub use service::WorkerService;
130#[cfg(not(target_arch = "wasm32"))]
131pub use wanix_workload::{
132    import_guest_namespace, inject_9p_socket, ImportedGuestNamespace, Injected9pServer,
133    WanixGuestConfig, WanixInjection, ANN_WANIX_COMMAND, ENV_9P_SOCK, ENV_GUEST_EXPORT_SOCK,
134};
135// Re-export service infrastructure from hyprstream-rpc for convenience
136pub use hyprstream_rpc::service::{EnvelopeContext, RequestService, ServiceHandle};
137
138/// CRI runtime version
139pub const RUNTIME_VERSION: &str = "0.1.0";
140
141/// CRI runtime name
142pub const RUNTIME_NAME: &str = "hyprstream-workers";