nish/net/http3-frame

The frames and stream types of HTTP/3 (RFC 9114 §6.2, §7): frame headers, SETTINGS, the one-identifier frames (GOAWAY, MAX_PUSH_ID, CANCEL_PUSH), and which types are HTTP/2's reserved ones or unknown. Sans-IO: every reader takes a byte window (buf, off, len) and reads it in place, and every writer writes into the caller's buffer at an offset, before an end, and answers the offset past what it wrote, or -1 when it does not fit (the frame writers may have written their header by then). Nothing here allocates.

import {
  H3_CLOSED_CRITICAL_STREAM,
  H3_CONNECT_ERROR,
  H3_DATAGRAM_ERROR,
  H3_EXCESSIVE_LOAD,
  H3_FRAME_CANCEL_PUSH,
  H3_FRAME_DATA,
  H3_FRAME_ERROR,
  H3_FRAME_GOAWAY,
  H3_FRAME_HEADERS,
  H3_FRAME_HEADER_MAX,
  H3_FRAME_MAX_PUSH_ID,
  H3_FRAME_PUSH_PROMISE,
  H3_FRAME_SETTINGS,
  H3_FRAME_UNEXPECTED,
  H3_FRAME_WEBTRANSPORT_STREAM,
  H3_GENERAL_PROTOCOL_ERROR,
  H3_ID_ERROR,
  H3_INTERNAL_ERROR,
  H3_MESSAGE_ERROR,
  H3_MISSING_SETTINGS,
  H3_NO_ERROR,
  H3_REQUEST_CANCELLED,
  H3_REQUEST_INCOMPLETE,
  H3_REQUEST_REJECTED,
  H3_SETTINGS_ENABLE_CONNECT_PROTOCOL,
  H3_SETTINGS_ENABLE_WEBTRANSPORT,
  H3_SETTINGS_ERROR,
  H3_SETTINGS_H3_DATAGRAM,
  H3_SETTINGS_KEEP,
  H3_SETTINGS_MAX_FIELD_SECTION_SIZE,
  H3_SETTINGS_OK,
  H3_SETTINGS_QPACK_BLOCKED_STREAMS,
  H3_SETTINGS_QPACK_MAX_TABLE_CAPACITY,
  H3_SETTINGS_WEBTRANSPORT_MAX_SESSIONS,
  H3_STREAM_CONTROL,
  H3_STREAM_CREATION_ERROR,
  H3_STREAM_PUSH,
  H3_STREAM_QPACK_DECODER,
  H3_STREAM_QPACK_ENCODER,
  H3_STREAM_WEBTRANSPORT,
  H3_VERSION_FALLBACK,
  H3_WT_SESSION_GONE,
  Http3FrameHeader,
  Http3Settings,
  h3CheckWindow,
  h3Count,
  h3FrameHeaderSize,
  h3Greased,
  h3PutFrameHeader,
  h3PutIdFrame,
  h3PutSettings,
  h3PutVarint,
  h3ReadFrameHeader,
  h3ReadIdPayload,
  h3ReadSettings,
  h3ReadVarint,
  h3ReservedHttp2Frame,
  h3VarintLength,
} from "nish/net/http3-frame";
import {
  Http3FrameHeader, h3ReadFrameHeader, h3PutFrameHeader, H3_FRAME_DATA, H3_FRAME_HEADER_MAX,
} from "nish/net/http3-frame";

const buf: u8[] = [0x00, 0x03, 0x61, 0x62, 0x63];         // bytes a stream delivered: DATA, 3 bytes
const h = new Http3FrameHeader();
const size: i32 = h3ReadFrameHeader(h, buf, 0, toI32(buf.length));   // 2; 0 if the header is cut off
// h.type, h.length; the payload is the next h.length bytes of the stream
const out: u8[] = new Array<u8>(H3_FRAME_HEADER_MAX);
const n: i32 = 3;
const at: i32 = h3PutFrameHeader(out, 0, toI32(out.length), H3_FRAME_DATA, toI64(n));   // 2

Frames (§7.1) are a type and a length, each a QUIC variable-length integer, and then that many bytes of payload. On a QUIC stream a frame may arrive in any number of pieces, so a header is read only once both of its integers are in the window (h3ReadFrameHeader answers 0 until then) and a payload is the caller's to count down. The varints are nish/net/quic-packet's, which QUIC and HTTP/3 share.

