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
}
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.
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.
QpackEncoder
One HTTP/3 connection's sending side: field sections that reference the static table alone, and the peer's decoder stream.
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[]requiredWhere the instruction goes, appended after what it holds: one byte for a stream ID under 63, else one plus its continuation bytes.
streamIdi64requiredThe 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).

