sigil-http3 / tree / docswebtransport-router.md
WebTransport router application contract
The router has no sockets and does not advertise SETTINGS or transport parameters. Construct it with explicit authority/path/origin authorization, negotiation and command callbacks. Protocol defaults to webtransport; the application chooses draft response headers only after measured client interop. Input requests pass the shared HTTP/3 field/HEADERS/DATA validator first.
Feed webtransport-router-input! the HTTP/3 adapter's raw application streams, including their first type/session prefix. Input is at most 4,103 bytes to accommodate the adapter preserving a fragmented eight-byte uni type in front of a 4,096-byte read. The router strips a WebTransport prefix once, then splits application/control payload delivery into at most 4,096-byte chunks. Feed webtransport-router-datagram! a negotiated QUIC DATAGRAM's data field, including the RFC 9297 quarter-stream-ID prefix.
Call webtransport-router-step! with nondecreasing elapsed milliseconds before each receive/pump round. The negotiation callback returns pending until peer SETTINGS arrive, ready only when the selected HTTP/3 and QUIC capabilities are negotiated, and unavailable otherwise. The application's QUIC capability test must remain false while the dependency lacks DATAGRAM.
Commands run synchronously. Do not re-enter the router from its command callback. Apply transport actions or log them before returning:
| Command vector | Application action |
|---|---|
#(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. |
#(open session request-fields) | Record the accepted session and its origin/authority/path. |
#(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. |
#(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. |
#(drain session) | Log draining. Existing session traffic can continue. |
#(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. |
#(end session) | Log CONNECT receive FIN; avoid a duplicate send FIN after close. |
#(retire id code) | Apply h3-server-retire-stream! to the indicated application stream. |
#(reset session id code) | Retire that stream and any paired uni output. |
#(aborted session code stream-ids) | Retire CONNECT, associated input streams and paired uni output. |
#(connection-closed session stream-ids) | Discard application state and log teardown. The transport is already closed; send nothing. |
Feed peer RESET/STOP observations through webtransport-router-reset!. Call webtransport-router-close! on connection teardown. Session close commands must also retire server uni outputs: the router only knows peer stream IDs.
Limits are per connection: one lifetime session by default (configurable up to four), 24 input descriptors, 8 KiB per waiting stream, 32 KiB aggregate waiting data and a five-second wait deadline. Expired input is retired before a late negotiation result can release it. Unknown-session datagrams are dropped rather than queued. Closed sessions count toward the lifetime limit, so repeated opens cannot grow retained session state. Each session also bounds lifetime associated stream IDs and aggregate payload bytes. The echo application must add connection/request/data rate limits and a bounded listener lifetime.