Types

DATA, HEADERS, CANCEL_PUSH, SETTINGS, PUSH_PROMISE, GOAWAY and MAX_PUSH_ID are the seven RFC 9114 defines. The types HTTP/2 used with no HTTP/3 counterpart (0x02 PRIORITY, 0x06 PING, 0x08 WINDOW_UPDATE, 0x09 CONTINUATION) are reserved, and receiving one is H3_FRAME_UNEXPECTED (§7.2.8): h3ReservedHttp2Frame names them. Every other type is unknown, the reserved 0x1f * N + 0x21 types that exercise that rule included (§7.2.8, §9), and its frame is skipped whole wherever it arrives.

SETTINGS

SETTINGS (§7.2.4). h3ReadSettings reads a whole payload into an Http3Settings: the three identifiers this endpoint understands, and the first H3_SETTINGS_KEEP it does not, kept rather than dropped so that an extension can read them. The four that extended CONNECT and WebTransport read (RFC 9220's, RFC 9297's and the two of the WebTransport drafts) are also recorded in fields of their own, refused when repeated, so a peer cannot push them out of reach behind eight others.

A payload that ends inside a pair is H3_FRAME_ERROR (§7.1); an identifier HTTP/2 defined with no HTTP/3 counterpart (0x00, 0x02 to 0x05), or one that appears twice, is H3_SETTINGS_ERROR (§7.2.4, §7.2.4.1). A repeat among the unknown ones is caught while they are kept, and past H3_SETTINGS_KEEP they are counted, not compared, so a peer cannot make the read cost more than a fixed number of compares per setting.

Stream types

Stream types (§6.2): control 0x00, push 0x01, RFC 9204's QPACK encoder 0x02 and decoder 0x03, and WebTransport's 0x54, whose bidirectional counterpart is the signal 0x41 where a request's first frame would be. Each is one varint at the start of a unidirectional stream, written with h3PutVarint.

Error codes

Error codes (§8.1) are the H3_* values from 0x0100; QPACK's three (0x0200 to 0x0202) are nish/net/qpack's.

Written from RFC 9114 §6.2, §7, §8.1 and §11.2, RFC 9220 §5, RFC 9297 §2.1.1 and §5.2 and draft-ietf-webtrans-http3-02, not ported from another implementation. Private names carry the h3Frame prefix, since a std/ module's private functions share the importing program's flat symbol namespace (docs/wp26-stdlib.md §3e).

Functions

h3CheckWindow

Panics unless [off, off + len) lies inside buf: a window outside its buffer is the program's mistake.

const h3CheckWindow: (
  what: string,
  buf: u8[],
  off: i32,
  len: i32,
) => void
whatstringrequired

The caller's name, which starts the panic message.

bufu8[]required

The buffer the window is meant to lie in.

offi32required

The window's first byte offset; negative panics.

leni32required

The window's length in bytes; negative panics, and so does an end past buf.length.

h3Count

count plus one, saturating at 2^31 - 1: every counter a peer drives.

const h3Count: (count: i32) => i32
counti32required

The counter's current value.

returnsi32

count + 1, or count unchanged once it is 2^31 - 1.

h3FrameHeaderSize

How many bytes a frame header of type and length takes.

const h3FrameHeaderSize: (type: i64, length: i64) => i32
typei64required

The frame type.

lengthi64required

The payload's length in bytes.

returnsi32

2 to 16 bytes, or 0 when type or length is negative or above 2^62 - 1.

h3Greased

Whether value is one of the 0x1f * N + 0x21 values reserved to exercise the rule that unknowns are ignored (§7.2.8, §7.2.4.1, §6.2.3).

const h3Greased: (value: i64) => boolean
valuei64required

A frame type, setting identifier or stream type.

returnsboolean

True when value is 0x21 or above and 0x21 more than a multiple of 0x1f; false otherwise, negatives included.

h3PutFrameHeader

Writes a frame header of type and length at buf[at], before end.

const h3PutFrameHeader: (
  buf: u8[],
  at: i32,
  end: i32,
  type: i64,
  length: i64,
) => i32
bufu8[]required

