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#

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#

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.