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();
  }
};
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, and fields; the program accepts or refuses it),
  • WT_DATAGRAM (a datagram of an accepted session, a window onto data),
  • WT_STREAM (the client opened a stream of an accepted session: stream, bidirectional),
  • WT_STREAM_DATA (its bytes, a window onto data),
  • WT_STREAM_END (its FIN),
  • WT_STREAM_RESET (the client reset its side: errorCode, the HTTP/3 code, and appCode, 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) and WT_CLOSED (the session is over: errorCode, the CLOSE capsule's code or 0, the reason a window onto data, and closedByPeer).

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
codei64required

An 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
codei64required

The 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.