hyprstream_workers/runtime/backend.rs
1//! SandboxBackend trait — pluggable sandbox runtime abstraction
2//!
3//! Extracts the VM lifecycle out of `SandboxPool` so multiple backends
4//! (Kata, systemd-nspawn, etc.) can provide sandbox isolation.
5//!
6//! ## #508 / #635 — narrowing in progress
7//!
8//! Epic #508 converges worker sandboxing onto a "namespace IS the OS surface,
9//! backends-as-transport" model: a `SandboxBackend` boots a guest OS under an
10//! isolation boundary and delivers the composed [`Namespace`] to it — it does
11//! NOT own image-pull or run commands. [`deliver_namespace`](SandboxBackend::deliver_namespace)
12//! is the narrowed method this trait is converging on.
13//!
14//! The CRI-shaped methods below (`exec_sync`/`supports_exec`, the
15//! `PodSandboxConfig`-driven image pull implicit in `start`, and
16//! `update_resources`'s `LinuxContainerResources`) are kept on the trait for
17//! now and marked **TRANSITIONAL**: they move off once the guest-OS
18//! control-file service (kata-agent #344, Wanix `/task` #612) and the
19//! universal filesystem-service Mount (#633/#641) are both wired end-to-end.
20//! Until then, removing them here would break every existing caller
21//! (`SandboxPool`, `ExecMount`, CRI-facing worker RPCs) for no working
22//! replacement. See issue #635 for the full narrowing rationale.
23use std::any::Any;
24use std::collections::HashMap;
25use std::path::PathBuf;
26use std::sync::Arc;
27
28use async_trait::async_trait;
29
30use crate::config::PoolConfig;
31use crate::error::Result;
32
33use super::sandbox::PodSandbox;
34use hyprstream_rpc_std::worker_client::{
35 CpuUsage, LinuxContainerResources, MemoryUsage, PodSandboxConfig,
36};
37use hyprstream_vfs::{Namespace, Subject};
38
39/// Opaque handle stored on each `PodSandbox`.
40///
41/// Backends stash runtime-specific state (hypervisor handles, PIDs, machine
42/// names, …) here. Callers can downcast via `as_any()` when they know the
43/// concrete type.
44pub trait SandboxHandle: Send + Sync + std::fmt::Debug {
45 fn as_any(&self) -> &dyn Any;
46}
47
48/// How a composed [`Namespace`] should be attached to a booted guest.
49///
50/// Designed to fit Kata's existing virtio-fs/ShareFs delivery today, and to
51/// be extensible to #653's local-FUSE-mount serve mode once it lands (a
52/// `BindMount` target can point at a FUSE mountpoint just as well as a plain
53/// directory — this enum does not need to change for that).
54#[derive(Debug, Clone)]
55pub enum NamespaceTransport {
56 /// Serve the namespace over a vhost-user-fs (virtio-fs) socket. The guest
57 /// mounts it via a ShareFs/virtio-fs device tagged `mount_tag`. This is
58 /// Kata's transport.
59 VirtioFs {
60 /// Host-side socket path the backend should serve the namespace on
61 /// (or has already served it on — backend-specific).
62 socket_path: PathBuf,
63 /// The virtio-fs mount tag the guest uses to identify the share.
64 mount_tag: String,
65 },
66 /// The namespace is (or will be) materialized at a host directory the
67 /// guest can see directly — a plain bind-mount for backends that don't
68 /// need FUSE (e.g. nspawn), or a #653 local-FUSE mountpoint once that
69 /// lands.
70 BindMount {
71 /// Host-side directory to bind/attach into the guest.
72 target: PathBuf,
73 },
74 /// Pass mount references directly into the guest's in-process
75 /// environment rather than over any wire transport — the wasm
76 /// host-imports path (no separate guest OS to mount into).
77 HostImports,
78 /// Deliver the composed namespace over authenticated network 9P and mount it
79 /// in a scheduler-placed Kubernetes pod through `csi.hyprstream.io` (#793).
80 ///
81 /// `endpoint` is the dial-time carrier endpoint selected by the operator
82 /// (normally iroh/QUIC-WebTransport cross-node, vsock for Kata, UDS only
83 /// co-located). The CSI node plugin mints the scoped #862 mount ticket at
84 /// `NodePublishVolume` via Kubernetes CSI `tokenRequests`, so no bearer
85 /// ticket is persisted in the PodSpec. `aname` is the Plan 9 attach name
86 /// selecting the authorized export root; filesystem paths are walked after
87 /// attach inside that root.
88 NineP {
89 endpoint: String,
90 aname: String,
91 plane: String,
92 mounter: String,
93 mount_path: PathBuf,
94 },
95}
96
97/// Result of [`SandboxBackend::deliver_namespace`]: what's now available for
98/// the guest to consume, and any transitional bookkeeping the caller needs.
99pub enum NamespaceDelivery {
100 /// The namespace is being served over a vhost-user-fs socket.
101 VirtioFs {
102 socket_path: PathBuf,
103 mount_tag: String,
104 /// Backend-specific guard object that must be kept alive for as long
105 /// as the guest needs this mount (e.g. the thread serving the
106 /// socket). Opaque to callers that don't need the concrete type —
107 /// dropping it early may tear down the serving thread/socket, just
108 /// like dropping a `SandboxHandle` early would. `None` when the
109 /// backend needs no such guard.
110 guard: Option<Arc<dyn Any + Send + Sync>>,
111 },
112 /// The namespace is available at this host path.
113 BindMount { target: PathBuf },
114 /// The namespace was imported directly into the guest's environment.
115 HostImports,
116 /// The namespace is represented as a `csi.hyprstream.io` pod volume.
117 NineP {
118 endpoint: String,
119 aname: String,
120 plane: String,
121 mounter: String,
122 mount_path: PathBuf,
123 },
124}
125
126impl std::fmt::Debug for NamespaceDelivery {
127 fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
128 match self {
129 Self::VirtioFs {
130 socket_path,
131 mount_tag,
132 ..
133 } => f
134 .debug_struct("VirtioFs")
135 .field("socket_path", socket_path)
136 .field("mount_tag", mount_tag)
137 .finish_non_exhaustive(),
138 Self::BindMount { target } => {
139 f.debug_struct("BindMount").field("target", target).finish()
140 }
141 Self::HostImports => write!(f, "HostImports"),
142 Self::NineP {
143 endpoint,
144 aname,
145 plane,
146 mounter,
147 mount_path,
148 ..
149 } => f
150 .debug_struct("NineP")
151 .field("endpoint", endpoint)
152 .field("aname", aname)
153 .field("plane", plane)
154 .field("mounter", mounter)
155 .field("mount_path", mount_path)
156 .finish_non_exhaustive(),
157 }
158 }
159}
160
161/// Pluggable sandbox runtime backend.
162///
163/// Implementors manage the full sandbox lifecycle: create → start → stop →
164/// destroy. The pool calls these methods and stores the returned
165/// `SandboxHandle` on the `PodSandbox`.
166#[async_trait]
167pub trait SandboxBackend: Send + Sync {
168 /// Human-readable backend name (e.g. `"kata"`, `"nspawn"`).
169 fn backend_type(&self) -> &'static str;
170
171 /// Check whether the backend's runtime dependencies are available.
172 fn is_available(&self) -> bool;
173
174 /// One-time initialisation (verify paths, enable rootless mode, …).
175 async fn initialize(&self, config: &PoolConfig) -> Result<()>;
176
177 /// Start a sandbox and return the backend-specific handle.
178 // TRANSITIONAL (#635): `config: &PodSandboxConfig` is the CRI-shaped
179 // image-pull/pod config. Once the universal filesystem-service Mount
180 // (#633/#641) owns image resolution end-to-end, `start` should narrow to
181 // "boot a guest OS", with image content arriving via `deliver_namespace`
182 // instead of being resolved here. Not touched in #635 to avoid breaking
183 // every existing caller before that replacement is wired.
184 async fn start(
185 &self,
186 sandbox: &mut PodSandbox,
187 config: &PodSandboxConfig,
188 pool_config: &PoolConfig,
189 annotations: &HashMap<String, String>,
190 ) -> Result<Arc<dyn SandboxHandle>>;
191
192 /// Gracefully stop a running sandbox.
193 async fn stop(&self, sandbox: &PodSandbox) -> Result<()>;
194
195 /// Destroy a sandbox and clean up all resources.
196 async fn destroy(&self, sandbox: &PodSandbox) -> Result<()>;
197
198 /// Reset a sandbox for warm-pool reuse.
199 ///
200 /// Returns `true` if the sandbox can be reused in-place (e.g. Kata keeps
201 /// the VM running). Returns `false` if the sandbox is ephemeral and must
202 /// be recreated (e.g. nspawn).
203 async fn reset(&self, sandbox: &mut PodSandbox) -> Result<bool>;
204
205 /// Get PIDs belonging to this sandbox (for monitoring / cgroup ops).
206 async fn get_pids(&self, sandbox: &PodSandbox) -> Result<Vec<u32>>;
207
208 /// Deliver a composed [`Namespace`] to this sandbox's guest via
209 /// `transport` (#635 — the narrowed `SandboxBackend` surface epic #508 is
210 /// converging on).
211 ///
212 /// A backend's job here is exactly: attach `namespace` (already fully
213 /// composed — rootfs + injected mounts — by the caller; composition
214 /// itself is NOT this method's job) to the running/starting guest, using
215 /// whichever `transport` variant it supports. `subject` is the policy/
216 /// audit principal the namespace is served under (threaded into every VFS
217 /// op at the Mount boundary).
218 ///
219 /// Default: unsupported. Not every backend has been re-grounded onto this
220 /// method yet (see #617/#619/nspawn re-grounding, blocked on this issue);
221 /// backends that haven't should fail closed rather than silently no-op.
222 async fn deliver_namespace(
223 &self,
224 _sandbox: &PodSandbox,
225 _namespace: Namespace,
226 _subject: Subject,
227 _transport: NamespaceTransport,
228 ) -> Result<NamespaceDelivery> {
229 Err(crate::error::WorkerError::Unsupported(format!(
230 "{} backend does not implement deliver_namespace yet",
231 self.backend_type()
232 )))
233 }
234
235 /// Whether `exec_sync` is supported.
236 // TRANSITIONAL (#635): `exec_sync`/`supports_exec` are CRI-shaped
237 // ("run a command in the sandbox") and don't fit a guest with no
238 // "command" absent a guest OS (wasm Profile A). They move off this trait
239 // once the guest-OS control-file service (kata-agent #344, Wanix `/task`
240 // #612) is wired — commands will run *in the guest OS*, driven through a
241 // 9P control file, not through the backend directly. Kept here,
242 // unchanged, until that replacement exists end-to-end.
243 fn supports_exec(&self) -> bool;
244
245 /// Run a command synchronously inside the sandbox.
246 // TRANSITIONAL (#635): see `supports_exec` above — moves to the guest-OS
247 // control-file service once #344/#612 land.
248 async fn exec_sync(
249 &self,
250 sandbox: &PodSandbox,
251 command: &[String],
252 timeout_secs: u64,
253 ) -> Result<(i32, Vec<u8>, Vec<u8>)>;
254
255 /// Apply resource limits to a running sandbox (optional).
256 // TRANSITIONAL (#635): `LinuxContainerResources` is CRI-shaped. Moves to a
257 // resource-control file service / namespace node once that lands; kept as
258 // a trait method (with a no-op default) until then.
259 async fn update_resources(
260 &self,
261 _sandbox: &PodSandbox,
262 _resources: &LinuxContainerResources,
263 ) -> Result<()> {
264 Ok(()) // default: no-op
265 }
266
267 /// Fetch live per-container resource usage from the sandbox's guest.
268 ///
269 /// Returns `Some((cpu, memory))` sourced from inside the sandbox (e.g.
270 /// the kata-agent stats RPC / guest cgroups), or `None` when the backend
271 /// cannot observe the guest (default). Callers fall back to
272 /// placeholder/zeroed usage when this is `None`, so a backend that has no
273 /// in-guest visibility does not have to synthesise fake numbers.
274 async fn container_stats(
275 &self,
276 _sandbox: &PodSandbox,
277 ) -> Result<Option<(CpuUsage, MemoryUsage)>> {
278 Ok(None) // default: no guest-level stats available
279 }
280}