nish/net/qpack

QPACK, the field compression of HTTP/3, as RFC 9204 defines it with a dynamic table of capacity 0: the Appendix A static table, the §4.1.1 prefixed integer up to 62 bits, the §4.1.2 string literal with an N-bit prefix, the §4.5 field-line representations under a Required Insert Count of 0, and what the encoder and decoder streams of §4.2 may carry when neither side ever inserts.

import {
  QPACK_DECODER_STREAM,
  QPACK_DECODER_STREAM_ERROR,
  QPACK_DECOMPRESSION_FAILED,
  QPACK_ENCODER_STREAM,
  QPACK_ENCODER_STREAM_ERROR,
  QPACK_FIELD_OVERHEAD,
  QPACK_OK,
  QPACK_REASON_ACKNOWLEDGMENT,
  QPACK_REASON_BASE,
  QPACK_REASON_CAPACITY,
  QPACK_REASON_DUPLICATE,
  QPACK_REASON_DYNAMIC,
  QPACK_REASON_HUFFMAN,
  QPACK_REASON_INCREMENT,
  QPACK_REASON_INSERT,
  QPACK_REASON_INSERT_COUNT,
  QPACK_REASON_INTEGER,
  QPACK_REASON_NONE,
  QPACK_REASON_STATIC_INDEX,
  QPACK_REASON_TRUNCATED,
  QPACK_SECTION_TOO_LARGE,
  QPACK_SETTINGS_BLOCKED_STREAMS,
  QPACK_SETTINGS_MAX_TABLE_CAPACITY,
  QPACK_STATIC_LENGTH,
  QpackDecoder,
  QpackEncoder,
  qpackPushStreamCancellation,
} from "nish/net/qpack";
import { QpackDecoder, QpackEncoder, QPACK_OK } from "nish/net/qpack";

const name: u8[] = [58, 112, 97, 116, 104];   // ":path"
const value: u8[] = [47];                     // "/"

const enc = new QpackEncoder();                     // one per connection
const section: u8[] = [];
enc.beginSection(section);
enc.encodeField(section, name, 0, toI32(name.length), value, 0, toI32(value.length), false, true);

const dec = new QpackDecoder(16384);                // one per connection, reused
if (dec.decode(section, 0, toI32(section.length)) === QPACK_OK) {
  // field i: dec.bytes[dec.nameStart[i], + dec.nameLength[i]), and the value alike
}
Capacity 0 is the whole dynamic table

This endpoint advertises SETTINGS_QPACK_MAX_TABLE_CAPACITY 0 (the default, §5), so a peer's encoder may never insert, every field section it sends has a Required Insert Count of 0, and nothing in it may name the dynamic table. Its own encoder never inserts either, whatever the peer allows, so the field sections it writes begin 00 00 and reference the static table alone. That is what lets a stream be decoded the moment its HEADERS frame is whole: there is nothing to block on (§2.1.2) and nothing to acknowledge (§4.4.1).

What is refused. QpackDecoder.decode answers QPACK_DECOMPRESSION_FAILED for a section that ends inside a representation, an integer past 2^62 - 1 (or padded past the nine continuation bytes such an integer needs), a non-zero Required Insert Count (§4.5.1.1), a negative Base (§4.5.1.2), any reference to the dynamic table, relative or post-Base (§2.2.3), a static index past 98, and Huffman padding that is not EOS's prefix or an EOS inside a string.

receiveEncoderStream answers QPACK_ENCODER_STREAM_ERROR for a Set Dynamic Table Capacity above 0 (§4.3.1), any Insert (§3.2.2: every entry is larger than the table) and any Duplicate (§2.2.3: there is nothing to duplicate). The encoder's receiveDecoderStream answers QPACK_DECODER_STREAM_ERROR for a Section Acknowledgment (§4.4.1: no section it sent needs one), any Insert Count Increment (§4.4.3: it has inserted nothing) and a stream ID past 2^62 - 1. Each of those is a connection error, so each is sticky: the same answer comes back from every later call without reading anything, and reason says which rule it was (QPACK_REASON_*).

What is accepted

A Set Dynamic Table Capacity of 0 on the encoder stream, and a Stream Cancellation on the decoder stream, read a byte at a time so that an instruction may be split across STREAM frames anywhere. The only instruction this endpoint may want to send is a Stream Cancellation on its own decoder stream, which §4.2 lets a decoder of capacity 0 omit; it is qpackPushStreamCancellation. Opening the two streams (types QPACK_ENCODER_STREAM and QPACK_DECODER_STREAM) and refusing a second one of either are HTTP/3's.

