# Maya Nexus WebTransport Lifecycle

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

```mermaid
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

```mermaid
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.
