nish/net/webtransport
WebTransport over HTTP/3, server side, as draft-ietf-webtrans-http3-02 has it and as Chrome and the wtransport 0.7 crate negotiate it: sessions made by an extended CONNECT (RFC 9220) with :protocol webtransport, HTTP datagrams (RFC 9297) carrying the session's quarter stream ID, the session's unidirectional and bidirectional streams, and CLOSE_WEBTRANSPORT_SESSION and DRAIN_WEBTRANSPORT_SESSION on the CONNECT stream's capsules. It is a layer over one Http3Connection (nish/net/http3), whose Http3Config turns WebTransport on with webtransportSessions, and is sans-IO like it.
import {
WT_BUFFERED_STREAM_REJECTED,
WT_CAPSULE_CLOSE,
WT_CAPSULE_DRAIN,
WT_CLOSED,
WT_DATAGRAM,
WT_DRAIN,
WT_FIRST_APP_CODE,
WT_LIMIT,
WT_REASON_MAX,
WT_SESSION,
WT_SESSION_GONE,
WT_STREAM,
WT_STREAM_DATA,
WT_STREAM_END,
WT_STREAM_RESET,
WT_STREAM_STOPPED,
WT_WRITABLE,
WebTransport,
WebTransportConfig,
WebTransportWaiting,
wtCodeFromHttp3,
wtCodeToHttp3,
} from "nish/net/webtransport";
import { WebTransport, WebTransportConfig, WT_SESSION, WT_DATAGRAM } from "nish/net/webtransport";
import { Http3Connection, H3_NEED_MORE, H3_ERROR } from "nish/net/http3";
// h3's Http3Config has webtransportSessions above 0.
const serve = (h3: Http3Connection): void => {
// once per slot, beside its Http3Connection:
const wt = new WebTransport(new WebTransportConfig(), h3);
// after quic.receive(...):
let event: i32 = wt.next();
while (event !== H3_NEED_MORE && event !== H3_ERROR) {
// WT_SESSION: wt.sessionId, wt.fields (path, get("origin")) — accept or refuse it
// WT_DATAGRAM: wt.sessionId, wt.data[wt.dataStart .. wt.dataStart + wt.dataLength)
if (event === WT_SESSION) { wt.accept(wt.sessionId); }
if (event === WT_DATAGRAM) { wt.sendDatagram(wt.sessionId, wt.data, wt.dataStart, wt.dataLength); }
event = wt.next();
}
};
wtCodeFromHttp3
The application code an HTTP/3 code carries, or -1 when it is outside the range, or one of its greased values.
wtCodeToHttp3
The HTTP/3 code an application's 32-bit code is sent as (WT_FIRST_APP_CODE + n + n / 0x1e, skipping the greased values).
WebTransport
The WebTransport sessions of one HTTP/3 connection.
WebTransportConfig
The caps of a WebTransport layer, fixed when it is made.
WebTransportWaiting
The streams waiting for a session (draft-02 §4.5): at most size, filed by the session ID they named in a hash keyed with bytes of entropy, each bucket a list in arrival order.
Events
next() answers a WT_* event, or one of nish/net/http3's for a plain
request, which passes through untouched so one connection can serve both:
-
WT_SESSION(a session asked for:sessionId, the CONNECT stream's ID, andfields; the programaccepts orrefuses it), WT_DATAGRAM(a datagram of an accepted session, a window ontodata),-
WT_STREAM(the client opened a stream of an accepted session:stream,bidirectional), WT_STREAM_DATA(its bytes, a window ontodata),WT_STREAM_END(its FIN),-
WT_STREAM_RESET(the client reset its side:errorCode, the HTTP/3 code, andappCode, the WebTransport code it maps to or -1), -
WT_STREAM_STOPPED(the client asked this side to stop writing: the same two codes), -
WT_WRITABLE(a stream, or a CONNECT stream whose capsule was held back, can take more), -
WT_DRAIN(the client sent DRAIN_WEBTRANSPORT_SESSION) andWT_CLOSED(the session is over:errorCode, the CLOSE capsule's code or 0, the reason a window ontodata, andclosedByPeer).
Each event names its session in sessionId and in session, its index in
the table, 0 .. webtransportSessions - 1, for a program's own per-session
arrays. A window is valid until the next call.
Writes
sendDatagram (the quarter stream ID, then the payload, one
QUIC DATAGRAM frame; maxDatagramPayload says how much fits), openStream,
write, resetStream, stopSending, close (CLOSE_WEBTRANSPORT_SESSION
and the FIN) and drain. Each answers 0 or a count, or one of
nish/net/http3's codes: H3_AGAIN, H3_CLOSED, H3_INVALID, H3_TOO_LARGE,
and WT_LIMIT for a stream past the session's cap.
A session
A session is the CONNECT stream's ID (draft-02 §2). A request is a
session when its :protocol is webtransport, its :scheme https, and
the client's SETTINGS offered SETTINGS_H3_DATAGRAM 1 and either
SETTINGS_ENABLE_WEBTRANSPORT 1 or SETTINGS_WEBTRANSPORT_MAX_SESSIONS
(§3.1); otherwise it is answered here and never reaches the program — 501
for another :protocol (RFC 8441 §4), 400 for the rest — as is one past
the session cap, with 429. accept answers 200 with
sec-webtransport-http3-draft: draft02, the response header Chrome's
draft-02 client looks for. With WebTransport on, nish/net/http3 holds a
request until the client's SETTINGS have arrived (§3.1), and an extended
CONNECT is malformed, H3_MESSAGE_ERROR, where this side did not send
SETTINGS_ENABLE_CONNECT_PROTOCOL (RFC 9220 §3).
Datagrams
Datagrams (RFC 9297 §2.1). A datagram whose quarter stream ID does not
parse, or names a stream past 2^62, is H3_DATAGRAM_ERROR and closes the
connection; one for a session that is not accepted — unknown, gone, or not
yet answered — is dropped and counted in datagramsDropped.
Streams
Streams (§4). A stream names its session in its first bytes;
nish/net/http3 reads them and holds the stream. One for an accepted
session is taken, up to maxStreams at once, and refused past it with
H3_REQUEST_REJECTED; one for a session asked for but not answered, or one
whose CONNECT stream has not arrived, waits — up to maxPending at once,
unread, so QUIC's flow control holds the client back — and is refused with
WT_BUFFERED_STREAM_REJECTED past that (§4.5); one for a session that is
gone, refused or was never one is refused with WT_SESSION_GONE. Refusing a
stream resets this side and asks the client to stop.
Capsules
Capsules (RFC 9297 §3) on the CONNECT stream's DATA: CLOSE (0x2843: a 32-bit code and a UTF-8 reason of at most 1024 bytes) and DRAIN (0x78ae, empty) are read; any other type is skipped. A CLOSE outside those lengths, a DRAIN with a payload, or the stream ending inside a capsule is H3_DATAGRAM_ERROR, and anything after a CLOSE is H3_MESSAGE_ERROR (§5); each resets the CONNECT stream and ends the session. A session ends when either side sends CLOSE, or the CONNECT stream ends or is reset: every one of its streams is then reset with WT_SESSION_GONE, and this side's half of the CONNECT stream finished.
Caps are start-up numbers: the sessions (Http3Config.webtransportSessions),
the streams of one session and the streams waiting for theirs
(WebTransportConfig), and the datagram queues, which are the QUIC
connection's rings (QUIC_CONN_DATAGRAM_QUEUE each way). Every array is
made by the constructor; a session, a stream and a datagram find their
state through the QUIC connection's stream index, never by a scan, and
nothing a warm session does allocates. Counters a peer drives saturate.
The clock
Each session keeps the time of its last activity
(monotonicNanos, read once a call of next): its request, its accept,
a datagram or a stream event either way, a capsule. expire(now), called
from the program's loop as Http1Server.expire is, ends every session
quiet for longer than WebTransportConfig.idleTimeout: one never answered
is refused with 503, an accepted one is closed (CLOSE with code 0 and the
FIN, or a reset both ways when the capsule does not fit), and one already
closed whose client never finished its half is let go. Each session it
ends that the program still held is reported by the next calls of next
as WT_CLOSED, closedByPeer false, code 0. A session takes at most
maxDatagramsPerSecond datagrams in each fixed one-second window, the
first starting when the session is asked for and the next at the first
datagram a second or more after it; the rest are dropped and counted in
datagramsDropped. The window does not slide, so across a boundary up to
twice the cap can arrive within a second.
Error codes
A stream's reset and STOP_SENDING carry an HTTP/3 code;
a WebTransport application's 32-bit code maps into the range from
0x52e4a40fa8db (wtCodeToHttp3, wtCodeFromHttp3), as Chrome maps it.
wtransport 0.7 sends its codes unmapped, so an event carries both.
Private helpers share the importing program's flat symbol namespace
(docs/wp26-stdlib.md §3e), which is why each one carries the module's name.
Written from draft-ietf-webtrans-http3-02, RFC 9220 and RFC 9297, with the
identifiers checked against wtransport 0.7.0 and Chrome's behaviour; no
code is ported from either.
Functions
wtCodeFromHttp3
The application code an HTTP/3 code carries, or -1 when it is outside the range, or one of its greased
values.
const wtCodeFromHttp3: (code: i64) => i64
codei64requiredAn HTTP/3 error code, such as a peer's RESET_STREAM or STOP_SENDING code; any value.
returnsi64
The 32-bit application code, 0 to 2^32 - 1, the inverse of wtCodeToHttp3; -1 for a code below
WT_FIRST_APP_CODE, above wtCodeToHttp3(0xffffffff), or greased.
wtCodeToHttp3
The HTTP/3 code an application's 32-bit code is sent as (WT_FIRST_APP_CODE + n + n / 0x1e, skipping
the greased values).
const wtCodeToHttp3: (code: i64) => i64
codei64requiredThe application's code; only its low 32 bits are used, so a value past 2^32 - 1 or below 0 is taken as those bits.
returnsi64
The HTTP/3 error code, from WT_FIRST_APP_CODE to wtCodeToHttp3(0xffffffff), never a greased
value.
Classes
WebTransport
The WebTransport sessions of one HTTP/3 connection. The fields after the tables are the last event's; the module comment says which event sets which.
class WebTransport
| Member | |
|---|---|
new WebTransport(config: WebTransportConfig, h3: Http3Connection) |
The WebTransport layer of h3, whose Http3Config must have webtransportSessions above 0. A cap out of range panics. |
appCode: i64 |
The WebTransport code errorCode maps to (wtCodeFromHttp3), or -1 when it maps to none; for WT_CLOSED, errorCode itself. |
bidirectional: boolean |
WT_STREAM's kind, and whether WT_CLOSED came from the client. |
closedByPeer: boolean |
Whether the last WT_CLOSED came from the client: its CLOSE capsule, its FIN, or a reset the client sent; false when this side ended the session, including when it reset the stream for a malformed capsule or a FIN inside one. |
config: WebTransportConfig |
The caps this layer was made with; the arrays they size are made by the constructor. |
data: u8[] |
The buffer the window of WT_DATAGRAM, WT_STREAM_DATA and WT_CLOSED lies in: this layer's own datagram buffer, the Http3Connection's data, or this layer's store of CLOSE reasons. Valid until the next call. |
datagramsDropped: i32 |
Counters for a log or a test, each saturating: datagrams dropped, sessions refused here, streams refused. |
datagramsIn: i32[] |
Counters for a log or a rate cap, each saturating: datagrams in and out. |
datagramsOut: i32[] |
How many datagrams each session sent, saturating at 2^31 - 1; zeroed when a session is asked for. |
dataLength: i32 |
How many bytes the last event's window has. |
dataStart: i32 |
Where the last event's window starts in data. |
errorCode: i64 |
The HTTP/3 code of the last WT_STREAM_RESET or WT_STREAM_STOPPED, or the 32-bit code of the last WT_CLOSED's CLOSE capsule (0 when the session ended without one). |
fields: HttpFields |
The request fields of the last WT_SESSION: the same object as the Http3Connection's fields. |
freeCount: i32 |
How many session indexes are free; a valid request for a session while none is free is answered 429. |
session: i32 |
The last event's session index, and its window onto data. |
sessionAt: i32[] |
The session whose CONNECT stream the slot holds, or -1. |
sessionId: i64 |
The last event's session ID, stream, and codes. |
sessionIds: i64[] |
Each session's ID, its CONNECT stream's ID, by session index; -1 for a free index. |
sessionsRefused: i32 |
How many requests for a session this layer answered with a 400, 429 or 501, or refuse refused. |
stream: i64 |
The stream ID of the last event about a stream: the client's or this side's stream, or the session's CONNECT stream; a WT_DATAGRAM leaves it as it was. |
streamCount: i32[] |
How many streams each session holds, the client's and this side's together, up to maxStreams; a stream stops counting once both of its sides are over. |
waiting: WebTransportWaiting |
The streams waiting for a session. |
accept(id: i64): i32 |
Accepts session id with a 200 (draft-02 §3.2): its datagrams and streams reach the program from now on, the streams that waited for it first. Answers 0, H3_AGAIN when the response does not fit yet, or H3_CLOSED for one that is not a session asked for. |
close(id: i64, code: i64, buf: u8[], off: i32, len: i32): i32 |
Closes session id (draft-02 §5): CLOSE_WEBTRANSPORT_SESSION with the application's code and the reason buf[off .. off + len), at most 1024 bytes of UTF-8, then the FIN; every stream of the session is reset with WT_SESSION_GONE. Answers 0; H3_INVALID for a reason too long; H3_AGAIN while the CONNECT stream has no room for the capsule, and WT_WRITABLE then names it; or H3_CLOSED. |
drain(id: i64): i32 |
Sends DRAIN_WEBTRANSPORT_SESSION on session id: the client should finish and close it. Answers 0, H3_AGAIN, or H3_CLOSED. |
expire(now: i64): i32 |
Ends every session quiet for longer than idleTimeout at now (see the module comment): one never answered is refused with 503, an accepted one closed with code 0, and one already closed whose client never finished its half let go. Call it from the program's loop; it returns at once before the soonest deadline it last saw. The next calls of next report each session the program held as WT_CLOSED. |
expiresNoSooner(now: i64): i64 |
The soonest expire could end a session, at or after now: activity only moves a session's deadline later. |
maxDatagramPayload(id: i64): i32 |
The largest payload sendDatagram takes for session id now: what the QUIC connection's maxDatagramPayload leaves after the quarter stream ID; 0 for a session not accepted. |
next(): i32 |
Reads what the connection has and answers the next event (see the module comment): a WT_* one, or a plain request's H3_* one. Call it until it answers H3_NEED_MORE or H3_ERROR. |
openStream(id: i64, bidirectional: boolean): i64 |
Opens a stream of this side's for session id (draft-02 §4.1, §4.2). Answers its ID; WT_LIMIT when the session holds maxStreams; H3_AGAIN while the client's MAX_STREAMS allows no more; or H3_CLOSED. |
refuse(id: i64, status: i32): i32 |
Refuses session id with status, 400 to 599 (draft-02 §3.2): the response ends the stream, and what the client still sends is dropped. Answers 0, H3_INVALID for a status out of range, or H3_CLOSED. |
resetStream(id: i64, code: i64): i32 |
Resets this side of session stream id with the application's code (mapped, wtCodeToHttp3). |
sendDatagram(id: i64, buf: u8[], off: i32, len: i32): i32 |
Sends buf[off .. off + len) as an HTTP datagram of session id (RFC 9297 §2.1): its quarter stream ID, then the payload, one QUIC DATAGRAM frame, never sent again if lost. Answers 0; H3_TOO_LARGE past maxDatagramPayload; H3_AGAIN while QUIC's queue is full; or H3_CLOSED for a session not accepted. |
stopSending(id: i64, code: i64): i32 |
Asks the client to stop its side of session stream id with the application's code, and drops what it sends. |
write(id: i64, buf: u8[], off: i32, len: i32, fin: boolean): i32 |
Writes up to len bytes of buf from off to session stream id, with its FIN when fin and all were taken. Answers how many it took, or H3_AGAIN, or H3_CLOSED (see Http3Connection.writeStream). |
WebTransportConfig
The caps of a WebTransport layer, fixed when it is made.
class WebTransportConfig
| Member | |
|---|---|
new WebTransportConfig() |
|
idleTimeout: i32 |
Milliseconds a session may go without activity before expire ends it, 1 to 86,400,000: a session asked for counts from its request, an accepted one from its last datagram or stream event either way, and one this side closed from its close. |
maxDatagramsPerSecond: i32 |
Datagrams one session may deliver in a second, 1 to 1,048,576; the rest are dropped and counted in datagramsDropped. Dropping is the whole defence: no count of drops closes the session. Datagrams are unreliable by contract (RFC 9297), so a dropped one is a loss the application already handles; a drop costs O(1); a close would punish a browser that bursts; and a client past the cap gains nothing but the CPU its datagrams cost to drop. |
maxPending: i32 |
Streams that may wait at once for a session not yet answered or not yet arrived (draft-02 §4.5). |
maxStreams: i32 |
Streams one session may have at once, both kinds and both openers together. |
WebTransportWaiting
The streams waiting for a session (draft-02 §4.5): at most size, filed
by the session ID they named in a hash keyed with bytes of entropy, each
bucket a list in arrival order. A session's waiting streams, and whether a
request's stream has any, are found by one probe and a walk of that
bucket, never by a pass over the room, so a client choosing session IDs
cannot make a request, an accept or a close cost the room's size.
class WebTransportWaiting
| Member | |
|---|---|
new WebTransportWaiting(size: i32) |
Makes an empty room, its hash salted with 4 bytes from crypto.getRandomValues. |
count: i32 |
How many streams are waiting now. |
Limits
1,024
WT_REASON_MAX: i32
The longest reason a CLOSE capsule carries.
Constants
0x3994bd84
WT_BUFFERED_STREAM_REJECTED: i64
A stream refused because no more may wait for their session (§4.5).
0x2843
WT_CAPSULE_CLOSE: i64
CLOSE_WEBTRANSPORT_SESSION's capsule type (draft-02 §5).
0x78ae
WT_CAPSULE_DRAIN: i64
DRAIN_WEBTRANSPORT_SESSION's capsule type.
24
WT_CLOSED: i32
The session is over: errorCode, the reason data[dataStart .. dataStart + dataLength), closedByPeer.
17
WT_DATAGRAM: i32
A datagram of an accepted session: data[dataStart .. dataStart + dataLength).
25
WT_DRAIN: i32
The client sent DRAIN_WEBTRANSPORT_SESSION: it will close the session soon.
0x52e4a40fa8db
WT_FIRST_APP_CODE: i64
The first HTTP/3 code a WebTransport application code maps to.
-24
WT_LIMIT: i32
A stream past the session's maxStreams: Linux's EMFILE.
16
WT_SESSION: i32
A session asked for: sessionId, fields.
H3_WT_SESSION_GONE
WT_SESSION_GONE: i64
A stream of a session that is gone (draft-02 §4.5).
18
WT_STREAM: i32
The client opened a stream of an accepted session: stream, bidirectional.
19
WT_STREAM_DATA: i32
A stream's bytes: stream, data[dataStart .. dataStart + dataLength).
20
WT_STREAM_END: i32
A stream's FIN: stream.
21
WT_STREAM_RESET: i32
The client reset its side of stream: errorCode, appCode.
22
WT_STREAM_STOPPED: i32
The client asked this side of stream to stop, and QUIC reset it: errorCode, appCode.
23
WT_WRITABLE: i32
stream — a session's stream, or its CONNECT stream — can take more.

