AtlatestRepositorysigil-http3
sigil-http3 / tree / docswebtransport-router.md
1
# WebTransport router application contract3
The router has no sockets and does not advertise SETTINGS or transport4
parameters. Construct it with explicit authority/path/origin authorization,5
negotiation and command callbacks. Protocol defaults to `webtransport`; the6
application chooses draft response headers only after measured client interop.7
Input requests pass the shared HTTP/3 field/HEADERS/DATA validator first.9
Feed `webtransport-router-input!` the HTTP/3 adapter's raw application streams,10
including their first type/session prefix. Input is at most 4,103 bytes to11
accommodate the adapter preserving a fragmented eight-byte uni type in front12
of a 4,096-byte read. The router strips a WebTransport prefix once, then splits13
application/control payload delivery into at most 4,096-byte chunks. Feed14
`webtransport-router-datagram!` a negotiated QUIC DATAGRAM's data field,15
including the RFC 9297 quarter-stream-ID prefix.17
Call `webtransport-router-step!` with nondecreasing elapsed milliseconds before18
each receive/pump round. The negotiation callback returns `pending` until19
peer SETTINGS arrive, `ready` only when the selected HTTP/3 and QUIC20
capabilities are negotiated, and `unavailable` otherwise. The application's21
QUIC capability test must remain false while the dependency lacks DATAGRAM.23
Commands run synchronously. Do not re-enter the router from its command24
callback. 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. |40
Feed peer RESET/STOP observations through `webtransport-router-reset!`. Call41
`webtransport-router-close!` on connection teardown. Session close commands42
must also retire server uni outputs: the router only knows peer stream IDs.44
Limits are per connection: one lifetime session by default (configurable up to45
four), 24 input descriptors, 8 KiB per waiting stream, 32 KiB aggregate waiting46
data and a five-second wait deadline. Expired input is retired before a late47
negotiation result can release it. Unknown-session datagrams are dropped rather48
than queued. Closed sessions count toward the lifetime limit, so repeated49
opens cannot grow retained session state. Each session also bounds lifetime50
associated stream IDs and aggregate payload bytes. The echo application must51
add connection/request/data rate limits and a bounded listener lifetime.