Skip to main content

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}