Skip to main content

Module wanix_workload

Module wanix_workload 

Source
Expand description

Wanix-guest workload wiring (#506, deliverable 3).

This is the OCI/nspawn analog of the kata/virtio-fs path in super::sandbox_fs (FS-D, #365). Where sandbox_fs composes a per-sandbox Subject-scoped VFS Namespace and serves it over a vhost-user-fs socket that a Cloud-Hypervisor guest attaches as a virtio-fs device, this module serves a tenant’s Subject-scoped Mount as a wire-faithful 9P2000.L server over a plain Unix socket (PR-A’s hyprstream_9p::serve_mount_uds) and injects that socket into a bind-mount-capable sandbox (OCI/nspawn) so the native Wanix guest (PR-B’s workers/wanix-guest) dials back and binds the export as its namespace root.

§Bidirectional 9P (#708 phase 2)

The above is Direction A — the host exports its namespace, the guest imports it. This module also wires Direction B, the reverse: the native Wanix guest exports its OWN live namespace over a second, independent UDS, and the host imports it via the phase-1 socket 9P client Remote9pMount and binds it into the host VFS Namespace at /workers/<tenant>/wanix — giving the host visibility into the guest’s task tree.

inject_9p_socket allocates the export path and injects it (a shared export directory bind-mount + ENV_GUEST_EXPORT_SOCK, mirroring the Direction-A socket injection). After the sandbox starts, import_guest_namespace dials the guest’s export socket and binds the imported tree. The two directions are independent — separate sockets, separate 9P sessions, no shared coupling (#708).

Scope + payoff caveat. This is wired for the shared-FS UDS backends (OCI/nspawn); a kata guest would export over vsock (follow-up, not here). And native Wanix currently has only native::ExecDriver — the exported #task tree is host-exec processes + binds, not a wasi/VM task tree, until a native wasi driver exists. The mechanism (host imports the guest’s namespace bidirectionally, over the phase-1 Remote9pMount) is the deliverable; what is visible through it will grow as the guest gains drivers.

§The three injection steps (#506 deliverable 3)

inject_9p_socket performs, for one workload:

  1. (a) allocate a per-workload UDS path under the workload’s runtime dir;
  2. (b) spawn the 9P server — hyprstream_9p::serve_mount_uds serving that tenant’s Subject-scoped Mount on the socket, as a background task (the [UnixListener] is bound synchronously first, so the socket file exists the moment this returns — no race with sandbox start);
  3. (c) produce the injection annotations that the sandbox backend already consumes at its existing mount/env seam:
    • hyprstream.io/mount.9p-sock=<host-sock>:<ctr-sock>:rw — bind the host UDS into the container’s mount namespace (OCI --volume, nspawn --bind);
    • hyprstream.io/mount.wanix-guest=<host-bin>:<ctr-bin>:ro — bind the (configurable, WanixGuestConfig::guest_bin) guest artifact in;
    • hyprstream.io/env.HYPRSTREAM_9P_SOCK=<ctr-sock> — tell the guest where to dial;
    • hyprstream.io/command=<ctr-bin> — run the guest as the workload command (consumed by OciBackend’s build_run_args).

The returned WanixInjection carries both the annotations (a HashMap<String, String>, exactly the shape a SandboxBackend::start receives) and an Injected9pServer RAII handle that owns the serve task and removes the socket on drop.

§Where the tenant Mount + Subject come from

The Subject-scoped Mount is a tenant’s composed VFS namespace root — the same thing SandboxFs::compose builds for the kata path (image rootfs + injected /stream, /models, /deltas, bound under the sandbox’s Subject). Because Namespace is not itself an Arc<dyn Mount> and the composition source differs per caller, this module takes the Mount + Subject as parameters rather than reaching into a specific composition site: the caller (a worker service placing a tenant workload) passes the tenant’s namespace root and principal. This is the seam #506 leaves explicit — see the deliverable-3 note on the PR.

§Fail-closed

Injection is gated on the 9P-socket-injection capability (#506, deliverable 4): require_9p_socket_capability must pass for the target backend before any socket is served. A backend that cannot receive a host UDS (kata, wasm) is refused cleanly — never a silent no-op where the guest comes up with no namespace. prepare_wanix_workload bundles the gate + injection.

Structs§

ImportedGuestNamespace
A guest namespace imported into the host VFS namespace (#708 phase 2, Direction B). Holds the Remote9pMount backing the imported tree so the remote 9P client connection lives as long as this handle; drop it (and unmount the prefix) at workload teardown.
Injected9pServer
RAII handle for a per-workload 9P server backing an injected socket.
WanixGuestConfig
Configuration for the Wanix-guest workload.
WanixInjection
The product of inject_9p_socket: the annotations to place on the workload’s sandbox config, plus the running 9P server handle.

Constants§

ANN_WANIX_COMMAND
Annotation key: the workload command to run in the sandbox. Consumed by OciBackend’s build_run_args. Must equal oci_backend::ANN_COMMAND (asserted by a test under --features oci).
ENV_9P_SOCK
Environment variable the Wanix guest reads for the 9P socket path (see workers/wanix-guest). Kept in sync with the guest’s --sock env fallback.
ENV_GUEST_EXPORT_SOCK
Environment variable the Wanix guest reads for the Direction-B export socket path — the in-container UDS on which the guest serves its OWN live namespace for the host to import (#708 phase 2). Kept in sync with the guest’s --export-sock env fallback (workers/wanix-guest).

Functions§

import_guest_namespace
Import the guest’s live namespace (Direction B, #708 phase 2): dial the guest’s export socket with the phase-1 socket 9P client Remote9pMount, and bind the resulting Mount into host_ns at /workers/<tenant>/wanix, giving the host visibility into the guest’s task tree.
inject_9p_socket
Allocate a per-workload UDS, serve mount (scoped to subject) as 9P over it, and build the sandbox injection annotations (#506 deliverable 3, steps a/b/c). See the module docs for the full contract.
prepare_wanix_workload
Fail-closed convenience: verify backend_type can inject a 9P socket, then perform the injection (#506, deliverables 3 + 4 together).