A field section larger than the decoder's limit — each field its name, its value and 32 bytes, as SETTINGS_MAX_FIELD_SECTION_SIZE counts it (RFC 9114 §4.2.2) — answers QPACK_SECTION_TOO_LARGE, which is negative because it is not one of the RFC's codes: no table depends on the section, so decoding stops there, nothing is kept, and the next section decodes normally. HTTP/3 answers it with a 431, not by closing the connection.

Byte windows, and nothing allocated per section

Names and values go in as windows (buf, off, len) and come out as windows into the decoder's own bytes, which holds every name and value of the last section back to back. The decoder's arrays are emptied with pop, which keeps their storage, so a connection's decoder stops allocating once it has seen its largest section (WP34 N9). A window outside its buffer is the program's mistake and panics.

The Huffman code is RFC 7541 Appendix B's, which §4.1.2 uses unmodified, and comes from nish/net/hpack rather than a copy. The integers are this module's own because QPACK needs 62 bits and HPACK's stop at 31.

Written from RFC 9204, not ported from another implementation. Private names carry the qpack prefix because a std/ module's private functions share the importing program's flat symbol namespace (docs/wp26-stdlib.md §3e).

Functions

qpackPushStreamCancellation

Appends a Stream Cancellation for streamId (§4.4.2), the one instruction a decoder of capacity 0 may send on its decoder stream, and may also omit. A stream ID outside 0 to 2^62 - 1 panics.

const qpackPushStreamCancellation: (
  out: u8[],
  streamId: i64,
) => void
outu8[]required

Where the instruction goes, appended after what it holds: one byte for a stream ID under 63, else one plus its continuation bytes.

streamIdi64required

The ID of the request stream whose section the peer's encoder may forget, 0 to 2^62 - 1.

Classes

QpackDecoder

One HTTP/3 connection's receiving side: the field sections the peer's encoder sends on request streams, and the peer's encoder stream.

decode answers a section's fields as windows into bytes: field i's name is bytes[nameStart[i], + nameLength[i]), its value likewise, and neverIndexed[i] is its N bit, which an intermediary forwarding it must keep (§4.5.4). All of them are replaced by every decode.

class QpackDecoder
Member
new QpackDecoder(maxFieldSectionSize: i32) Makes a decoder with no fields, no connection error and no capacity instructions counted.
bytes: u8[] Every name and value of the last section decode answered, back to back; emptied by every decode call, including one that refuses, and valid until the next.
capacityInstructions: i32 How many Set Dynamic Table Capacity 0 instructions the encoder stream carried, saturating at 2^31 - 1.
count: i32 How many fields the last decode answered.
maxFieldSectionSize: i32 SETTINGS_MAX_FIELD_SECTION_SIZE as RFC 9114 §4.2.2 counts it.
nameLength: i32[] How many bytes field i's name has in bytes.
nameStart: i32[] Where field i's name starts in bytes, for i below count.
neverIndexed: boolean[] Field i's N bit (§4.5.4): true when the peer marked it never to be indexed; always false for an Indexed Field Line, which has no such bit.
reason: i32 Which rule the connection error broke, a QPACK_REASON_*; QPACK_REASON_NONE until a call answers QPACK_DECOMPRESSION_FAILED or QPACK_ENCODER_STREAM_ERROR. Reset by http3.ts's restart.
valueLength: i32[] How many bytes field i's value has in bytes.
valueStart: i32[] Where field i's value starts in bytes, for i below count.
decode(section: u8[], off: i32, len: i32): i64 Decodes one whole field section, section[off, off + len), and answers QPACK_OK, QPACK_SECTION_TOO_LARGE or QPACK_DECOMPRESSION_FAILED; the module comment lists what each means. A decoder whose encoder stream was refused answers QPACK_ENCODER_STREAM_ERROR again instead, since the connection is closing. Anything but QPACK_OK leaves no fields.
receiveEncoderStream(buf: u8[], off: i32, len: i32): i64 Reads the encoder stream's next bytes, buf[off, off + len), and answers QPACK_OK or QPACK_ENCODER_STREAM_ERROR (or, once a section was refused, QPACK_DECOMPRESSION_FAILED again). At capacity 0 the one instruction a peer may send is Set Dynamic Table Capacity 0, the single byte 0x20, so every other first byte is refused on sight: its top bits already say which instruction it begins, and none of them can be valid.

QpackEncoder

One HTTP/3 connection's sending side: field sections that reference the static table alone, and the peer's decoder stream.

It never inserts, so it needs no state for the peer's table capacity or its blocked-streams limit, whatever the peer's SETTINGS allow, and it never sends anything on its own encoder stream once the stream type is written.

