This document describes the browser WebTransport path added for Phase 77.1.2. It covers the server-side HTTP/3 CONNECT flow, browser fallback behavior, and how Nexus envelopes map onto WebTransport streams and datagrams.
Server Flow#
Drawn from its Mermaid source.
As text
Participants: - Browser - HTTP/3 h3+quinn - Nexus WebTransport Session - NexusCluster Steps: - 1. Browser to HTTP/3 h3+quinn: CONNECT /nexus/webtransport (:protocol=webtransport) - 2. HTTP/3 h3+quinn to Nexus WebTransport Session: validate authority, origin, certificate hash, fingerprint - 3. Nexus WebTransport Session: apply per-fingerprint connect rate limits - 4. Nexus WebTransport Session to Browser: 200 CONNECT accepted (reply) - 5. Browser to Nexus WebTransport Session: bidirectional stream with length-prefixed NexusEnvelope - 6. Nexus WebTransport Session to NexusCluster: ingest_client_envelope - 7. NexusCluster to Nexus WebTransport Session: queued snapshots/events (reply) - 8. Nexus WebTransport Session to Browser: server-initiated unidirectional streams (reply) - 9. Browser to Nexus WebTransport Session: QUIC datagrams with NXQD sequenced frames - 10. Nexus WebTransport Session: reject stale or reordered datagrams
Show source
sequenceDiagram
participant Browser
participant H3 as HTTP/3 h3+quinn
participant WT as Nexus WebTransport Session
participant Cluster as NexusCluster
Browser->>H3: CONNECT /nexus/webtransport (:protocol=webtransport)
H3->>WT: validate authority, origin, certificate hash, fingerprint
WT->>WT: apply per-fingerprint connect rate limits
WT-->>Browser: 200 CONNECT accepted
Browser->>WT: bidirectional stream with length-prefixed NexusEnvelope
WT->>Cluster: ingest_client_envelope
Cluster-->>WT: queued snapshots/events
WT-->>Browser: server-initiated unidirectional streams
Browser->>WT: QUIC datagrams with NXQD sequenced frames
WT->>WT: reject stale or reordered datagrams
Browser Selection#
Drawn from its Mermaid source.
As text
Parts: - Start browser connection - Secure context? (decision) - Blocked or WebSocket fallback - WebTransport constructor? (decision) - HTTP/3 datagrams available? (decision) - Use WebTransport - WebSocket fallback enabled? (decision) - Use WebSocket with session ticket - Fail connection Connections: - Start browser connection to Secure context? - Secure context? to Blocked or WebSocket fallback: no - Secure context? to WebTransport constructor?: yes - WebTransport constructor? to Blocked or WebSocket fallback: no - WebTransport constructor? to HTTP/3 datagrams available?: yes - HTTP/3 datagrams available? to Blocked or WebSocket fallback: no - HTTP/3 datagrams available? to Use WebTransport: yes - Blocked or WebSocket fallback to WebSocket fallback enabled? - WebSocket fallback enabled? to Use WebSocket with session ticket: yes - WebSocket fallback enabled? to Fail connection: no
Show source
flowchart TD
A[Start browser connection] --> B{Secure context?}
B -- no --> F[Blocked or WebSocket fallback]
B -- yes --> C{WebTransport constructor?}
C -- no --> F
C -- yes --> D{HTTP/3 datagrams available?}
D -- no --> F
D -- yes --> E[Use WebTransport]
F --> G{WebSocket fallback enabled?}
G -- yes --> H[Use WebSocket with session ticket]
G -- no --> I[Fail connection]
Channel Mapping#
| Nexus reliability or message | WebTransport channel |
|---|---|
| Client reliable ordered commands | Bidirectional stream |
| Server snapshots and events | Server-initiated unidirectional stream |
| Unreliable sequenced state updates | WebTransport datagram |
| Browser without WebTransport support | WebSocket fallback |
Stream payloads use the same four-byte big-endian length prefix as the native
QUIC transport. Datagram payloads use the NXQD frame header with a version
byte, a big-endian sequence number, and a length-prefixed Nexus envelope.
Certificate Hash Pinning#
Development self-signed certificates are pinned by SHA-256 leaf certificate
hash. The Rust server helper derives the pin from the QUIC certificate bundle;
the TypeScript SDK normalizes the same 32-byte hash into the browser
serverCertificateHashes option.
Production deployments should rely on ACME-managed certificates and can leave the development hash list empty.
Metrics#
The WebTransport server reports RTT, packet loss, datagram drop ratio, queued
server-push depth, fallback activations, and in-flight bytes. These values are
converted into NexusSessionBandwidthMetrics for the existing connection
quality monitoring and bandwidth adaptation systems.