The buffer to write into.

ati32required

The byte offset to write the header at.

endi32required

The offset the header must end at or before; at most buf.length.

typei64required

The frame type, 0 to 2^62 - 1, written as given.

lengthi64required

The payload's length in bytes, 0 to 2^62 - 1; the payload is the caller's to write.

returnsi32

The offset past the 2 to 16 bytes written, or -1 with nothing written when type or length is no varint, [at, end) is not a window inside buf, or the header does not fit before end.

h3PutIdFrame

Writes a frame whose payload is one identifier — GOAWAY, MAX_PUSH_ID or CANCEL_PUSH (§7.2.6, §7.2.7, §7.2.3) — at buf[at], before end; answers the offset past it, or -1.

const h3PutIdFrame: (
  buf: u8[],
  at: i32,
  end: i32,
  type: i64,
  id: i64,
) => i32
bufu8[]required

The buffer to write into.

ati32required

The byte offset to write the frame at.

endi32required

The offset the frame must end at or before; at most buf.length.

typei64required

The frame type, written as given: H3_FRAME_GOAWAY, H3_FRAME_MAX_PUSH_ID or H3_FRAME_CANCEL_PUSH, which this does not check.

idi64required

The stream ID or push ID the payload carries, 0 to 2^62 - 1.

returnsi32

The offset past the frame written, or -1 when type or id is no varint, [at, end) is not a window inside buf, or the frame does not fit before end; when only the identifier does not fit, the header may already be in buf[at ..].

h3PutSettings

Writes a whole SETTINGS frame of the pairs ids[k], values[k] at buf[at], before end, and answers the offset past it, or -1 when it does not fit, the lists differ in length, or an identifier or a value is no varint. It writes what it is given: refusing a reserved identifier is the reader's job.

const h3PutSettings: (
  buf: u8[],
  at: i32,
  end: i32,
  ids: i64[],
  values: i64[],
) => i32
bufu8[]required

The buffer to write into.

ati32required

The byte offset to write the frame at.

endi32required

The offset the frame must end at or before; at most buf.length.

idsi64[]required

The setting identifiers, in the order they are written; read, not kept.

valuesi64[]required

The values, one per identifier at the same index; read, not kept.

returnsi32

The offset past the frame written, header and payload, or -1 when the lists differ in length, an identifier or a value is negative or above 2^62 - 1, [at, end) is not a window inside buf, or the frame does not fit before end. Nothing is written for the first three; when only the payload does not fit, the header may already be in buf[at ..].

h3PutVarint

Writes value as a varint in the fewest bytes at buf[at], before end, and answers the offset past it, or -1 when it does not fit or no varint holds the value.

const h3PutVarint: (
  buf: u8[],
  at: i32,
  end: i32,
  value: i64,
) => i32
bufu8[]required

The buffer to write into.

ati32required

The byte offset to write the first byte at.

endi32required

The offset the integer must end at or before; at most buf.length.

valuei64required

The value to encode, 0 to 2^62 - 1.

returnsi32

The offset past the 1, 2, 4 or 8 bytes written, or -1 with nothing written when value is negative or above 2^62 - 1, [at, end) is not a window inside buf, or the integer does not fit before end.

h3ReadFrameHeader

Reads a frame header from buf[off, off + len) into h and answers how many bytes it took, or 0 when the window ends inside it (and h is not touched). Any type and any length up to 2^62 - 1 is a header; whether the type is allowed where it arrived is the stream's question.

const h3ReadFrameHeader: (
  h: Http3FrameHeader,
  buf: u8[],
  off: i32,
  len: i32,
) => i32
hHttp3FrameHeaderrequired

The header to fill; set only when the answer is above 0.

bufu8[]required

The bytes the stream delivered.

offi32required

The window's first byte offset, where the header starts.

leni32required

The window's length in bytes; the window must lie inside buf, or this panics.

returnsi32

The header's size, 2 to 16 bytes, or 0 when the window ends before both varints are whole.

h3ReadIdPayload

The identifier a GOAWAY, MAX_PUSH_ID or CANCEL_PUSH payload buf[off, off + len) carries, or -1 when the payload is not exactly one varint, which is H3_FRAME_ERROR (§7.1).

