Eve library

Maya Nexus WebTransport Lifecycle

Guide

Revision 1

On this page

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#

Sequence diagramSequence diagram: 4 participants and 10 messages.1Browser to HTTP/3 h3+quinnCONNECT /nexus/webtransport (:protocol=webtransport)2HTTP/3 h3+quinn to Nexus WebTransport Sessionvalidate authority, origin, certificate hash, fingerprint3Nexus WebTransport Sessionapply per-fingerprint connect rate limits4Nexus WebTransport Session to Browser200 CONNECT accepted5Browser to Nexus WebTransport Sessionbidirectional stream with length-prefixed NexusEnvelope6Nexus WebTransport Session to NexusClusteringest_client_envelope7NexusCluster to Nexus WebTransport Sessionqueued snapshots/events8Nexus WebTransport Session to Browserserver-initiated unidirectional streams9Browser to Nexus WebTransport SessionQUIC datagrams with NXQD sequenced frames10Nexus WebTransport Sessionreject stale or reordered datagrams
Sequence diagram: Sequence diagram. Sequence diagram: 4 participants and 10 messages.

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#

FlowchartFlowchart: 9 steps and 10 connections.noyesnoyesnoyesyesnoStart browser connectionSecure context?Blocked or WebSocketfallbackWebTransportconstructor?HTTP/3 datagramsavailable?Use WebTransportWebSocket fallbackenabled?Use WebSocket withsession ticketFail connection
Flowchart: Flowchart. Flowchart: 9 steps and 10 connections.

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.