Skip to content
Vulpine
Esc
↑↓navigate↵open⌘Jpreview
On this page

Reach: WebSocket

A key paired by reach-pair.v1 whose row grants ws (every client row by default). The helper's accept rule runs after the TLS handshake and before a byte.

Living doc, checked against the code 2026-11-14

reach-ws.v1 — the frontend protocol’s WebSocket carried over reach, one QUIC stream per WebSocket

  • Status: accepted; public, built. public is its label in the API catalog.
  • Scope: how a paired key reaches the gateway’s frontend WebSocket from another network. The frontend protocol 5 crosses the WebSocket unchanged. This contract adds no frame.
  • Off by default. The helper serves this ALPN only with [reach] enabled = true and [reach] helper_ws set.

Who may open it

It closes any other key with the codes in reach-pair.v1’s accept rule: 2 unpaired, 3 revoked, 4 role, 5 attest. A delegated agent key holding a one-shot admission for ws (from vulpine/delegate/1, an owner ALPN) may also open it, for that one connection.

The wire

  1. Dial the gateway’s EndpointId (from the pairing) on ALPN vulpine/ws/1.
  2. Open one bidirectional stream per WebSocket. A connection may carry many. Each is independent, and a failed stream ends alone.
  3. On the stream, speak a WebSocket client exactly as on a TCP socket: the HTTP/1.1 Upgrade request to /, then WebSocket frames (RFC 6455) both ways. The helper copies the stream’s bytes to the gateway’s loopback ws port and back, and reads, rewrites and frames nothing. A FIN on one side finishes the other side’s write half.
  4. If the helper cannot reach the gateway’s port, it resets the stream and stops reading it with application code 1 (refused). The connection and its other streams carry on.

The bytes are a plain WebSocket, so the gateway’s own rules apply:

  • The Origin guard. The gateway sees a client on loopback. A native client sends no Origin and is accepted. A page’s Origin must be a loopback or Tauri origin or be listed in [frontend] allowed_origins, or the upgrade is answered 403 (crates/voice_gateway/src/browser_origin.rs).
  • Protocol 5. The gateway sends hello first and the client answers with its own hello (protocol_version: 5), as for any frontend. The client may name the route in its hello’s capabilities.reach: {route: "iroh", via: "direct"|"relay", rtt_ms, from}, closed words and a fleet label, never an address. The Admin’s Live sessions row shows it.
  • Audio is the frontend protocol’s binary PCM16 frames inside the WebSocket. For speech over a lossy or relayed path, reach-voice.v1 carries the same session with Opus datagrams. A client that is refused there falls back to this ALPN.

What Vulpine’s own clients do (not normative)

vulpine-reach open ws carries its stdin and stdout over one such stream; the Admin’s onboarding check opens one. It writes reach_path via=<relay|direct> rtt_ms=<n> on stderr at open and at every path switch. vulpine-reach voice relay falls back to this ALPN when vulpine/voice/1 is refused or off. The loopback Client Core behind it is the same either way.

Compatibility

  • Nothing on the stream belongs to reach, so a change to the frontend protocol is that protocol’s change (PROTOCOL_VERSION), never this ALPN’s.
  • Anything reach would add to the stream (a header, a framing) takes vulpine/ws/2.

See also

  • API surfaces: this ALPN’s row and its stability label.
  • The frontend protocol’s JSON Schema: frontend.v5.schema.json.
  • ADR 0053.

Was this page helpful?