const h3ReadIdPayload: (
  buf: u8[],
  off: i32,
  len: i32,
) => i64
bufu8[]required

The bytes holding the payload.

offi32required

The payload's first byte offset.

leni32required

The payload's length in bytes, the frame header's length; the window must lie inside buf, or this panics.

returnsi64

The identifier, 0 to 2^62 - 1, or -1 when the payload is empty, ends inside the varint, or has bytes after it.

h3ReadSettings

Reads a whole SETTINGS payload, buf[off, off + len), into s (which it resets first). Answers H3_SETTINGS_OK, H3_FRAME_ERROR for a payload that ends inside a pair (§7.1), or H3_SETTINGS_ERROR for a reserved or repeated identifier (§7.2.4).

const h3ReadSettings: (
  s: Http3Settings,
  buf: u8[],
  off: i32,
  len: i32,
) => i64
sHttp3Settingsrequired

The settings to fill; reset first, and after an error answer its contents are not meaningful.

bufu8[]required

The bytes holding the payload.

offi32required

The payload's first byte offset.

leni32required

The payload's length in bytes, the frame header's length; the window must lie inside buf, or this panics. An empty payload is read as the defaults.

returnsi64

H3_SETTINGS_OK when every pair was read; H3_FRAME_ERROR when the payload ends inside an identifier or a value; H3_SETTINGS_ERROR for an identifier HTTP/2 defined (0x00, 0x02 to 0x05) or a repeat of an identifier understood, of an extension one, or of a kept unknown one. It stops at the first error.

h3ReadVarint

The varint at buf[at], read only from buf[at .. end), or -1 when it does not fit there. Advance past it by h3VarintLength(buf, at).

const h3ReadVarint: (buf: u8[], at: i32, end: i32) => i64
bufu8[]required

The bytes holding the integer.

ati32required

The byte offset of the integer's first byte.

endi32required

The offset the integer must end at or before; past buf.length reads nothing.

returnsi64

The value, 0 to 2^62 - 1, or -1 when at is outside buf, end is past buf.length, or the integer's bytes run past end.

h3ReservedHttp2Frame

Whether type is one HTTP/2 used that HTTP/3 reserves, whose receipt is H3_FRAME_UNEXPECTED (§7.2.8).

const h3ReservedHttp2Frame: (type: i64) => boolean
typei64required

A frame type as read.

returnsboolean

True for 0x02, 0x06, 0x08 and 0x09; false for every other type.

h3VarintLength

The length of the varint whose first byte is buf[at].

const h3VarintLength: (buf: u8[], at: i32) => i32
bufu8[]required

The bytes holding the integer.

ati32required

The byte offset of the integer's first byte.

returnsi32

1, 2, 4 or 8 bytes, read from the first byte's two-bit prefix alone (the rest need not be in buf), or 0 when at is outside buf.

Classes

Http3FrameHeader

One frame header as h3ReadFrameHeader read it: the type and the payload's length.

class Http3FrameHeader
Member
new Http3FrameHeader()
length: i64 The payload's length in bytes, 0 to 2^62 - 1, set with type; the payload itself is not read here.
type: i64 The frame type, 0 to 2^62 - 1, any value: set by each h3ReadFrameHeader that answers above 0.

Http3Settings

The peer's SETTINGS as h3ReadSettings read them. The three it understands hold RFC 9114's and RFC 9204's defaults until a frame sets them: maxFieldSectionSize is -1, unlimited (§7.2.4.1). The first H3_SETTINGS_KEEP identifiers it does not understand are kept with their values, in order, and the rest counted in dropped.

