Skip to main content

Module ninep

Module ninep 

Source
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 /9p WebSocket endpoint, the mount-ticket query parameter, and the wire so a mounting client (S4 WanixSessionContext) can construct the wss://…/9p?ticket=… URL. (Upstream’s /.well-known/export9p is a mux-session endpoint for the reverse direction — a browser exporting its namespace outward; H1a’s interop path is the raw-frame /9p endpoint that stock wanix import binds 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-agnostic Translator::serve_connection core 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 (P9PortReadWriter on 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§

Export9pDiscovery
Discovery document for the 9P-over-WebSocket export.
NinePQuery
Query params on the /9p WebSocket upgrade.
NinePWtExport
The injected 9P-over-WebTransport handler (H1b / #765).
WirePlane
One wire plane’s advertisement in the WirePlaneTable.
WirePlaneTable
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 /9p selector on the SERVE side: both Export9pDiscovery and the WirePlaneTable read it, and the route in crate::server registers 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-side crate::dial::*_PATH constants 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 /9p arm serves this node’s export. Idempotent (first-wins); call once at server startup where ServerState exists (see crate::server::create_app).
wire_planes_metadata
GET /.well-known/planes — advertise the wire-plane discovery table (#821).