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:
- (a) allocate a per-workload UDS path under the workload’s runtime dir;
- (b) spawn the 9P server —
hyprstream_9p::serve_mount_udsserving that tenant’s Subject-scopedMounton 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); - (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 byOciBackend’sbuild_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§
- Imported
Guest Namespace - A guest namespace imported into the host VFS namespace (#708 phase 2,
Direction B). Holds the
Remote9pMountbacking the imported tree so the remote 9P client connection lives as long as this handle; drop it (andunmountthe prefix) at workload teardown. - Injected9p
Server - RAII handle for a per-workload 9P server backing an injected socket.
- Wanix
Guest Config - Configuration for the Wanix-guest workload.
- Wanix
Injection - 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’sbuild_run_args. Must equaloci_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--sockenv 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-sockenv 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 resultingMountintohost_nsat/workers/<tenant>/wanix, giving the host visibility into the guest’s task tree. - inject_
9p_ socket - Allocate a per-workload UDS, serve
mount(scoped tosubject) 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_typecan inject a 9P socket, then perform the injection (#506, deliverables 3 + 4 together).