class QpackEncoder
Member
new QpackEncoder() Makes an encoder whose decoder stream has carried nothing yet.
cancellations: i32 How many Stream Cancellations the decoder stream carried, saturating at 2^31 - 1.
lastCancelled: i64 The stream ID the last Stream Cancellation named; -1 until one arrives.
reason: i32 Which rule the decoder stream broke, a QPACK_REASON_*; QPACK_REASON_NONE until receiveDecoderStream answers QPACK_DECODER_STREAM_ERROR. Reset by http3.ts's restart.
beginSection(out: u8[]): void Appends the prefix every field section of this encoder begins with: a Required Insert Count of 0 and a Base of 0, the bytes 00 00.
encodeField(out: u8[], name: u8[], nameOff: i32, nameLen: i32, value: u8[], valueOff: i32, valueLen: i32, neverIndexed: boolean, huffman: boolean): void Appends one field line, name[nameOff, + nameLen) and value[valueOff, + valueLen), to the section in out. A field the static table holds whole is one Indexed Field Line; otherwise it is a literal, with its name by static index when the table has the name, the lowest index first, and each of its strings Huffman-coded when huffman is true and the code is the shorter spelling.

A field marked neverIndexed is always a literal with the N bit set, even when the static table holds it, so that an intermediary re-encoding it keeps it out of every dynamic table downstream (§4.5.4, §7.1.3).

A window outside its buffer panics.
receiveDecoderStream(buf: u8[], off: i32, len: i32): i64 Reads the decoder stream's next bytes, buf[off, off + len), and answers QPACK_OK or QPACK_DECODER_STREAM_ERROR. A Stream Cancellation is accepted and counted, its stream ID read across calls when the bytes split it. A Section Acknowledgment and an Insert Count Increment are refused on their first byte: this encoder sent no section that needs acknowledging and inserted nothing to count.

Constants

0x03

QPACK_DECODER_STREAM: i64

The unidirectional stream type of a decoder stream (§4.2).

0x0202

QPACK_DECODER_STREAM_ERROR: i64

The encoder could not interpret an instruction on the decoder stream (§6).

0x0200

QPACK_DECOMPRESSION_FAILED: i64

The decoder could not interpret a field section (§6).

0x02

QPACK_ENCODER_STREAM: i64

The unidirectional stream type of an encoder stream (§4.2).

0x0201

QPACK_ENCODER_STREAM_ERROR: i64

The decoder could not interpret an instruction on the encoder stream (§6).

32

QPACK_FIELD_OVERHEAD: i32

What a field costs a field section beyond its name and value (RFC 9114 §4.2.2).

0

QPACK_OK: i64

A call that met nothing to refuse.

11

QPACK_REASON_ACKNOWLEDGMENT: i32

A Section Acknowledgment (§4.4.1).

4

QPACK_REASON_BASE: i32

A field section whose Base is negative (§4.5.1.2).

8

QPACK_REASON_CAPACITY: i32

A Set Dynamic Table Capacity above 0 (§4.3.1).

10

QPACK_REASON_DUPLICATE: i32

A Duplicate (§4.3.4).

5

QPACK_REASON_DYNAMIC: i32

A field line naming the dynamic table, by relative or post-Base index (§2.2.3).

7

QPACK_REASON_HUFFMAN: i32

Huffman padding that is not a prefix of EOS, or EOS inside a string (RFC 7541 §5.2).

12

QPACK_REASON_INCREMENT: i32

An Insert Count Increment (§4.4.3).

9

QPACK_REASON_INSERT: i32

An Insert with Name Reference or with Literal Name (§3.2.2, §4.3.2, §4.3.3).

3

QPACK_REASON_INSERT_COUNT: i32

A field section whose Required Insert Count is not 0 (§4.5.1.1).

2

QPACK_REASON_INTEGER: i32

An integer past 2^62 - 1, or padded past nine continuation bytes (§4.1.1).

0

QPACK_REASON_NONE: i32

Nothing refused yet.

6

QPACK_REASON_STATIC_INDEX: i32

A static index past 98 (§3.1).

1

QPACK_REASON_TRUNCATED: i32

The bytes ended inside a representation, an integer or a string.

-1

QPACK_SECTION_TOO_LARGE: i64

A field section past the decoder's size limit. Not one of RFC 9204's codes and not fatal: HTTP/3 answers the request with a 431.

0x07

QPACK_SETTINGS_BLOCKED_STREAMS: i64

SETTINGS_QPACK_BLOCKED_STREAMS's identifier (§5); with no table nothing blocks, so 0.

0x01

QPACK_SETTINGS_MAX_TABLE_CAPACITY: i64

SETTINGS_QPACK_MAX_TABLE_CAPACITY's identifier (§5); this module's value is 0.

99

QPACK_STATIC_LENGTH: i32

The number of entries in the static table, indexes 0 to 98 (Appendix A).