class Http3Settings
Member
new Http3Settings() Settings at their defaults, with room for H3_SETTINGS_KEEP unknown identifiers made once.
blockedStreams: i64 SETTINGS_QPACK_BLOCKED_STREAMS, a count of streams, as the peer sent it, unchecked; 0 by default.
dropped: i32 How many more there were, saturating at 2^31 - 1.
enableConnectProtocol: i64 The extension settings WebTransport reads, -1 when the frame did not carry them: SETTINGS_ENABLE_CONNECT_PROTOCOL, SETTINGS_H3_DATAGRAM, SETTINGS_ENABLE_WEBTRANSPORT and SETTINGS_WEBTRANSPORT_MAX_SESSIONS. Each is recorded here, where a peer cannot push it out of reach, and also kept as an unknown identifier while there is room, so unknown still finds it.
enableWebtransport: i64 SETTINGS_ENABLE_WEBTRANSPORT's value as the peer sent it, or -1 when the frame did not carry it.
h3Datagram: i64 SETTINGS_H3_DATAGRAM's value as the peer sent it, or -1 when the frame did not carry it.
maxFieldSectionSize: i64 SETTINGS_MAX_FIELD_SECTION_SIZE as the peer sent it: the largest field section it takes, as §4.2.2 counts it; -1, unlimited, by default.
maxTableCapacity: i64 SETTINGS_QPACK_MAX_TABLE_CAPACITY in bytes as the peer sent it, unchecked; 0 by default.
seen: i32 The bits of the identifiers understood that the frame set.
unknownCount: i32 How many unknown identifiers are kept.
webtransportMaxSessions: i64 SETTINGS_WEBTRANSPORT_MAX_SESSIONS's value as the peer sent it, or -1 when the frame lacked it.
unknown(id: i64): i64 The value of an identifier this module does not understand.

Limits

16

H3_FRAME_HEADER_MAX: i32

The largest frame header: two eight-byte varints.

8

H3_SETTINGS_KEEP: i32

How many identifiers Http3Settings keeps that it does not understand.

Constants

0x0104

H3_CLOSED_CRITICAL_STREAM: i64

H3_CLOSED_CRITICAL_STREAM (0x0104): a stream the connection needs was closed or reset (§8.1).

0x010f

H3_CONNECT_ERROR: i64

H3_CONNECT_ERROR (0x010f): a CONNECT request's TCP connection was reset or closed abnormally (§8.1).

0x33

H3_DATAGRAM_ERROR: i64

H3_DATAGRAM_ERROR (RFC 9297 §5.2): an HTTP datagram or a capsule that does not parse.

0x0107

H3_EXCESSIVE_LOAD: i64

H3_EXCESSIVE_LOAD (0x0107): the peer behaves in a way that may cause excessive load (§8.1).

0x03

H3_FRAME_CANCEL_PUSH: i64

CANCEL_PUSH (§7.2.3): one push ID.

0x00

H3_FRAME_DATA: i64

DATA (§7.2.1): a piece of a message's content.

0x0106

H3_FRAME_ERROR: i64

H3_FRAME_ERROR (0x0106): a frame whose layout or size is wrong (§8.1).

0x07

H3_FRAME_GOAWAY: i64

GOAWAY (§7.2.6): a stream ID from a server, a push ID from a client.

0x01

H3_FRAME_HEADERS: i64

HEADERS (§7.2.2): a QPACK-encoded field section.

0x0d

H3_FRAME_MAX_PUSH_ID: i64

MAX_PUSH_ID (§7.2.7): the largest push ID a client lets a server use.

0x05

H3_FRAME_PUSH_PROMISE: i64

PUSH_PROMISE (§7.2.5): a push ID and a request's field section; only a server sends it.

0x04

H3_FRAME_SETTINGS: i64

SETTINGS (§7.2.4): identifier and value pairs, first on a control stream.

0x0105

H3_FRAME_UNEXPECTED: i64

H3_FRAME_UNEXPECTED (0x0105): a frame not allowed in the current state or on its stream (§8.1).

0x41

H3_FRAME_WEBTRANSPORT_STREAM: i64

The signal that opens a WebTransport bidirectional stream (draft-02 §4.2): where a request's first frame type would be, then the session ID, then the session's bytes. It is not a frame: no length follows it.

0x0101

H3_GENERAL_PROTOCOL_ERROR: i64

H3_GENERAL_PROTOCOL_ERROR (0x0101): a protocol violation no more specific code names (§8.1).

0x0108

H3_ID_ERROR: i64

H3_ID_ERROR (0x0108): a stream ID or push ID used wrongly, such as past a limit or reused (§8.1).

0x0102

H3_INTERNAL_ERROR: i64

H3_INTERNAL_ERROR (0x0102): an internal error in the HTTP stack (§8.1).

