nish/net/http3
The server side of an HTTP/3 connection (RFC 9114) on the streams of a QuicConnection (nish/net/quic): the control stream and SETTINGS both ways, the QPACK encoder and decoder streams (opened, at dynamic table capacity 0), requests and responses on bidirectional streams with their bodies streamed both ways, GOAWAY, and RFC 9114's error codes. Field sections are encoded and decoded by nish/net/qpack and checked by nish/net/http-fields.
import {
H3_AGAIN,
H3_ALPN,
H3_CLOSED,
H3_CONTROL_FRAME_MAX,
H3_DATA,
H3_DROPPED,
H3_END,
H3_ERROR,
H3_GOAWAY,
H3_INVALID,
H3_MAX_SESSIONS,
H3_NEED_MORE,
H3_NO_APPLICATION_PROTOCOL,
H3_REQUEST,
H3_RESET,
H3_STOPPED,
H3_STREAM,
H3_TOO_LARGE,
H3_TRAILERS,
H3_WRITABLE,
Http3Config,
Http3Connection,
} from "nish/net/http3";
import { Http3Config, Http3Connection, H3_NEED_MORE, H3_ERROR, H3_END } from "nish/net/http3";
import { httpFieldBytes } from "nish/net/http-fields";
import { QuicConnection } from "nish/net/quic";
// Once per slot, beside a server QuicConnection; restart() per connection.
const open = (quic: QuicConnection): Http3Connection => {
return new Http3Connection(new Http3Config(), quic);
}
// After each quic.receive(...):
const serve = (h3: Http3Connection): void => {
const names: u8[][] = [httpFieldBytes("content-type")];
const values: u8[][] = [httpFieldBytes("text/plain")];
const body: u8[] = httpFieldBytes("hello\n");
let event: i32 = h3.next();
while (event !== H3_NEED_MORE && event !== H3_ERROR) {
// H3_REQUEST: h3.stream, h3.fields (method, path, get("accept"))
// H3_DATA: h3.data[h3.dataStart .. h3.dataStart + h3.dataLength)
if (event === H3_END) { // the request is whole: respond
h3.respond(h3.stream, 200, names, values, false);
h3.writeData(h3.stream, body, 0, toI32(body.length), true); // answers how much it took
}
event = h3.next();
}
}
Http3Config
The connection's caps, fixed when it is made.
Http3Connection
One HTTP/3 connection, server side, over quic.
It is sans-IO in the way the QUIC connection under it is: the carrier
hands the QuicConnection its datagrams and takes the ones it sends, and
this module reads and writes that connection's streams. nish/net/http3-server
runs it over a UDP socket with ALPN h3.
Events
next() reads the streams the QUIC connection has news for and answers the
first thing that means something to the program:
H3_REQUEST(a request's field section, infields),-
H3_DATA(a piece of its body, a window ontodatavalid until the next call), H3_TRAILERS,H3_END(the request ended, and itscontent-length, if any, matched),-
H3_RESET(the stream is gone: the client reset it or stopped it, or it broke a rule that resets it —errorCodesays which,resetByPeerwho), H3_WRITABLE(a stream whose write was held back can take more),H3_GOAWAY(the client is going away;lastStreamIdis its push ID),-
and
H3_ERROR, final: the connection broke a rule, it is closed witherrorCode, and every later call answers it again.
H3_NEED_MORE asks for more datagrams. A request's events come in order —
REQUEST, DATA…, TRAILERS, END — and after H3_RESET its stream has no more.
Back-pressure
Back-pressure is QUIC's flow control. A body is read only as the
program calls next(), bodyChunk bytes at most at a time, and QUIC gives
the client more credit only as its receive buffer is read. writeData
takes as much as the stream's send buffer has room for and answers how much;
when it took less, H3_WRITABLE names the stream once acknowledgements free
room. HEADERS and trailers go whole or not at all (H3_AGAIN).
ALPN
A QUIC connection whose handshake chose anything but h3 is
closed with CRYPTO_ERROR no_application_protocol (0x0178) on the first
next() after it connects, before any HTTP/3 byte (§3.1).
Streams
Streams (§6). The connection opens its control stream, sends SETTINGS
first on it (SETTINGS_QPACK_MAX_TABLE_CAPACITY 0, SETTINGS_QPACK_BLOCKED_STREAMS
0 and SETTINGS_MAX_FIELD_SECTION_SIZE), and opens its QPACK encoder and
decoder streams, on which it sends nothing but their types. The client's
encoder and decoder streams go to nish/net/qpack's capacity-0 handling.
A unidirectional stream of a type it does not know is asked to stop
(H3_STREAM_CREATION_ERROR) and read to its end (§6.2).
What it refuses.
A connection error closes the QUIC connection with the code:
- a second control, encoder or decoder stream, or a push stream from a client (H3_STREAM_CREATION_ERROR, §6.2.1, §6.2.2);
- a control stream whose first frame is not SETTINGS (H3_MISSING_SETTINGS);
- the end, reset or STOP_SENDING of any critical stream, either side's (H3_CLOSED_CRITICAL_STREAM);
- a frame where it may not be — DATA or HEADERS on the control stream, a control frame on a request stream, a second SETTINGS, DATA before HEADERS, anything but the end after trailers, any PUSH_PROMISE from a client, and an HTTP/2 type HTTP/3 reserves (H3_FRAME_UNEXPECTED, §7.2.8);
- a frame cut off by its stream's end or a payload of the wrong length (H3_FRAME_ERROR, §7.1);
- a SETTINGS frame
nish/net/http3-framerefuses (H3_SETTINGS_ERROR); - a GOAWAY whose push ID rose, a MAX_PUSH_ID that fell, a CANCEL_PUSH past the push IDs allowed (H3_ID_ERROR, §5.2, §7.2.7, §7.2.3);
- a control frame past
H3_CONTROL_FRAME_MAX(H3_EXCESSIVE_LOAD); -
a request reset past what
resetBudgetallows — by the client, or by this side for a stream error or a 431 the client caused, net of the requests this side answered (H3_EXCESSIVE_LOAD, §10.5); - and QPACK's three.
A stream error resets one request, both ways, and the connection lives: a
field section nish/net/http-fields refuses, and a body that disagrees with
content-length (H3_MESSAGE_ERROR, §4.1.2); a request stream that ends
before its HEADERS (H3_REQUEST_INCOMPLETE, §4.1.1); a request on a stream at
or past the ID of the GOAWAY this side sent (H3_REQUEST_REJECTED, §5.2). A
request whose field section is longer than maxFieldSectionSize — the frame,
or the section once decoded — is answered with a 431, never reaches the
program, and its stream is asked to stop with H3_NO_ERROR (§4.2.2, §4.1.2).
No server push
It never sends PUSH_PROMISE; a client's MAX_PUSH_ID is allowed, checked and ignored.
Caps are start-up numbers, all in Http3Config. The stream state for
every QUIC stream slot and the control frame are made by the constructor;
the body chunk and the field section are borrowed, around one read, from
pools that a server's connections share and that a standalone
connection keeps one buffer each of. A field section's
names and values are copied into arrays the connection keeps, which grow to
the largest section seen and are then reused, so a warm connection
allocates nothing per request (docs/security/http3.md, H3-2). A peer's
counters saturate, and the lookup of a stream's state is the QUIC
connection's own hash index (QuicStreams.slotOf), never a scan.
Extended CONNECT and WebTransport
With extendedConnect the connection
sends SETTINGS_ENABLE_CONNECT_PROTOCOL 1 and a request may carry :protocol
(RFC 9220); without it :protocol is malformed, H3_MESSAGE_ERROR.
webtransportSessions above 0 turns that on and also sends
SETTINGS_H3_DATAGRAM 1, draft-02's SETTINGS_ENABLE_WEBTRANSPORT 1 and
draft-07's SETTINGS_WEBTRANSPORT_MAX_SESSIONS, and nish/net/webtransport
runs its sessions on top: a request then waits for the client's SETTINGS
(draft-02 §3.1), and a stream that opens with WebTransport's unidirectional
type (0x54) or bidirectional signal (0x41) is read as far as its session ID,
held unread and named in H3_STREAM until the program calls acceptStream
(its bytes then come as H3_DATA, H3_END, H3_RESET and H3_STOPPED, and
writeStream writes them as they are) or refuseStream.
openStream opens one of this side's; writeDataWhole writes a capsule; a
GOAWAY still lets a session's new stream in, and H3_DROPPED names a request
stream that ended before its request reached the program. The client's
SETTINGS_ENABLE_CONNECT_PROTOCOL and SETTINGS_H3_DATAGRAM must be 0 or 1
(H3_SETTINGS_ERROR), a session ID that is no client-initiated bidirectional
stream is H3_ID_ERROR, and the signal anywhere but a stream's start is
H3_FRAME_ERROR. Holding every request, not only an extended CONNECT, until
the client's SETTINGS keeps a decoded field section from having to be held
per stream; it costs a request only when the client's control stream is lost
or reordered.
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.
The Date
A response carries the date in conn.date, 29 bytes of
IMF-fixdate, right after :status, unless the program's fields hold their
own; trailers carry none. It counts against the peer's
SETTINGS_MAX_FIELD_SECTION_SIZE. A bare connection has no clock, so date
starts empty and nothing is sent; Http3Server fills it from its
HttpDate (RFC 9110 §6.6.1).
Written from RFC 9114 and RFC 9204, not ported from another implementation.
Classes
Http3Config
The connection's caps, fixed when it is made. maxFieldSectionSize is
advertised in SETTINGS and is the largest HEADERS frame read and the
largest section decoded; bodyChunk the most body handed to the program at
once; writeChunk the largest DATA frame written.
class Http3Config
| Member | |
|---|---|
new Http3Config() |
|
bodyChunk: i32 |
The body buffer: the largest H3_DATA window. |
extendedConnect: boolean |
Whether :protocol is accepted (RFC 9220's extended CONNECT), and SETTINGS_ENABLE_CONNECT_PROTOCOL sent. WebTransport turns it on. |
headTimeout: i32 |
The milliseconds a request's head may take to arrive whole, from its first byte or the last head before it, before clock closes the connection with H3_EXCESSIVE_LOAD (H3-5), 1 to 2^31 - 1. A body that trickles after its head is the program's to time, as a long response is. |
idleTimeout: i32 |
The milliseconds a connection may go without progress while no request is in hand before clock closes it (H3-5), 1 to 2^31 - 1. Progress is the connection starting, a request's head arriving whole, and the last request in hand finishing. With no request open the close is H3_NO_ERROR; with one still short of its head it is H3_EXCESSIVE_LOAD. |
maxFieldSectionSize: i32 |
SETTINGS_MAX_FIELD_SECTION_SIZE (§4.2.2): past it a request is answered with a 431. |
resetBudget: i32 |
How many requests may be reset before the connection is closed with H3_EXCESSIVE_LOAD, net of those this side answered: each request the client resets or stops, and each this side resets for a stream error or answers with a 431, costs one; each response this side ends with a FIN earns one back, up to this. Rapid reset (CVE-2023-44487) and MadeYouReset (CVE-2025-8671) over HTTP/3. |
webtransportSessions: i32 |
The WebTransport sessions this side takes at once (nish/net/webtransport), 0 for none. Above 0 it turns on extended CONNECT and sends SETTINGS_H3_DATAGRAM, SETTINGS_ENABLE_WEBTRANSPORT and SETTINGS_WEBTRANSPORT_MAX_SESSIONS, and the QUIC connection must take DATAGRAM frames; at 0 it must not (RFC 9297 §2.1.1). |
writeChunk: i32 |
The largest DATA frame writeData starts. |
Http3Connection
One HTTP/3 connection, server side, over quic. The fields after the
buffers are the last event's; the module comment says which event sets
which.
class Http3Connection
| Member | |
|---|---|
new Http3Connection(config: Http3Config, quic: QuicConnection) |
A connection under config over quic, whose configuration must let a HEADERS frame of maxFieldSectionSize fit half a stream's buffer, and one on every request stream fit half the connection's window, and let the client open the three unidirectional streams it needs and this side open its own three (§6.2). A cap out of range panics. |
data: u8[] |
H3_DATA's bytes, and where a payload being skipped is read to: a bodyChunk-byte buffer borrowed from dataPool for the read that needs it and held while an H3_DATA window is live, else an empty array. Any event but H3_DATA gives the buffer back, zeroed as far as reads wrote. |
dataLength: i32 |
H3_DATA's window length in bytes, 1 to bodyChunk; valid until the next next(). |
dataPool: BufferPool |
Where data is borrowed from: the connection's own pool until its server lends it the server's. |
dataStart: i32 |
Where H3_DATA's window onto data starts. |
date: u8[] |
The date every response carries (RFC 9110 §6.6.1), as the 29 bytes of an IMF-fixdate, or empty for none. A bare connection has no clock, so it starts empty; Http3Server points it at its HttpDate's bytes, which that rewrites in place once a second. |
decoder: QpackDecoder |
The QPACK decoder of the client's field sections, at dynamic table capacity 0; it also reads the client's encoder stream. |
encoder: QpackEncoder |
The QPACK encoder of this side's field sections; it also reads the client's decoder stream. |
errorCode: i64 |
H3_RESET's, H3_STOPPED's and H3_ERROR's code. |
fields: HttpFields |
The last request's or trailers' fields, valid until the next of either. |
generation: i32 |
How many times restart ran: a layer above that keeps state per connection compares it to know when to forget its own. |
lastStreamId: i64 |
H3_GOAWAY's push ID. |
live: i32 |
Requests open, taken and not yet finished both ways, plus the bidirectional WebTransport streams held after this side's GOAWAY for a session below it. |
maxPushId: i64 |
The client's MAX_PUSH_ID, or -1 until it sends one. It is checked (it may not fall, and bounds CANCEL_PUSH) and otherwise unused, since this side never pushes. |
peer: Http3Settings |
The client's SETTINGS. |
peerControl: i64 |
The ID of the client's control stream, or -1 until its stream type has been read. |
peerDecoder: i64 |
The ID of the client's QPACK decoder stream, or -1 until its stream type has been read. |
peerEncoder: i64 |
The ID of the client's QPACK encoder stream, or -1 until its stream type has been read. |
quic: QuicConnection |
The QUIC connection this one runs on, given to the constructor and kept for its life. |
rejected: i32 |
Counters for a log or a test, each saturating and zeroed by restart. This one: request streams refused because their ID is at or past the one this side's GOAWAY named, and WebTransport streams dropped because their session's is. |
resetByPeer: boolean |
Whether H3_RESET came from the client. |
sectionPool: BufferPool |
Where the buffer a HEADERS payload is read into whole, for the decoder, is borrowed from around one read and decode: the connection's own pool until its server lends it the server's. |
session: i64 |
H3_STREAM's session ID. |
settingIds: i64[] |
The identifiers of the SETTINGS this side sends, in the order sent; fixed by the constructor. |
settingsSeen: boolean |
Whether the client's SETTINGS have arrived. |
state: i32 |
0 while the connection is open; 1 once it failed (H3_ERROR), which only restart undoes. |
stream: i64 |
The last event's stream. |
streamErrors: i32 |
Requests reset for breaking a rule (a stream error, §8): a malformed message, a body that disagrees with content-length, a stream that ends before its HEADERS, a trailer section too large. |
tooLarge: i32 |
Requests whose field section was past maxFieldSectionSize: answered with a 431, or reset when the 431 did not fit. |
webtransport: boolean |
Whether WebTransport is on: webtransportSessions above 0. Fixed by the constructor. |
acceptStream(id: i64): i32 |
Lets a stream H3_STREAM held go: its bytes come as H3_DATA from the next next(), and the program may write it. Answers 0, or H3_CLOSED for a stream that is not one held. |
awaitsRequest(id: i64): boolean |
Whether request stream id has not yet had its field section read: not opened, opened by a later stream's frame (RFC 9000 §3.2), or still waiting for its HEADERS. A WebTransport stream that names it as its session may wait for it. |
clock(now: i64): i64 |
Runs the connection's clock (H3-5): closes the QUIC connection once it has gone idleTimeout without progress while no request is in hand, or a request's head has waited headTimeout, and otherwise answers when to look again. Http3Server calls it on every flush of the slot; a program driving a connection itself calls it after each next and when the time it answered comes. It allocates nothing. The clock starts on the first next after the handshake chose h3, whether or not the client's MAX_STREAMS has let this side's own streams open yet: a connection the program runs another protocol on, and never asks for an event, is left to QUIC's own idle timeout. |
discardRequest(id: i64, code: i64): i32 |
Stops reading request stream id: the client is asked to stop with code and what it still sends is dropped unseen, whether or not this side has finished its response — a refused WebTransport session's stream, after its status. Answers 0, or H3_CLOSED for a stream that is not a request here. |
goaway(): i32 |
Sends GOAWAY (§5.2): the client's requests on streams below the ID it names — every stream the client has opened so far — are processed, and any it opens from there on is refused with H3_REQUEST_REJECTED. A second call never raises the ID, and sends nothing when the ID has not fallen. Answers 0, or H3_AGAIN before this side's control stream is open or while it has no room for the frame. |
isDone(): boolean |
Whether this side sent GOAWAY and every request it took has finished both ways, every byte of each response acknowledged: the carrier may close the connection. |
next(): i32 |
Reads what the QUIC connection has for the program and answers the next event (see the module comment). Call it after every datagram the QUIC connection takes, until it answers H3_NEED_MORE or H3_ERROR. |
openStream(session: i64, bidirectional: boolean): i64 |
Opens a WebTransport stream of this side's for session (draft-02 §4.1, §4.2): unidirectional with the type 0x54, or bidirectional with the signal 0x41, and the session ID, which go before anything written. Answers its ID, H3_AGAIN while the client's MAX_STREAMS allows no more, or H3_CLOSED with WebTransport off or the connection failed. |
refuseStream(id: i64, code: i64): i32 |
Refuses WebTransport stream id with code: its side here is reset, the client's asked to stop, and what it sent read and dropped. Answers 0, or H3_CLOSED for a stream that is not a WebTransport one. |
reset(id: i64, code: i64): i32 |
Resets request stream id both ways with code — H3_REQUEST_CANCELLED, or H3_REQUEST_REJECTED for one the program did not process (§4.1.1). Answers 0 or H3_CLOSED. |
resetStream(id: i64, code: i64): i32 |
Resets this side of WebTransport stream id with code; the client's side goes on. |
respond(id: i64, status: i32, names: u8[][], values: u8[][], endStream: boolean): i32 |
Sends the response head on request stream id: status (200 to 599) and the fields names/values (lowercase names, no pseudo-headers), ending the stream when endStream. Answers 0; H3_CLOSED for a stream that is not an open request; H3_INVALID for a second head, a status out of range or a field httpFieldsCheckOutgoing refuses; H3_TOO_LARGE for a section past the client's SETTINGS_MAX_FIELD_SECTION_SIZE; or H3_AGAIN. |
restart(): void |
Puts the connection back as the constructor left it, for the QUIC connection's next peer (call it after quic.reset): no stream known, QPACK's state and the client's SETTINGS forgotten, and any buffer still borrowed given back. It allocates nothing. |
stopStream(id: i64, code: i64): i32 |
Asks the client to stop its side of WebTransport stream id with code, and drops what it still sends; this side's goes on. Answers 0 or H3_CLOSED. |
writeData(id: i64, buf: u8[], off: i32, len: i32, endStream: boolean): i32 |
Writes up to len bytes of buf from off as the response body of stream id, in DATA frames of at most writeChunk, and ends the stream when endStream and every byte was taken. Answers how many bytes it took — fewer than len only when the send buffer filled, and H3_WRITABLE then names the stream once it has room — or H3_AGAIN when it took none; H3_CLOSED, or H3_INVALID before the head or when endStream would cut short the DATA frame the last call started. A window outside buf panics. |
writeDataWhole(id: i64, buf: u8[], off: i32, len: i32, fin: boolean): i32 |
Writes buf[off .. off + len) as one DATA frame on request stream id, whole or not at all, with the FIN when fin: a capsule (RFC 9297 §3.2) goes this way, so the client never reads half of one. Answers 0; H3_AGAIN while the send buffer lacks room, and H3_WRITABLE then names the stream; or as writeData refuses, and H3_TOO_LARGE for a frame past the stream's buffer. A window outside buf panics. |
writeStream(id: i64, buf: u8[], off: i32, len: i32, fin: boolean): i32 |
Writes up to len bytes of buf from off to WebTransport stream id, as they are, and its FIN when fin and every byte was taken. Answers how many it took — fewer only when the send buffer filled, and H3_WRITABLE then names the stream — or H3_AGAIN when it took none, or H3_CLOSED for a stream with no side here to write, finished, reset, held or stopped. A window outside buf panics. |
writeTrailers(id: i64, names: u8[][], values: u8[][]): i32 |
Writes a trailer section on request stream id after its body, which ends the stream. Answers as respond does; H3_INVALID before the head or inside a DATA frame writeData has not finished. |
Limits
1,024
H3_CONTROL_FRAME_MAX: i32
The largest control-stream frame read whole: SETTINGS, GOAWAY, MAX_PUSH_ID, CANCEL_PUSH.
256
H3_MAX_SESSIONS: i32
The most WebTransport sessions a configuration may advertise.
Constants
-11
H3_AGAIN: i32
A write that can take nothing yet: Linux's EAGAIN, as nish:net spells it.
"h3"
H3_ALPN: string
The ALPN protocol identifier of HTTP/3 (RFC 9114 §3.1).
-32
H3_CLOSED: i32
A write to a stream that is not an open request: Linux's EPIPE.
2
H3_DATA: i32
Request body bytes: stream, data[dataStart .. dataStart + dataLength).
11
H3_DROPPED: i32
A request stream ended before its request reached the program (only with
webtransportSessions on): stream. Nothing is owed the program; a
WebTransport layer lets go of the streams that waited for it as a session.
4
H3_END: i32
The request ended whole: stream.
8
H3_ERROR: i32
The connection failed with errorCode and is closed. Final.
7
H3_GOAWAY: i32
The client sent GOAWAY: lastStreamId, its push ID.
-22
H3_INVALID: i32
A write of fields or a status the program may not send, or out of order: Linux's EINVAL.
0
H3_NEED_MORE: i32
next has nothing more until more datagrams arrive.
0x0178
H3_NO_APPLICATION_PROTOCOL: i64
CRYPTO_ERROR with TLS's no_application_protocol alert (RFC 9001 §4.8): a handshake that did not choose h3.
1
H3_REQUEST: i32
A request's field section: stream, fields.
5
H3_RESET: i32
The stream is gone: stream, errorCode, resetByPeer.
10
H3_STOPPED: i32
The client sent STOP_SENDING for a WebTransport stream this side writes, and QUIC reset it: stream, errorCode.
9
H3_STREAM: i32
A WebTransport stream arrived (only with webtransportSessions on):
stream, and session, the session ID its first bytes named. It is held,
unread, until the program calls acceptStream or refuseStream.
-90
H3_TOO_LARGE: i32
A field section past what the client takes, or past a stream's buffer: Linux's EMSGSIZE.
3
H3_TRAILERS: i32
A trailer section: stream, fields.
6
H3_WRITABLE: i32
A stream whose write was held back can take more: stream.

