Expand description
9P-over-WebSocket export (H1a / #764).
Serves hyprstream’s Subject-scoped VFS as 9P2000.L over WebSocket on the
existing axum HTTP server, wire-compatible with wanix serve, so stock
wanix 0.4 / apptron mount a hyprstream host with zero client glue.
Two routes (registered in crate::server):
GET /.well-known/export9p— discovery. Advertises the/9pWebSocket endpoint, the mount-ticket query parameter, and the wire so a mounting client (S4WanixSessionContext) can construct thewss://…/9p?ticket=…URL. (Upstream’s/.well-known/export9pis amux-session endpoint for the reverse direction — a browser exporting its namespace outward; H1a’s interop path is the raw-frame/9pendpoint that stock waniximportbinds connect to directly, so we serve a JSON discovery document here instead of the mux protocol. See the PR “WIRE CONTRACT” section.)GET /9p— WebSocket upgrade → a ws↔9p byte pump feeding the transport-agnosticTranslator::serve_connectioncore over a [MountBackend] (the SAME core the UDS/vsock transports use — not a fork). Binary frames carry framed 9P2000.L messages; the pump tolerates arbitrary chunking (P9PortReadWriteron the wanix side buffers).
§Auth (reuses the existing chain)
The mount ticket rides the URL query (?ticket=<at+jwt>) because a browser
WebSocket cannot set request headers. It is validated at the WS upgrade
via [crate::server::middleware::verify_resource_token_claims] — the exact same
chain auth_middleware uses (issuer routing, Ed25519/ML-DSA signature +
audience validation, JTI revocation). The validated sub becomes the
session Subject, threaded onto every 9P op by [MountBackend] (the
single MAC policy-enforcement point). Denials surface as Rlerror errnos.
§Server-owned liveness (H1a hard requirement)
A dead browser peer is NOT observable to the far side (a closed port yields
no EOF), so a naive server would leak the 9P session forever. The pump
therefore OWNS liveness via server-driven WS ping/pong keepalive: it
sends a WS Ping every [PING_INTERVAL] (30s) and closes the session after
[MAX_MISSED_PONGS] consecutive unanswered pings (~90s). Closing drops the
pump’s write half, which surfaces as EOF to serve_connection and tears the
9P session down cleanly. A dead peer stops ponging and is reaped in ~90s; a
HEALTHY-but-idle mount survives indefinitely because pongs keep flowing
with zero 9P traffic (and any inbound frame — pong or data — counts as
liveness). The client’s WS close event is the browser’s unmount trigger,
so teardown stays 100% server-driven with no client keepalive. The server
never relies on the client noticing.
Structs§
- Export9p
Discovery - Discovery document for the 9P-over-WebSocket export.
- NineP
Query - Query params on the
/9pWebSocket upgrade. - NineP
WtExport - The injected 9P-over-WebTransport handler (H1b / #765).
- Wire
Plane - One wire plane’s advertisement in the
WirePlaneTable. - Wire
Plane Table - Wire-plane discovery table served at
GET /.well-known/planes(#821).
Constants§
- NINEP_
PATH - URL path the 9P plane is served on. The single authoritative source for the
/9pselector on the SERVE side: bothExport9pDiscoveryand theWirePlaneTableread it, and the route incrate::serverregisters it, so the plane advertises its own path rather than the value being duplicated as a constant on both the dial and serve sides (the retire of the dial-sidecrate::dial::*_PATHconstants against this table is #820’s job).
Functions§
- export9p_
metadata GET /.well-known/export9p— advertise the 9P-over-WS export.- ninep_
ws GET /9p— validate the mount ticket, then upgrade to a 9P-over-WS session.- register_
ninep_ wt_ handler - Register the process-global 9P-over-WebTransport handler so the QUIC
path-mux
/9parm serves this node’s export. Idempotent (first-wins); call once at server startup whereServerStateexists (seecrate::server::create_app). - wire_
planes_ metadata GET /.well-known/planes— advertise the wire-plane discovery table (#821).