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)
};

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; fields holds 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 empties fields and reuses the arrays it pointed into),
  • H2_DATA (some of a request body, a window onto the input buffer that stays valid until the next feed),
  • H2_TRAILERS,
  • H2_RESET (the stream is gone: the peer reset it, or broke a rule that resets it — errorCode says which),
  • H2_WINDOW (a send window that held writeData back 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 with errorCode is 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 http2SettingError refuses;
  • a header block longer than maxHeaderBlock or cut into more than H2_MAX_FRAGMENTS frames, a header block that would make the HPACK table copy past its budget (HPACK_ERR_COPY_BUDGET), and more streams reset than resetBudget allows — 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.