AtlatestRepositorysigil-http3

sigil-http3 / tree / docswebtransport-router.md

Read it rendered

1# WebTransport router application contract
2
3The router has no sockets and does not advertise SETTINGS or transport
4parameters. Construct it with explicit authority/path/origin authorization,
5negotiation and command callbacks. Protocol defaults to `webtransport`; the
6application chooses draft response headers only after measured client interop.
7Input requests pass the shared HTTP/3 field/HEADERS/DATA validator first.
8
9Feed `webtransport-router-input!` the HTTP/3 adapter's raw application streams,
10including their first type/session prefix. Input is at most 4,103 bytes to
11accommodate the adapter preserving a fragmented eight-byte uni type in front
12of a 4,096-byte read. The router strips a WebTransport prefix once, then splits
13application/control payload delivery into at most 4,096-byte chunks. Feed
14`webtransport-router-datagram!` a negotiated QUIC DATAGRAM's data field,
15including the RFC 9297 quarter-stream-ID prefix.
17Call `webtransport-router-step!` with nondecreasing elapsed milliseconds before
18each receive/pump round. The negotiation callback returns `pending` until
19peer SETTINGS arrive, `ready` only when the selected HTTP/3 and QUIC
20capabilities are negotiated, and `unavailable` otherwise. The application's
21QUIC capability test must remain false while the dependency lacks DATAGRAM.
23Commands run synchronously. Do not re-enter the router from its command
24callback. Apply transport actions or log them before returning:
26| Command vector | Application action |
27| --- | --- |
28| `#(response id status request-fields)` | Encode response HEADERS. For 200, add the selected profile's response fields and keep CONNECT open. For rejection, send FIN. |
29| `#(open session request-fields)` | Record the accepted session and its origin/authority/path. |
30| `#(stream session id bytes fin?)` | Deliver opaque payload bytes. A bidi echo writes to the same ID without a response prefix. A uni echo opens one server uni stream, writes `0x54` plus session ID once, then retains that mapping for subsequent chunks and FIN. |
31| `#(datagram session payload)` | Deliver the application datagram. An echo uses the quarter-stream-ID encoder and the negotiated unreliable QUIC API. A capsule-origin datagram has the same application semantics; its source is not proof of unreliable delivery. |
32| `#(drain session)` | Log draining. Existing session traffic can continue. |
33| `#(close session code reason stream-ids)` | Close CONNECT's send side with FIN and retire associated transport streams and any paired server uni streams. Cancel pending/retransmitted output. |
34| `#(end session)` | Log CONNECT receive FIN; avoid a duplicate send FIN after `close`. |
35| `#(retire id code)` | Apply `h3-server-retire-stream!` to the indicated application stream. |
36| `#(reset session id code)` | Retire that stream and any paired uni output. |
37| `#(aborted session code stream-ids)` | Retire CONNECT, associated input streams and paired uni output. |
38| `#(connection-closed session stream-ids)` | Discard application state and log teardown. The transport is already closed; send nothing. |
40Feed peer RESET/STOP observations through `webtransport-router-reset!`. Call
41`webtransport-router-close!` on connection teardown. Session close commands
42must also retire server uni outputs: the router only knows peer stream IDs.
44Limits are per connection: one lifetime session by default (configurable up to
45four), 24 input descriptors, 8 KiB per waiting stream, 32 KiB aggregate waiting
46data and a five-second wait deadline. Expired input is retired before a late
47negotiation result can release it. Unknown-session datagrams are dropped rather
48than queued. Closed sessions count toward the lifetime limit, so repeated
49opens cannot grow retained session state. Each session also bounds lifetime
50associated stream IDs and aggregate payload bytes. The echo application must
51add connection/request/data rate limits and a bounded listener lifetime.