Skip to main content

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}