0x010e

H3_MESSAGE_ERROR: i64

H3_MESSAGE_ERROR (0x010e): a malformed HTTP message (§8.1, §4.1.2).

0x010a

H3_MISSING_SETTINGS: i64

H3_MISSING_SETTINGS (0x010a): the control stream did not start with SETTINGS (§8.1, §6.2.1).

0x0100

H3_NO_ERROR: i64

H3_NO_ERROR (0x0100): no error, for closing a connection or stream with nothing to signal (§8.1).

0x010c

H3_REQUEST_CANCELLED: i64

H3_REQUEST_CANCELLED (0x010c): a request or its response is cancelled (§8.1).

0x010d

H3_REQUEST_INCOMPLETE: i64

H3_REQUEST_INCOMPLETE (0x010d): the client's stream ended without a whole request (§8.1).

0x010b

H3_REQUEST_REJECTED: i64

H3_REQUEST_REJECTED (0x010b): the server refused a request before any processing of it (§8.1).

0x08

H3_SETTINGS_ENABLE_CONNECT_PROTOCOL: i64

SETTINGS_ENABLE_CONNECT_PROTOCOL (RFC 9220 §5, RFC 8441 §3): 1 lets the peer send an extended CONNECT.

0x2b603742

H3_SETTINGS_ENABLE_WEBTRANSPORT: i64

SETTINGS_ENABLE_WEBTRANSPORT of draft-ietf-webtrans-http3-02 §3.1, which Chrome and wtransport 0.7 send.

0x0109

H3_SETTINGS_ERROR: i64

H3_SETTINGS_ERROR (0x0109): an error in a SETTINGS payload (§8.1, §7.2.4).

0x33

H3_SETTINGS_H3_DATAGRAM: i64

SETTINGS_H3_DATAGRAM (RFC 9297 §2.1.1): 1 lets the peer send HTTP datagrams.

0x06

H3_SETTINGS_MAX_FIELD_SECTION_SIZE: i64

SETTINGS_MAX_FIELD_SECTION_SIZE: the largest field section the sender takes, as §4.2.2 counts it.

0

H3_SETTINGS_OK: i64

What h3ReadSettings answers for a payload it read whole.

QPACK_​SETTINGS_​BLOCKED_​STREAMS

H3_SETTINGS_QPACK_BLOCKED_STREAMS: i64

SETTINGS_QPACK_BLOCKED_STREAMS.

QPACK_​SETTINGS_​MAX_​TABLE_​CAPACITY

H3_SETTINGS_QPACK_MAX_TABLE_CAPACITY: i64

SETTINGS_QPACK_MAX_TABLE_CAPACITY.

0xc671706a

H3_SETTINGS_WEBTRANSPORT_MAX_SESSIONS: i64

SETTINGS_WEBTRANSPORT_MAX_SESSIONS of draft-ietf-webtrans-http3-07 §3.1, which wtransport 0.7 sends beside the draft-02 one.

0x00

H3_STREAM_CONTROL: i64

The control stream: SETTINGS first, then the connection's control frames.

0x0103

H3_STREAM_CREATION_ERROR: i64

H3_STREAM_CREATION_ERROR (0x0103): the peer created a stream this endpoint will not accept (§8.1).

0x01

H3_STREAM_PUSH: i64

A push stream, which only a server opens.

QPACK_​DECODER_​STREAM

H3_STREAM_QPACK_DECODER: i64

QPACK's decoder stream.

QPACK_​ENCODER_​STREAM

H3_STREAM_QPACK_ENCODER: i64

QPACK's encoder stream.

0x54

H3_STREAM_WEBTRANSPORT: i64

A WebTransport unidirectional stream (draft-ietf-webtrans-http3-02 §4.1): the type, then the session ID, then the session's bytes.

0x0110

H3_VERSION_FALLBACK: i64

H3_VERSION_FALLBACK (0x0110): the request cannot be served over HTTP/3; retry it over HTTP/1.1 (§8.1).

0x170d7b68

H3_WT_SESSION_GONE: i64

WT_SESSION_GONE (draft-ietf-webtrans-http3-02 §4.5): a WebTransport stream of a session that is gone, or can never come.