hyprstream_workers/runtime/wanix_workload.rs
1//! Wanix-guest workload wiring (#506, deliverable 3).
2//!
3//! This is the OCI/nspawn analog of the kata/virtio-fs path in
4//! [`super::sandbox_fs`] (FS-D, #365). Where `sandbox_fs` composes a per-sandbox
5//! Subject-scoped VFS [`Namespace`](hyprstream_vfs::Namespace) and serves it over
6//! a **vhost-user-fs** socket that a Cloud-Hypervisor guest attaches as a
7//! virtio-fs device, this module serves a tenant's Subject-scoped [`Mount`] as a
8//! **wire-faithful 9P2000.L server over a plain Unix socket** (PR-A's
9//! [`hyprstream_9p::serve_mount_uds`]) and injects that socket into a
10//! *bind-mount-capable* sandbox (OCI/nspawn) so the native Wanix guest (PR-B's
11//! `workers/wanix-guest`) dials back and binds the export as its namespace root.
12//!
13//! ## Bidirectional 9P (#708 phase 2)
14//!
15//! The above is **Direction A** — the host exports its namespace, the guest
16//! imports it. This module also wires **Direction B**, the reverse: the native
17//! Wanix guest exports its OWN live namespace over a *second, independent* UDS,
18//! and the host imports it via the phase-1 socket 9P client
19//! [`Remote9pMount`](hyprstream_9p::Remote9pMount) and binds it into the host
20//! VFS [`Namespace`] at `/workers/<tenant>/wanix` — giving the host visibility
21//! into the guest's task tree.
22//!
23//! [`inject_9p_socket`] allocates the export path and injects it (a shared
24//! export *directory* bind-mount + [`ENV_GUEST_EXPORT_SOCK`], mirroring the
25//! Direction-A socket injection). After the sandbox starts,
26//! [`import_guest_namespace`] dials the guest's export socket and binds the
27//! imported tree. The two directions are **independent** — separate sockets,
28//! separate 9P sessions, no shared coupling (#708).
29//!
30//! **Scope + payoff caveat.** This is wired for the shared-FS UDS backends
31//! (OCI/nspawn); a kata guest would export over vsock (follow-up, not here).
32//! And native Wanix currently has only [`native::ExecDriver`] — the exported
33//! `#task` tree is host-exec processes + binds, not a wasi/VM task tree, until a
34//! native wasi driver exists. The *mechanism* (host imports the guest's
35//! namespace bidirectionally, over the phase-1 `Remote9pMount`) is the
36//! deliverable; what is visible through it will grow as the guest gains drivers.
37//!
38//! [`native::ExecDriver`]: https://pkg.go.dev/tractor.dev/wanix/native
39//!
40//! ## The three injection steps (#506 deliverable 3)
41//!
42//! [`inject_9p_socket`] performs, for one workload:
43//!
44//! 1. **(a) allocate a per-workload UDS path** under the workload's runtime dir;
45//! 2. **(b) spawn the 9P server** — [`hyprstream_9p::serve_mount_uds`] serving
46//! *that tenant's* Subject-scoped [`Mount`] on the socket, as a background
47//! task (the [`UnixListener`] is bound *synchronously* first, so the socket
48//! file exists the moment this returns — no race with sandbox start);
49//! 3. **(c) produce the injection annotations** that the sandbox backend already
50//! consumes at its existing mount/env seam:
51//! * `hyprstream.io/mount.9p-sock=<host-sock>:<ctr-sock>:rw` — bind the host
52//! UDS into the container's mount namespace (OCI `--volume`, nspawn
53//! `--bind`);
54//! * `hyprstream.io/mount.wanix-guest=<host-bin>:<ctr-bin>:ro` — bind the
55//! (configurable, [`WanixGuestConfig::guest_bin`]) guest artifact in;
56//! * `hyprstream.io/env.HYPRSTREAM_9P_SOCK=<ctr-sock>` — tell the guest where
57//! to dial;
58//! * `hyprstream.io/command=<ctr-bin>` — run the guest as the workload command
59//! (consumed by [`OciBackend`](super::oci_backend)'s `build_run_args`).
60//!
61//! The returned [`WanixInjection`] carries both the annotations (a
62//! `HashMap<String, String>`, exactly the shape a
63//! [`SandboxBackend::start`](super::SandboxBackend::start) receives) and an
64//! [`Injected9pServer`] RAII handle that owns the serve task and removes the
65//! socket on drop.
66//!
67//! ## Where the tenant `Mount` + `Subject` come from
68//!
69//! The Subject-scoped [`Mount`] is a tenant's composed VFS namespace root — the
70//! same thing [`SandboxFs::compose`](super::sandbox_fs::SandboxFs) builds for the
71//! kata path (image rootfs + injected `/stream`, `/models`, `/deltas`, bound
72//! under the sandbox's [`Subject`]). Because [`Namespace`](hyprstream_vfs::Namespace)
73//! is not itself an `Arc<dyn Mount>` and the composition source differs per
74//! caller, this module takes the `Mount` + `Subject` as **parameters** rather
75//! than reaching into a specific composition site: the caller (a worker service
76//! placing a tenant workload) passes the tenant's namespace root and principal.
77//! This is the seam #506 leaves explicit — see the deliverable-3 note on the PR.
78//!
79//! ## Fail-closed
80//!
81//! Injection is gated on the **9P-socket-injection capability** (#506,
82//! deliverable 4): [`require_9p_socket_capability`](super::require_9p_socket_capability)
83//! must pass for the target backend before any socket is served. A backend that
84//! cannot receive a host UDS (kata, wasm) is refused cleanly — never a silent
85//! no-op where the guest comes up with no namespace. [`prepare_wanix_workload`]
86//! bundles the gate + injection.
87
88#![cfg(not(target_arch = "wasm32"))]
89
90use std::collections::HashMap;
91use std::path::{Path, PathBuf};
92use std::sync::Arc;
93
94use hyprstream_9p::Remote9pMount;
95use hyprstream_vfs::{BindFlag, Mount, Namespace, Subject};
96use tokio::net::UnixListener;
97use tracing::{debug, info, warn};
98
99use crate::error::{Result, WorkerError};
100use hyprstream_rpc_std::worker_client::KeyValue;
101
102// ─────────────────────────────────────────────────────────────────────────────
103// Annotation / env contract (shared with the sandbox backends' existing seam)
104// ─────────────────────────────────────────────────────────────────────────────
105
106/// Annotation key prefix: per-variable container environment. Matches the OCI
107/// backend's `ANN_ENV_PREFIX` (a wire contract between producer and consumer).
108const ANN_ENV_PREFIX: &str = "hyprstream.io/env.";
109/// Annotation key prefix: bind-mount spec `host:container[:ro|:rw]`. Matches the
110/// OCI backend's `ANN_MOUNT_PREFIX`.
111const ANN_MOUNT_PREFIX: &str = "hyprstream.io/mount.";
112/// Annotation key: the workload command to run in the sandbox. Consumed by
113/// [`OciBackend`](super::oci_backend)'s `build_run_args`. Must equal
114/// `oci_backend::ANN_COMMAND` (asserted by a test under `--features oci`).
115pub const ANN_WANIX_COMMAND: &str = "hyprstream.io/command";
116
117/// Environment variable the Wanix guest reads for the 9P socket path (see
118/// `workers/wanix-guest`). Kept in sync with the guest's `--sock` env fallback.
119pub const ENV_9P_SOCK: &str = "HYPRSTREAM_9P_SOCK";
120
121/// Environment variable the Wanix guest reads for the Direction-B **export**
122/// socket path — the in-container UDS on which the guest serves its OWN live
123/// namespace for the host to import (#708 phase 2). Kept in sync with the
124/// guest's `--export-sock` env fallback (`workers/wanix-guest`).
125pub const ENV_GUEST_EXPORT_SOCK: &str = "HYPRSTREAM_GUEST_EXPORT_SOCK";
126
127/// File name of the per-workload 9P socket under the workload runtime dir.
128const NINEP_SOCKET_NAME: &str = "9p.sock";
129/// In-container path the host 9P socket is bind-mounted to.
130const CTR_SOCK_PATH: &str = "/run/hyprstream/9p.sock";
131/// In-container path the host `wanix-guest` binary is bind-mounted to.
132const CTR_GUEST_BIN_PATH: &str = "/usr/local/bin/wanix-guest";
133
134/// Sub-directory under the workload runtime dir shared with the container for
135/// the Direction-B guest export. The guest CREATES its export listener inside
136/// this dir (a bind-mount source must already exist, and the guest's socket
137/// does not yet — so we share the *directory*, not a pre-made socket file, and
138/// the socket the guest binds appears here on the host).
139const GUEST_EXPORT_DIR_NAME: &str = "export";
140/// File name the guest binds its export listener as, inside the shared dir.
141const GUEST_EXPORT_SOCKET_NAME: &str = "wanix.sock";
142/// In-container path the shared export dir is bind-mounted to.
143const CTR_EXPORT_DIR: &str = "/run/hyprstream/export";
144/// In-container path of the guest's export socket (inside [`CTR_EXPORT_DIR`]).
145const CTR_EXPORT_SOCK_PATH: &str = "/run/hyprstream/export/wanix.sock";
146
147/// Bounded attempts to dial the guest export socket after sandbox start (it
148/// appears only once the guest boots and calls `listen(2)`).
149const IMPORT_CONNECT_ATTEMPTS: u32 = 20;
150/// Base backoff between import-connect attempts.
151const IMPORT_CONNECT_BACKOFF: std::time::Duration = std::time::Duration::from_millis(250);
152
153/// Env var overriding the host path to the `wanix-guest` build artifact.
154const ENV_GUEST_BIN: &str = "HYPRSTREAM_WANIX_GUEST_BIN";
155/// Default host path (relative to CWD) of the `wanix-guest` artifact produced by
156/// `scripts/build-wanix-guest.sh`.
157const DEFAULT_GUEST_BIN: &str = "target/wanix-guest";
158
159// ─────────────────────────────────────────────────────────────────────────────
160// Configuration
161// ─────────────────────────────────────────────────────────────────────────────
162
163/// Configuration for the Wanix-guest workload.
164#[derive(Debug, Clone)]
165pub struct WanixGuestConfig {
166 /// Host path to the `wanix-guest` binary (a foreign-toolchain build artifact
167 /// from `scripts/build-wanix-guest.sh`, *not* a cargo target). Configurable
168 /// via `HYPRSTREAM_WANIX_GUEST_BIN`; **never** hardcoded to an absolute path.
169 pub guest_bin: PathBuf,
170}
171
172impl Default for WanixGuestConfig {
173 fn default() -> Self {
174 let guest_bin = std::env::var(ENV_GUEST_BIN)
175 .map(PathBuf::from)
176 .unwrap_or_else(|_| PathBuf::from(DEFAULT_GUEST_BIN));
177 Self { guest_bin }
178 }
179}
180
181// ─────────────────────────────────────────────────────────────────────────────
182// Running 9P server handle
183// ─────────────────────────────────────────────────────────────────────────────
184
185/// RAII handle for a per-workload 9P server backing an injected socket.
186///
187/// Owns the background serve task (aborted on drop) and removes the socket file
188/// on drop, so tearing a workload down does not leak a listener or a stale
189/// socket. The task also exits on its own if the socket errors/closes.
190pub struct Injected9pServer {
191 /// Host-side path of the 9P Unix socket.
192 socket_path: PathBuf,
193 /// The background serve task ([`hyprstream_9p`]'s accept loop).
194 task: tokio::task::JoinHandle<()>,
195}
196
197impl Injected9pServer {
198 /// Host-side path of the 9P socket (the bind-mount source).
199 pub fn socket_path(&self) -> &Path {
200 &self.socket_path
201 }
202
203 /// Abort the serve task and remove the socket now (idempotent; `Drop` also
204 /// does this).
205 pub fn shutdown(&self) {
206 self.task.abort();
207 if let Err(e) = std::fs::remove_file(&self.socket_path) {
208 if e.kind() != std::io::ErrorKind::NotFound {
209 debug!(socket = %self.socket_path.display(), error = %e, "remove 9P socket");
210 }
211 }
212 }
213}
214
215impl Drop for Injected9pServer {
216 fn drop(&mut self) {
217 self.shutdown();
218 }
219}
220
221impl std::fmt::Debug for Injected9pServer {
222 fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
223 f.debug_struct("Injected9pServer")
224 .field("socket_path", &self.socket_path)
225 .finish()
226 }
227}
228
229// ─────────────────────────────────────────────────────────────────────────────
230// Injection result
231// ─────────────────────────────────────────────────────────────────────────────
232
233/// The product of [`inject_9p_socket`]: the annotations to place on the
234/// workload's sandbox config, plus the running 9P server handle.
235#[derive(Debug)]
236pub struct WanixInjection {
237 /// Annotations to merge into the sandbox's config. Shaped as the backend's
238 /// `start` receives them (`HashMap<String, String>`); use
239 /// [`WanixInjection::as_key_values`] to fold them into a
240 /// [`PodSandboxConfig`](hyprstream_rpc_std::worker_client::PodSandboxConfig)'s
241 /// `annotations: Vec<KeyValue>` for the pool path.
242 pub annotations: HashMap<String, String>,
243 /// The live Direction-A 9P server (host exports its namespace to the guest).
244 /// Keep it alive for the workload's lifetime; drop it to tear the export down.
245 pub server: Injected9pServer,
246 /// Host-side path where the guest's Direction-B export socket will appear
247 /// once the guest boots and listens (inside the shared export dir bound into
248 /// the container). Pass this to [`import_guest_namespace`] **after** the
249 /// sandbox is started to import the guest's live namespace.
250 pub export_socket_path: PathBuf,
251}
252
253impl WanixInjection {
254 /// The injection annotations as `Vec<KeyValue>` for merging into a
255 /// [`PodSandboxConfig`](hyprstream_rpc_std::worker_client::PodSandboxConfig).
256 pub fn as_key_values(&self) -> Vec<KeyValue> {
257 self.annotations
258 .iter()
259 .map(|(k, v)| KeyValue {
260 key: k.clone(),
261 value: v.clone(),
262 })
263 .collect()
264 }
265
266 /// Host-side path of the guest's Direction-B export socket (see
267 /// [`WanixInjection::export_socket_path`]).
268 pub fn export_socket_path(&self) -> &Path {
269 &self.export_socket_path
270 }
271}
272
273// ─────────────────────────────────────────────────────────────────────────────
274// Injection
275// ─────────────────────────────────────────────────────────────────────────────
276
277/// Allocate a per-workload UDS, serve `mount` (scoped to `subject`) as 9P over
278/// it, and build the sandbox injection annotations (#506 deliverable 3, steps
279/// a/b/c). See the module docs for the full contract.
280///
281/// The [`UnixListener`] is bound synchronously before the serve task is spawned,
282/// so the socket file exists on return — the bind-mount at sandbox start never
283/// races the server coming up.
284///
285/// This is the mechanical injection; the **capability gate** is
286/// [`prepare_wanix_workload`] (or call
287/// [`require_9p_socket_capability`](super::require_9p_socket_capability) first).
288pub async fn inject_9p_socket(
289 mount: Arc<dyn Mount>,
290 subject: Subject,
291 decider: Arc<dyn hyprstream_9p::AccessDecider>,
292 monitor: Option<Arc<hyprstream_9p::ReferenceMonitor>>,
293 workload_dir: &Path,
294 guest_cfg: &WanixGuestConfig,
295) -> Result<WanixInjection> {
296 // (a) Allocate the per-workload UDS path under the workload runtime dir.
297 tokio::fs::create_dir_all(workload_dir).await.map_err(|e| {
298 WorkerError::SandboxCreationFailed(format!(
299 "create workload dir {}: {e}",
300 workload_dir.display()
301 ))
302 })?;
303 let socket_path = workload_dir.join(NINEP_SOCKET_NAME);
304 // Remove any stale socket from a crashed predecessor (bind would EADDRINUSE).
305 if let Err(e) = tokio::fs::remove_file(&socket_path).await {
306 if e.kind() != std::io::ErrorKind::NotFound {
307 warn!(socket = %socket_path.display(), error = %e, "remove stale 9P socket");
308 }
309 }
310
311 // (b) Bind the listener *now* (socket file exists on return), then spawn the
312 // 9P serve loop in the background over that tenant's Subject-scoped Mount.
313 let listener = UnixListener::bind(&socket_path).map_err(|e| {
314 WorkerError::SandboxCreationFailed(format!("bind 9P UDS at {}: {e}", socket_path.display()))
315 })?;
316 let sock_for_log = socket_path.clone();
317 let task = tokio::spawn(async move {
318 // `serve_uds` is PR-A's wire-faithful 9P2000.L server; it runs until the
319 // socket errors/closes (or the task is aborted on teardown).
320 // #1269: when a ReferenceMonitor is supplied, every dispatched op is
321 // mediated (attach-time token verification, trusted label resolution,
322 // token gate, independent IFC dominance, then the local AVC/PDP).
323 let mut translator = hyprstream_9p::Translator::from_mount(mount, subject, decider);
324 if let Some(monitor) = monitor {
325 translator = translator
326 .with_reference_monitor(monitor)
327 .with_activation_control();
328 }
329 if let Err(e) = translator.serve_uds(listener).await {
330 warn!(socket = %sock_for_log.display(), error = %e, "9P workload server exited with error");
331 }
332 });
333
334 // (c) Injection annotations, consumed at the backend's existing mount/env
335 // seam (OCI `--volume`/`--env`/command; nspawn `--bind`/`--setenv`).
336 let host_sock = socket_path.to_string_lossy().into_owned();
337 let host_bin = guest_cfg.guest_bin.to_string_lossy().into_owned();
338
339 let mut annotations = HashMap::new();
340 // Bind the host 9P socket into the container's mount namespace (rw: the guest
341 // connects and does full-duplex 9P over it).
342 annotations.insert(
343 format!("{ANN_MOUNT_PREFIX}9p-sock"),
344 format!("{host_sock}:{CTR_SOCK_PATH}:rw"),
345 );
346 // Bind the configurable guest artifact in read-only.
347 annotations.insert(
348 format!("{ANN_MOUNT_PREFIX}wanix-guest"),
349 format!("{host_bin}:{CTR_GUEST_BIN_PATH}:ro"),
350 );
351 // Point the guest at the in-container socket path.
352 annotations.insert(
353 format!("{ANN_ENV_PREFIX}{ENV_9P_SOCK}"),
354 CTR_SOCK_PATH.to_owned(),
355 );
356
357 // ── Direction B (#708 phase 2): guest exports, host imports ──────────────
358 //
359 // Allocate a shared export DIRECTORY (not a pre-made socket file: the guest
360 // is the server here, so it creates the listener — a bind-mount source must
361 // already exist, but the guest's socket does not yet). The guest binds its
362 // export listener inside this dir; because the dir is bind-mounted into the
363 // container, that socket appears on the host at `export_socket_path`, which
364 // the host later dials via [`import_guest_namespace`].
365 let host_export_dir = workload_dir.join(GUEST_EXPORT_DIR_NAME);
366 tokio::fs::create_dir_all(&host_export_dir)
367 .await
368 .map_err(|e| {
369 WorkerError::SandboxCreationFailed(format!(
370 "create guest export dir {}: {e}",
371 host_export_dir.display()
372 ))
373 })?;
374 let export_socket_path = host_export_dir.join(GUEST_EXPORT_SOCKET_NAME);
375 // Remove any stale export socket left by a crashed predecessor guest.
376 if let Err(e) = tokio::fs::remove_file(&export_socket_path).await {
377 if e.kind() != std::io::ErrorKind::NotFound {
378 warn!(socket = %export_socket_path.display(), error = %e, "remove stale guest export socket");
379 }
380 }
381 let host_export_dir_str = host_export_dir.to_string_lossy().into_owned();
382 // Bind the shared export dir into the container's mount namespace (rw: the
383 // guest binds its listener inside it, the host reads the resulting socket).
384 annotations.insert(
385 format!("{ANN_MOUNT_PREFIX}wanix-export-dir"),
386 format!("{host_export_dir_str}:{CTR_EXPORT_DIR}:rw"),
387 );
388 // Tell the guest where to export its namespace (in-container socket path).
389 annotations.insert(
390 format!("{ANN_ENV_PREFIX}{ENV_GUEST_EXPORT_SOCK}"),
391 CTR_EXPORT_SOCK_PATH.to_owned(),
392 );
393
394 // Run the guest as the workload command (serve-namespace mode: no `--cmd`,
395 // which is the reliable path today — see wanix-guest README's known gap).
396 annotations.insert(ANN_WANIX_COMMAND.to_owned(), CTR_GUEST_BIN_PATH.to_owned());
397
398 info!(
399 socket = %socket_path.display(),
400 export_socket = %export_socket_path.display(),
401 guest_bin = %guest_cfg.guest_bin.display(),
402 "prepared bidirectional Wanix-guest 9P workload injection"
403 );
404
405 Ok(WanixInjection {
406 annotations,
407 server: Injected9pServer { socket_path, task },
408 export_socket_path,
409 })
410}
411
412/// A guest namespace imported into the host VFS namespace (#708 phase 2,
413/// Direction B). Holds the [`Remote9pMount`] backing the imported tree so the
414/// remote 9P client connection lives as long as this handle; drop it (and
415/// [`unmount`](ImportedGuestNamespace::unmount) the prefix) at workload teardown.
416pub struct ImportedGuestNamespace {
417 mount: Arc<dyn Mount>,
418 prefix: String,
419}
420
421impl ImportedGuestNamespace {
422 /// The host namespace prefix the guest tree is bound at
423 /// (`/workers/<tenant>/wanix`).
424 pub fn prefix(&self) -> &str {
425 &self.prefix
426 }
427
428 /// The imported guest tree as an `Arc<dyn Mount>` (already bound into the
429 /// host namespace by [`import_guest_namespace`]; exposed for rebind/teardown).
430 pub fn mount(&self) -> Arc<dyn Mount> {
431 Arc::clone(&self.mount)
432 }
433
434 /// Remove the imported tree from `host_ns` (the teardown counterpart of the
435 /// bind [`import_guest_namespace`] performed).
436 pub fn unmount(&self, host_ns: &mut Namespace) {
437 let _ = host_ns.unmount(&self.prefix);
438 }
439}
440
441impl std::fmt::Debug for ImportedGuestNamespace {
442 fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
443 f.debug_struct("ImportedGuestNamespace")
444 .field("prefix", &self.prefix)
445 .finish()
446 }
447}
448
449/// Import the guest's live namespace (Direction B, #708 phase 2): dial the
450/// guest's export socket with the phase-1 socket 9P client [`Remote9pMount`],
451/// and bind the resulting [`Mount`] into `host_ns` at `/workers/<tenant>/wanix`,
452/// giving the host visibility into the guest's task tree.
453///
454/// Call this **after** the sandbox has been started: the export socket appears
455/// only once the guest boots and `listen(2)`s, so the dial is retried with
456/// bounded backoff ([`IMPORT_CONNECT_ATTEMPTS`]). `export_sock` is the host-side
457/// [`WanixInjection::export_socket_path`].
458///
459/// This is the reverse, independent 9P session of the Direction-A export the
460/// host serves in [`inject_9p_socket`] — a separate socket, a separate client,
461/// no shared coupling (#708).
462pub async fn import_guest_namespace(
463 host_ns: &mut Namespace,
464 export_sock: &Path,
465 tenant: &str,
466) -> Result<ImportedGuestNamespace> {
467 import_guest_namespace_with(
468 host_ns,
469 export_sock,
470 tenant,
471 IMPORT_CONNECT_ATTEMPTS,
472 IMPORT_CONNECT_BACKOFF,
473 )
474 .await
475}
476
477/// [`import_guest_namespace`] with explicit retry bounds (the public wrapper
478/// uses [`IMPORT_CONNECT_ATTEMPTS`]/[`IMPORT_CONNECT_BACKOFF`]). Kept separate so
479/// tests can drive the retry loop without waiting out the production backoff.
480async fn import_guest_namespace_with(
481 host_ns: &mut Namespace,
482 export_sock: &Path,
483 tenant: &str,
484 attempts: u32,
485 backoff: std::time::Duration,
486) -> Result<ImportedGuestNamespace> {
487 let prefix = format!("/workers/{tenant}/wanix");
488
489 // The guest's listener appears only after it boots — retry with backoff.
490 let mut last_err: Option<anyhow::Error> = None;
491 let mut mount = None;
492 for attempt in 1..=attempts {
493 match Remote9pMount::connect_uds(export_sock, "hyprstream", "").await {
494 Ok(m) => {
495 mount = Some(m);
496 break;
497 }
498 Err(e) => {
499 debug!(
500 socket = %export_sock.display(),
501 attempt,
502 error = %e,
503 "guest export socket not ready yet; retrying"
504 );
505 last_err = Some(e);
506 tokio::time::sleep(backoff * attempt).await;
507 }
508 }
509 }
510 let mount = mount.ok_or_else(|| {
511 WorkerError::SandboxCreationFailed(format!(
512 "could not import guest namespace from {} after {attempts} attempts: {}",
513 export_sock.display(),
514 last_err
515 .map(|e| e.to_string())
516 .unwrap_or_else(|| "unknown error".into())
517 ))
518 })?;
519
520 let mount: Arc<dyn Mount> = Arc::new(mount);
521 host_ns
522 .bind_mount(&prefix, Arc::clone(&mount), BindFlag::Replace)
523 .map_err(|e| {
524 WorkerError::SandboxCreationFailed(format!(
525 "bind imported guest namespace at {prefix}: {e}"
526 ))
527 })?;
528
529 info!(prefix = %prefix, socket = %export_sock.display(), "imported guest Wanix namespace into host VFS");
530
531 Ok(ImportedGuestNamespace { mount, prefix })
532}
533
534/// Fail-closed convenience: verify `backend_type` can inject a 9P socket, then
535/// perform the injection (#506, deliverables 3 + 4 together).
536///
537/// The capability gate runs **before** any socket is bound or served, so an
538/// incapable backend (kata, wasm) is refused without side effects — never a
539/// silent no-op where the guest boots with no namespace.
540pub async fn prepare_wanix_workload(
541 backend_type: &str,
542 mount: Arc<dyn Mount>,
543 subject: Subject,
544 decider: Arc<dyn hyprstream_9p::AccessDecider>,
545 monitor: Option<Arc<hyprstream_9p::ReferenceMonitor>>,
546 workload_dir: &Path,
547 guest_cfg: &WanixGuestConfig,
548) -> Result<WanixInjection> {
549 super::require_9p_socket_capability(backend_type)?;
550 inject_9p_socket(mount, subject, decider, monitor, workload_dir, guest_cfg).await
551}
552
553// ─────────────────────────────────────────────────────────────────────────────
554// Tests
555// ─────────────────────────────────────────────────────────────────────────────
556
557#[cfg(test)]
558#[allow(clippy::unwrap_used, clippy::expect_used)]
559mod tests {
560 use super::*;
561 use hyprstream_rpc::auth::mac::{ObjectRef, SecurityContext};
562 use hyprstream_vfs::injected::{SyntheticMount, SyntheticNode};
563 use std::os::unix::net::UnixStream as StdUnixStream;
564
565 /// Explicitly test-only policy for the loopback guest-export fixture.
566 ///
567 /// Production callers must inject the resolver-backed, audited decider;
568 /// this permit policy exists only to exercise the transport fixture.
569 struct FixtureAccessDecider;
570
571 impl hyprstream_9p::AccessDecider for FixtureAccessDecider {
572 fn check(
573 &self,
574 _ctx: &SecurityContext,
575 _object: ObjectRef<'_>,
576 _action: hyprstream_9p::Action,
577 ) -> bool {
578 true
579 }
580
581 fn audit_denial(
582 &self,
583 _ctx: &SecurityContext,
584 _object: ObjectRef<'_>,
585 _object_label: Option<hyprstream_rpc::auth::mac::SecurityLabel>,
586 _action: hyprstream_9p::Action,
587 _reason: hyprstream_9p::ReferenceMonitorDenyReason,
588 ) {
589 }
590 }
591
592 fn tenant_mount() -> Arc<dyn Mount> {
593 // A trivial Subject-scoped tree stands in for a composed tenant namespace.
594 Arc::new(SyntheticMount::new(
595 SyntheticNode::dir().with_child("hello", SyntheticNode::file(b"hi\n".to_vec())),
596 ))
597 }
598
599 #[test]
600 fn guest_bin_is_configurable_not_hardcoded() {
601 // Default is the build-script artifact path (relative), never an absolute
602 // hardcode.
603 std::env::remove_var(ENV_GUEST_BIN);
604 let cfg = WanixGuestConfig::default();
605 assert_eq!(cfg.guest_bin, PathBuf::from(DEFAULT_GUEST_BIN));
606 assert!(
607 cfg.guest_bin.is_relative(),
608 "default must not be an absolute hardcode"
609 );
610
611 std::env::set_var(ENV_GUEST_BIN, "/opt/custom/wanix-guest");
612 let cfg = WanixGuestConfig::default();
613 assert_eq!(cfg.guest_bin, PathBuf::from("/opt/custom/wanix-guest"));
614 std::env::remove_var(ENV_GUEST_BIN);
615 }
616
617 #[tokio::test]
618 async fn inject_creates_socket_and_expected_annotations() {
619 let dir = tempfile::tempdir().unwrap();
620 let cfg = WanixGuestConfig {
621 guest_bin: PathBuf::from("/host/build/wanix-guest"),
622 };
623 let inj = inject_9p_socket(
624 tenant_mount(),
625 Subject::anonymous(),
626 Arc::new(FixtureAccessDecider),
627 None,
628 dir.path(),
629 &cfg,
630 )
631 .await
632 .unwrap();
633
634 // (a) socket exists on return (bound synchronously) — the bind-mount
635 // source is ready before any sandbox start.
636 let sock = dir.path().join(NINEP_SOCKET_NAME);
637 assert!(
638 sock.exists(),
639 "9P socket must exist immediately after inject"
640 );
641 assert_eq!(inj.server.socket_path(), sock.as_path());
642
643 // (c) env points the guest at the in-container socket.
644 assert_eq!(
645 inj.annotations
646 .get(&format!("{ANN_ENV_PREFIX}{ENV_9P_SOCK}"))
647 .map(String::as_str),
648 Some(CTR_SOCK_PATH)
649 );
650 // socket bind: host abs path → container path, rw.
651 let sock_mount = inj
652 .annotations
653 .get(&format!("{ANN_MOUNT_PREFIX}9p-sock"))
654 .expect("9p-sock mount annotation");
655 assert_eq!(
656 sock_mount,
657 &format!("{}:{CTR_SOCK_PATH}:rw", sock.display())
658 );
659 // guest binary bind uses the CONFIGURED host path (read-only).
660 assert_eq!(
661 inj.annotations
662 .get(&format!("{ANN_MOUNT_PREFIX}wanix-guest"))
663 .map(String::as_str),
664 Some(format!("/host/build/wanix-guest:{CTR_GUEST_BIN_PATH}:ro").as_str())
665 );
666 // command runs the guest.
667 assert_eq!(
668 inj.annotations.get(ANN_WANIX_COMMAND).map(String::as_str),
669 Some(CTR_GUEST_BIN_PATH)
670 );
671
672 // Direction B (#708 phase 2): shared export dir bound rw, export env set,
673 // and the host-side export socket path exposed under the shared dir.
674 let export_dir = dir.path().join(GUEST_EXPORT_DIR_NAME);
675 assert!(
676 export_dir.is_dir(),
677 "shared export dir must be created on inject"
678 );
679 assert_eq!(
680 inj.annotations
681 .get(&format!("{ANN_MOUNT_PREFIX}wanix-export-dir")),
682 Some(&format!("{}:{CTR_EXPORT_DIR}:rw", export_dir.display()))
683 );
684 assert_eq!(
685 inj.annotations
686 .get(&format!("{ANN_ENV_PREFIX}{ENV_GUEST_EXPORT_SOCK}"))
687 .map(String::as_str),
688 Some(CTR_EXPORT_SOCK_PATH)
689 );
690 assert_eq!(
691 inj.export_socket_path(),
692 export_dir.join(GUEST_EXPORT_SOCKET_NAME).as_path()
693 );
694 }
695
696 #[tokio::test]
697 async fn import_guest_namespace_binds_and_reads() {
698 // Stand up a local wire-faithful 9P server over a Mount — this stands in
699 // for the guest's Direction-B export — then import it into a host
700 // namespace and read a file back through the bound prefix. Exercises the
701 // full host-import mechanism (phase-1 Remote9pMount → bind_mount) in
702 // process, no sandbox boot.
703 let dir = tempfile::tempdir().unwrap();
704 let sock = dir.path().join("guest-export.sock");
705 let listener = UnixListener::bind(&sock).unwrap();
706 let server = tokio::spawn(async move {
707 let _ = hyprstream_9p::Translator::from_mount(
708 tenant_mount(),
709 Subject::anonymous(),
710 Arc::new(FixtureAccessDecider),
711 )
712 .serve_uds(listener)
713 .await;
714 });
715
716 let mut host_ns = Namespace::new();
717 let imported = import_guest_namespace(&mut host_ns, &sock, "t1")
718 .await
719 .unwrap();
720 assert_eq!(imported.prefix(), "/workers/t1/wanix");
721
722 let data = host_ns
723 .cat("/workers/t1/wanix/hello", &Subject::anonymous())
724 .await
725 .unwrap();
726 assert_eq!(
727 data, b"hi\n",
728 "host must read the guest's file over the imported 9P mount"
729 );
730
731 imported.unmount(&mut host_ns);
732 assert!(
733 !host_ns.mount_prefixes().contains(&"/workers/t1/wanix"),
734 "unmount must remove the imported prefix"
735 );
736 server.abort();
737 }
738
739 #[tokio::test]
740 async fn import_fails_when_no_guest_export() {
741 // No server ever listens on the socket → bounded retries exhaust and the
742 // import fails closed (never binds a dead mount).
743 let dir = tempfile::tempdir().unwrap();
744 let sock = dir.path().join("never-appears.sock");
745 let mut host_ns = Namespace::new();
746 let err = import_guest_namespace_with(
747 &mut host_ns,
748 &sock,
749 "t1",
750 3,
751 std::time::Duration::from_millis(1),
752 )
753 .await
754 .unwrap_err();
755 assert!(
756 err.to_string().contains("could not import guest namespace"),
757 "got: {err}"
758 );
759 assert!(
760 host_ns.mount_prefixes().is_empty(),
761 "nothing must be bound on failure"
762 );
763 }
764
765 #[tokio::test]
766 async fn injected_socket_is_a_live_9p_server() {
767 // The spawned task actually serves 9P through attach, the first
768 // policy-controlled operation. Stopping at Rversion would miss a
769 // deny-all policy outage because negotiation is intentionally
770 // unauthenticated.
771 let dir = tempfile::tempdir().unwrap();
772 let inj = inject_9p_socket(
773 tenant_mount(),
774 Subject::anonymous(),
775 Arc::new(FixtureAccessDecider),
776 None,
777 dir.path(),
778 &WanixGuestConfig::default(),
779 )
780 .await
781 .unwrap();
782
783 let sock = inj.server.socket_path().to_path_buf();
784 // Connect, negotiate 9P2000.L, then attach to the exported root.
785 let reply = tokio::task::spawn_blocking(move || {
786 use std::io::{Read, Write};
787
788 fn read_frame(stream: &mut StdUnixStream) -> Vec<u8> {
789 let mut len = [0u8; 4];
790 stream.read_exact(&mut len).unwrap();
791 let total = u32::from_le_bytes(len) as usize;
792 let mut frame = vec![0u8; total];
793 frame[..4].copy_from_slice(&len);
794 stream.read_exact(&mut frame[4..]).unwrap();
795 frame
796 }
797
798 let mut c = StdUnixStream::connect(&sock).unwrap();
799 c.write_all(&hyprstream_9p::msg::tversion(1, 8192, "9P2000.L"))
800 .unwrap();
801 let version = read_frame(&mut c);
802 assert_eq!(
803 version[4],
804 hyprstream_9p::msg::RVERSION,
805 "expected Rversion from the injected 9P server"
806 );
807
808 c.write_all(&hyprstream_9p::msg::tattach(2, 0, u32::MAX, "wanix", ""))
809 .unwrap();
810 read_frame(&mut c)[4]
811 })
812 .await
813 .unwrap();
814
815 assert_eq!(
816 reply,
817 hyprstream_9p::msg::RATTACH,
818 "expected Rattach from the injected 9P server"
819 );
820 }
821
822 #[tokio::test]
823 async fn dropping_server_removes_socket() {
824 let dir = tempfile::tempdir().unwrap();
825 let inj = inject_9p_socket(
826 tenant_mount(),
827 Subject::anonymous(),
828 Arc::new(FixtureAccessDecider),
829 None,
830 dir.path(),
831 &WanixGuestConfig::default(),
832 )
833 .await
834 .unwrap();
835 let sock = inj.server.socket_path().to_path_buf();
836 assert!(sock.exists());
837 drop(inj);
838 assert!(
839 !sock.exists(),
840 "socket must be removed when the server is dropped"
841 );
842 }
843
844 #[tokio::test]
845 async fn prepare_fails_closed_on_incapable_backend() {
846 // kata/wasm/unknown cannot inject a host UDS → refuse before serving.
847 let dir = tempfile::tempdir().unwrap();
848 let err = prepare_wanix_workload(
849 "kata",
850 tenant_mount(),
851 Subject::anonymous(),
852 Arc::new(FixtureAccessDecider),
853 None,
854 dir.path(),
855 &WanixGuestConfig::default(),
856 )
857 .await
858 .unwrap_err();
859 assert!(
860 err.to_string().contains("cannot inject a 9P socket"),
861 "got: {err}"
862 );
863 // And no socket was created (fail-closed BEFORE any side effect).
864 assert!(!dir.path().join(NINEP_SOCKET_NAME).exists());
865 }
866
867 #[cfg(feature = "nspawn")]
868 #[tokio::test]
869 async fn prepare_succeeds_on_capable_backend() {
870 // nspawn is registered (under the `nspawn` feature) and capable → injection proceeds.
871 let dir = tempfile::tempdir().unwrap();
872 let inj = prepare_wanix_workload(
873 "nspawn",
874 tenant_mount(),
875 Subject::anonymous(),
876 Arc::new(FixtureAccessDecider),
877 None,
878 dir.path(),
879 &WanixGuestConfig::default(),
880 )
881 .await
882 .unwrap();
883 assert!(inj.server.socket_path().exists());
884 assert!(inj.annotations.contains_key(ANN_WANIX_COMMAND));
885 }
886}