nish/net/http2
The server side of an HTTP/2 connection (RFC 9113): the connection preface, SETTINGS and their acknowledgement, the stream state machine of §5.1, flow control on the connection and on every stream with WINDOW_UPDATE, PING, RST_STREAM, GOAWAY with the last stream identifier, header blocks across CONTINUATION frames decoded by nish/net/hpack, and extended CONNECT (RFC 8441).
import {
H2_AGAIN,
H2_CLOSED,
H2_DATA,
H2_ERROR,
H2_GOAWAY,
H2_INVALID,
H2_MAX_FRAGMENTS,
H2_NEED_MORE,
H2_REQUEST,
H2_RESET,
H2_TRAILERS,
H2_WINDOW,
Http2Config,
Http2Connection,
Http2Pools,
Http2Stream,
} from "nish/net/http2";
import { H2_ERROR, H2_NEED_MORE, H2_REQUEST, Http2Config, Http2Connection } from "nish/net/http2";
import { httpFieldBytes } from "nish/net/http-fields";
const names: u8[][] = [httpFieldBytes("content-type")];
const values: u8[][] = [httpFieldBytes("text/plain")];
const body: u8[] = httpFieldBytes("hello");
const conn = new Http2Connection(new Http2Config());
// Hands the connection `received[0 .. n)`, read from the socket, and answers every request.
const serve = (received: u8[], n: i32): void => {
conn.feed(received, 0, n); // answers how much it took; feed the rest after `next`
let event: i32 = conn.next();
while (event !== H2_NEED_MORE && event !== H2_ERROR) {
// H2_DATA: conn.data[conn.dataStart .. conn.dataStart + conn.dataLength), conn.endStream
if (event === H2_REQUEST) {
// conn.stream, conn.fields (method, path, get("accept")), conn.endStream
conn.respond(conn.stream, 200, names, values, false);
conn.writeData(conn.stream, body, 0, toI32(body.length), true);
}
event = conn.next();
}
// while conn.wantsWrite(): send conn.output[conn.outputStart .. conn.outputEnd),
// then conn.consume(sent)
};
Http2Config
The connection's caps, fixed when it is made.
Http2Connection
One HTTP/2 connection, server side.
Http2Pools
The three buffers a connection borrows — its input, its output and the header block it gathers — as one pool each, sized from one Http2Config.
Http2Stream
One stream's slot.
It is sans-IO: bytes in, events and bytes out, and no socket anywhere.
nish/net/http2-tls runs it over TLS with ALPN h2.
Events
next() reads the frames feed handed it and answers the first that means
something to the program:
-
H2_REQUEST(a stream opened with a request's header section;fieldsholds it until the next header block on the connection is read, for any stream, and a program copies what it keeps past that: the next block emptiesfieldsand reuses the arrays it pointed into), -
H2_DATA(some of a request body, a window onto the input buffer that stays valid until the nextfeed), H2_TRAILERS,-
H2_RESET(the stream is gone: the peer reset it, or broke a rule that resets it —errorCodesays which), -
H2_WINDOW(a send window that heldwriteDataback has opened:stream, or 0 for the connection's), H2_GOAWAY(the peer is going away;lastStreamId),-
and
H2_ERROR, final: the connection broke a rule, a GOAWAY witherrorCodeis queued, and every later call answers it again.
H2_NEED_MORE asks for more input, or for the output to drain: a frame is
read only while the output has room for whatever it makes the connection
answer, so a peer that sends PINGs or SETTINGS and never reads the
acknowledgements stops being read rather than growing a queue. Bodies move a
frame at a time and nothing buffers a whole one.
What the connection refuses, as RFC 9113 classes it.
A connection error sends GOAWAY and ends the connection:
- a bad preface or a first frame that is not SETTINGS (PROTOCOL_ERROR, §3.4);
- every refusal of
nish/net/http2-frame; - a frame other than CONTINUATION inside a header block, or a CONTINUATION outside one (§6.10);
- a stream identifier that is even or does not increase (§5.1.1);
- DATA, WINDOW_UPDATE or RST_STREAM on an idle stream, and a PUSH_PROMISE from a client (PROTOCOL_ERROR);
- HEADERS on a closed stream (STREAM_CLOSED);
- a header block HPACK cannot decode (COMPRESSION_ERROR, RFC 7541 §2.3.2);
- DATA past the connection window, or a window pushed past 2^31 − 1 (FLOW_CONTROL_ERROR, §6.9);
- a setting
http2SettingErrorrefuses; -
a header block longer than
maxHeaderBlockor cut into more thanH2_MAX_FRAGMENTSframes, a header block that would make the HPACK table copy past its budget (HPACK_ERR_COPY_BUDGET), and more streams reset thanresetBudgetallows — by the peer, or by the server for a stream error the peer caused (ENHANCE_YOUR_CALM, §10.5).
A stream error resets one stream and the connection lives: a malformed
request — any refusal of nish/net/http-fields, trailers without END_STREAM,
a body that disagrees with content-length (PROTOCOL_ERROR, §8.1.1); DATA or
HEADERS after the peer ended the stream (STREAM_CLOSED, §5.1); DATA past the
stream's window, or its window pushed past 2^31 − 1 (FLOW_CONTROL_ERROR); a
stream past maxStreams (REFUSED_STREAM, §5.1.2); a stream that depends on
itself and a PRIORITY of the wrong length. A request whose header list is
longer than maxHeaderListSize is answered with a 431 and never reaches the
program (§10.5.1).
Caps are start-up numbers, all in Http2Config: the streams open at
once, the windows, the largest frame and header block accepted, the header
list, the output buffer and the reset budget. Every stream slot is allocated
by the constructor; the input, output and header-block buffers are borrowed
from an Http2Pools when first needed and given back, zeroed as far as they
were written, once each is empty or the connection ends, so an idle
connection holds none.
A server shares one Http2Pools among its slots; a connection on its own
makes a private one that holds one buffer of each. Once the pools are warm,
reading DATA, writing DATA and every control frame allocate nothing, and
neither does a header block once the decoder's arrays have grown to the
largest block and header list seen: it decodes into storage the connection
owns, bounded by maxHeaderBlock and maxHeaderListSize whether the stream
is opened, refused or reset (docs/security/http2.md, H2-1).
The server sends no PUSH_PROMISE and no PRIORITY, and reads PRIORITY only to
check it: RFC 9113 §5.3.2 deprecates the scheme. Every field it sends is a
literal without indexing, so its encoder's table stays empty and the peer's
SETTINGS_HEADER_TABLE_SIZE only ever asks it for a size update; a field
httpFieldSensitive names (set-cookie, authorization, …) is a
never-indexed literal, which no intermediary may index either (RFC 7541
§7.1.3).
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 final response carries the date in conn.date, 29
bytes of IMF-fixdate, right after :status, unless the program's fields
hold their own; a 1xx and trailers carry none. A bare connection has no
clock, so date starts empty and nothing is sent; Http2TlsServer fills
it from its HttpDate (RFC 9110 §6.6.1).
Written from RFC 9113 and RFC 8441, not ported from another implementation.
Classes
Http2Config
The connection's caps, fixed when it is made. The defaults are RFC 9113's where it has one; each is advertised in the server's SETTINGS where a setting names it.
class Http2Config
| Member | |
|---|---|
new Http2Config() |
|
connectionWindowSize: i32 |
The connection's receive window, raised from 65,535 by a WINDOW_UPDATE at the start. |
enableConnectProtocol: boolean |
SETTINGS_ENABLE_CONNECT_PROTOCOL (RFC 8441): whether :protocol is accepted. |
headerTableSize: i32 |
SETTINGS_HEADER_TABLE_SIZE, in bytes: the largest HPACK dynamic table the peer's header blocks may make the decoder keep. It is in force once the peer acknowledges the server's SETTINGS; until then the table is 4,096 bytes, RFC 7541's default. A size update past it is a COMPRESSION_ERROR. |
idleTimeout: i32 |
Milliseconds without a byte read or written, counted from lastActive, after which expired answers true and timeOut ends the connection with GOAWAY NO_ERROR, streams open or not. |
initialWindowSize: i32 |
SETTINGS_INITIAL_WINDOW_SIZE: what each stream may send before the server credits it. |
maxFrameSize: i32 |
SETTINGS_MAX_FRAME_SIZE: the largest frame payload read, which sizes the input buffer. |
maxHeaderBlock: i32 |
The largest header block, compressed, across HEADERS and CONTINUATION. |
maxHeaderListSize: i32 |
SETTINGS_MAX_HEADER_LIST_SIZE: past it a request is answered with a 431. |
maxStreams: i32 |
SETTINGS_MAX_CONCURRENT_STREAMS, and the stream slots the connection allocates. |
outputSize: i32 |
The output buffer, in bytes. |
resetBudget: i32 |
How many streams may be reset — by the peer, or by the server for a stream error the peer caused — net of the ones the server finishes. |
settingsTimeout: i32 |
Milliseconds the peer has, from begin, to acknowledge the server's SETTINGS: past them expired answers true and timeOut ends the connection with SETTINGS_TIMEOUT (RFC 9113 §6.5.3). |
Http2Connection
One HTTP/2 connection, server side. The fields after the buffers are the last event's; the module comment says which event sets which.
class Http2Connection
| Member | |
|---|---|
new Http2Connection(config: Http2Config) |
A connection under config, owing its SETTINGS — and the WINDOW_UPDATE that raises the connection's window, when connectionWindowSize asks for one — since a server's preface is its SETTINGS (§3.4): the first wantsWrite, next or response writes them into output. It holds no buffer until then, so output is empty after the constructor and after restart: a caller that reads output itself calls wantsWrite first. A cap outside what RFC 9113 allows panics. |
active: i32 |
Streams with a slot. |
data: u8[] |
H2_DATA's bytes: the input buffer, valid until the next feed. |
dataLength: i32 |
How many bytes of data, from dataStart, H2_DATA hands the program; 0 for an empty DATA. |
dataStart: i32 |
H2_DATA's window onto data. |
date: u8[] |
The date every final 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; Http2TlsServer points it at its HttpDate's bytes, which that rewrites in place once a second. |
decoder: HpackDecoder |
The HPACK decoder for the peer's header blocks; restart empties its table. |
encoder: HpackEncoder |
The HPACK encoder for responses; every field is a literal without indexing, so its table stays empty. |
endStream: boolean |
Whether the last H2_REQUEST, H2_DATA or H2_TRAILERS ended its stream. |
errorCode: i64 |
H2_RESET's, H2_GOAWAY's and H2_ERROR's code. |
fields: HttpFields |
The last request's or trailers' fields, valid until the next header block on the connection, for any stream: that block empties them and reuses their arrays, so a program copies what it keeps (docs/security/http2.md, H2-1). |
goawaySent: boolean |
Whether a GOAWAY from the server is in the output: by goaway, sendGoaway or a connection error. |
input: u8[] |
Bytes fed and not read yet are input[inputStart .. inputEnd). |
inputEnd: i32 |
Where the bytes fed and not read yet end in input. |
inputStart: i32 |
Where the bytes fed and not read yet start in input. |
inputUsed: i32 |
How far into input the connection has written since it borrowed it: what giving it back zeroes. |
lastActive: i64 |
When the carrier last moved a byte for the connection, in monotonicNanos; begin starts it. |
lastPeerStream: i32 |
The highest stream identifier the peer has opened. |
lastStreamId: i32 |
H2_GOAWAY's last stream identifier. |
output: u8[] |
Bytes to send are output[outputStart .. outputEnd). |
outputEnd: i32 |
Where the bytes to send end in output. |
outputStart: i32 |
Where the bytes to send start in output; consume moves it. |
peerMaxFrameSize: i32 |
The peer's SETTINGS_MAX_FRAME_SIZE. |
pools: Http2Pools | null |
Where the connection borrows its input, its output and the header block it gathers: the pools Http2TlsServer shares among its slots, or, while this is null when a buffer is first needed, pools of one of each the connection makes itself. While the connection holds no input or no output buffer, input or output is an empty array. |
resetByPeer: boolean |
Whether H2_RESET came from the peer's RST_STREAM rather than a rule its stream broke. |
settingsAcked: boolean |
Whether the peer has acknowledged the server's SETTINGS. |
settingsSince: i64 |
When the server's SETTINGS began to wait for their acknowledgement, in monotonicNanos; begin sets it. |
stream: i32 |
The last event's stream. |
begin(now: i64): void |
Starts both of the connection's clocks at now: the deadline for the peer's acknowledgement of the server's SETTINGS, and the idle one. The connection reads no clock itself; a carrier calls this when it takes the peer, stamps lastActive whenever bytes move, and asks expired. |
consume(n: i32): void |
Marks the first n bytes of the output sent; once all of it is, the output goes back to its pool. |
drop(): void |
Ends the connection where it stands, for a carrier that closes it: every buffer is given back, zeroed, with what was unread or unsent, and the connection answers H2_ERROR until restart. errorCode is left as it was. |
expired(now: i64): boolean |
Whether the connection has outlived a timeout at now: the peer has not acknowledged the server's SETTINGS within settingsTimeout of begin, or nothing has moved for longer than idleTimeout. |
expiresNoSooner(now: i64): i64 |
The soonest expired can answer true at or after now, however the connection moves from here: lastActive only grows, and the SETTINGS deadline goes once they are acknowledged. |
feed(buf: u8[], off: i32, len: i32): i32 |
Takes as much of buf[off, off + len) as the input buffer has room for, and answers how much; the rest is the caller's to feed again once next has read what is there. Moves the unread bytes to the front of the buffer, which ends the last H2_DATA's window. Once the connection has failed it takes everything and keeps nothing. |
find(id: i32): Http2Stream | null |
The slot holding stream id, or null. |
goaway(): i32 |
Starts a graceful close (§6.8): GOAWAY with NO_ERROR naming the last stream the peer opened. Streams already open finish; newer ones are ignored; isDone once the last has closed and everything is sent. Answers 0, also when a GOAWAY was already sent or the connection has failed, or H2_AGAIN when the output has no room for the frame yet. |
isDone(): boolean |
Whether the connection is over: everything is sent, and it failed, or no stream is left after a GOAWAY went either way or after the peer's byte stream ended (endInput) with nothing of it left unread. |
next(): i32 |
Reads frames until one is an event for the program, and answers it. |
reset(id: i32, code: i32): i32 |
Resets stream id with code (§6.4), from the program's side: CANCEL, say. Answers 0, H2_AGAIN when the output has no room for the frame yet (the stream stays open), or H2_CLOSED. |
respond(id: i32, status: i32, names: u8[][], values: u8[][], endStream: boolean): i32 |
Answers stream id with status and the fields names[k]: values[k], lowercase and none of them connection-specific; END_STREAM when endStream. A 1xx status but 101 may come before the final one and may not end the stream. The block is encoded into the output before it answers. |
rest(): void |
Gives back every buffer the connection holds and does not need: the input once all of it is read, which ends the last H2_DATA's window; the output once all of it is sent; the header block while none is open. A carrier calls it once the program is done with the last event, so a connection waiting on its peer holds no buffer. |
restart(): void |
Puts the connection back as the constructor left it, for the next peer: every stream closed, both HPACK tables empty, every buffer given back, and the server's SETTINGS owed again. It allocates nothing, which is what lets a carrier reuse one connection per slot (WP34 N9). |
sendGoaway(code: i32): boolean |
Writes GOAWAY with code, naming the last stream the peer had opened when the server's first GOAWAY went: no later one may name a higher stream (§6.8). Answers whether it fit. |
timeOut(now: i64): void |
Ends a connection expired at now: the connection fails with GOAWAY SETTINGS_TIMEOUT when the peer never acknowledged the server's SETTINGS in time (§6.5.3), and with GOAWAY NO_ERROR when it was idle. The carrier sends what it can of the output, then closes. |
wantsWrite(): boolean |
Whether the output holds bytes to send; the SETTINGS a fresh connection owes are written first. |
writeData(id: i32, buf: u8[], off: i32, len: i32, endStream: boolean): i32 |
Sends as much of buf[off, off + len) on stream id as the stream's window, the connection's window, and the output allow, in frames no larger than the peer's SETTINGS_MAX_FRAME_SIZE, and answers how much. END_STREAM goes on the last frame when endStream and every byte was taken; len 0 with endStream sends an empty DATA that ends the stream. Answers H2_AGAIN when nothing could be taken — after H2_WINDOW for the stream or the connection, or once the output has drained, it may be tried again — and H2_CLOSED for a stream with no final response head or that has ended. |
writeTrailers(id: i32, names: u8[][], values: u8[][]): i32 |
Ends stream id with a trailer section, after its response head (§8.1). The block carries no :status and no date, and is encoded into the output before it answers. |
Http2Pools
The three buffers a connection borrows — its input, its output and the
header block it gathers — as one pool each, sized from one Http2Config.
Http2TlsServer owns one with a ceiling of its slot count and shares it
with every slot; a bare connection makes its own, of ceiling 1, the first
time it needs a buffer.
class Http2Pools
| Member | |
|---|---|
new Http2Pools(name: string, config: Http2Config, ceiling: i32) |
Pools of at most ceiling buffers each, for connections under config. Allocates no buffer. |
block: BufferPool |
maxHeaderBlock. |
input: BufferPool |
maxFrameSize and a frame header: the largest frame next reads. |
output: BufferPool |
outputSize. |
lent(): i32 |
How many buffers of the three kinds are lent now. |
made(): i32 |
How many buffers of the three kinds have ever been made. |
Http2Stream
One stream's slot. id is 0 while the slot is free.
class Http2Stream
| Member | |
|---|---|
new Http2Stream() |
|
contentLength: i64 |
The request's content-length, or -1. |
id: i32 |
The stream's identifier, odd since a client opened it, or 0 while the slot is free. |
localEnded: boolean |
The server sent END_STREAM: half-closed (local). |
received: i64 |
The body bytes received. |
recvWindow: i64 |
What the peer may still send on it. |
remoteEnded: boolean |
The peer sent END_STREAM: half-closed (remote). |
responded: boolean |
A final (non-1xx) response head was sent. |
sendWindow: i64 |
What the server may still send on the stream. |
Limits
64
H2_MAX_FRAGMENTS: i32
How many frames one header block may be cut into.
Constants
-11
H2_AGAIN: i32
What writeData answers when nothing can be sent yet: Linux's EAGAIN, as nish:net spells it.
-32
H2_CLOSED: i32
What a write answers for a stream it may not write to: Linux's EPIPE.
2
H2_DATA: i32
Request body bytes: stream, data[dataStart .. dataStart + dataLength), endStream.
7
H2_ERROR: i32
The connection failed with errorCode and a GOAWAY is queued. Final.
6
H2_GOAWAY: i32
The peer sent GOAWAY: lastStreamId, errorCode.
-22
H2_INVALID: i32
What a write answers for fields or a status it may not send: Linux's EINVAL.
0
H2_NEED_MORE: i32
next needs more input, or the output to drain.
1
H2_REQUEST: i32
A stream opened with a request: stream, fields, endStream.
4
H2_RESET: i32
The stream is gone, reset by the peer or for a rule it broke: stream, errorCode, resetByPeer.
3
H2_TRAILERS: i32
A trailer section, which ends the request: stream, fields.
5
H2_WINDOW: i32
A send window that held writeData back has opened: stream, 0 for the connection's.

