QPACK: Header Compression for HTTP over QUIC

Each entry possesses both an absolute index which is fixed for the lifetime of that entry and a relative index which changes over time based on the context of the reference. The first entry inserted has an absolute index of “1”; indices increase sequentially with each insertion.¶

The relative index begins at zero and increases in the opposite direction from the absolute index. Determining which entry has a relative index of “0” depends on the context of the reference.¶

On the control stream, a relative index of “0” always refers to the most recently inserted value in the dynamic table. Note that this means the entry referenced by a given relative index will change while interpreting instructions on the encoder stream.¶

Because frames from request streams can be delivered out of order with instructions on the control stream, relative indices are relative to the Base Index at the beginning of the header block (see Section 5.4.1). The Base Index is an absolute index. When interpreting the rest of the frame, the entry identified by Base Index has a relative index of zero. The relative indices of entries do not change while interpreting headers on a request or push stream.¶

A header block on the request stream can reference entries added after the entry identified by the Base Index. This allows an encoder to process a header block in a single pass and include references to entries added while processing this (or other) header blocks. Newly added entries are referenced using Post-Base instructions. Indices for Post-Base instructions increase in the same direction as absolute indices, but the zero value is one higher than the Base Index.¶

If the decoder encounters a reference to an entry which has already been dropped from the table or which is greater than the declared Largest Reference (see Section 5.4.1), this MUST be treated as a stream error of type HTTP_QPACK_DECOMPRESSION_FAILED error code. If this reference occurs on the control stream, this MUST be treated as a session error.¶

• Successful processing of a header block
• Abandonment of a stream which might have remaining header blocks
• Receipt of new dynamic table entries

Regardless of whether a header block contained blocking references, the knowledge that it was processed successfully permits the encoder to avoid evicting entries while references remain outstanding; see Section 6.3.1. When a stream is reset or abandoned, the indication that these header blocks will never be processed serves a similar function; see Section 5.3.3.¶

For the encoder to identify which dynamic table entries can be safely used without a stream becoming blocked, the encoder tracks the absolute index of the decoder’s Largest Known Received entry.¶

When blocking references are permitted, the encoder uses acknowledgement of header blocks to identify the Largest Known Received index, as described in Section 5.3.2.¶

To acknowledge dynamic table entries which are not referenced by header blocks, for example because the encoder or the decoder have chosen not to risk blocked streams, the decoder sends a Table State Synchronize instruction (see Section 5.3.1).¶

The prefixed integer from Section 5.1 of [RFC7541] is used heavily throughout this document. The format from [RFC7541] is used unmodified.¶

The string literal defined by Section 5.2 of [RFC7541] is also used throughout. This string format includes optional Huffman encoding.¶

HPACK defines string literals to begin on a byte boundary. They begin with a single flag (indicating whether the string is Huffman-coded), followed by the Length encoded as a 7-bit prefix integer, and finally Length octets of data. When Huffman encoding is enabled, the Huffman table from Appendix B of [RFC7541] is used without modification.¶

This document expands the definition of string literals and permits them to begin other than on a byte boundary. An “N-bit prefix string literal” begins with the same Huffman flag, followed by the length encoded as an (N-1)-bit prefix integer. The remainder of the string literal is unmodified.¶

A string literal without a prefix length noted is an 8-bit prefix string literal and follows the definitions in [RFC7541] without modification.¶

An addition to the header table where the header field name matches the header field name of an entry stored in the static table or the dynamic table starts with the ‘1’ one-bit pattern. The S bit indicates whether the reference is to the static (S=1) or dynamic (S=0) table. The header field name is represented using the relative index of that entry, which is represented as an integer with a 6-bit prefix (see Section 5.1 of [RFC7541]).¶

The header name reference is followed by the header field value represented as a string literal (see Section 5.2 of [RFC7541]).¶

An addition to the header table where both the header field name and the header field value are represented as string literals (see Section 5.1) starts with the ‘01’ two-bit pattern.¶

The name is represented as a 6-bit prefix string literal, while the value is represented as an 8-bit prefix string literal.¶

Duplication of an existing entry in the dynamic table starts with the ‘000’ three-bit pattern. The relative index of the existing entry is represented as an integer with a 5-bit prefix.¶

The existing entry is re-inserted into the dynamic table without resending either the name or the value. This is useful to mitigate the eviction of older entries which are frequently referenced, both to avoid the need to resend the header and to avoid the entry in the table blocking the ability to insert new headers.¶

An encoder informs the decoder of a change to the size of the dynamic table using an instruction which begins with the ‘001’ three-bit pattern. The new maximum table size is represented as an integer with a 5-bit prefix (see Section 5.1 of [RFC7541]).¶

The new maximum size MUST be lower than or equal to the limit determined by the protocol using QPACK. A value that exceeds this limit MUST be treated as a decoding error. In HTTP/QUIC, this limit is the value of the SETTINGS_HEADER_TABLE_SIZE parameter (see Section 4) received from the decoder.¶

Reducing the maximum size of the dynamic table can cause entries to be evicted (see Section 4.3 of [RFC7541]). This MUST NOT cause the eviction of entries with outstanding references (see Section 6.3). Changing the size of the dynamic table is not acknowledged as this instruction does not insert an entry.¶

The Table State Synchronize instruction begins with the ‘00’ two-bit pattern. The instruction specifies the total number of dynamic table inserts and duplications since the last Table State Synchronize or Header Acknowledgement that increased the Largest Known Received dynamic table entry. This is encoded as a 6-bit prefix integer. The encoder uses this value to determine which table entries might cause a stream to become blocked, as described in Section 2.3.1.¶

A decoder chooses when to emit Table State Synchronize instructions. Emitting a Table State Synchronize after adding each new dynamic table entry will provide the most timely feedback to the encoder, but could be redundant with other decoder feedback. By delaying a Table State Synchronize, a decoder might be able to coalesce multiple Table State Synchronize instructions, or replace them entirely with Header Acknowledgements. However, delaying too long may lead to compression inefficiencies if the encoder waits for an entry to be acknowledged before using it.¶

After processing a header block on a request or push stream, the decoder emits a Header Acknowledgement instruction on the decoder stream. The instruction begins with the ‘1’ one-bit pattern and includes the request stream’s stream ID, encoded as a 7-bit prefix integer. It is used by the peer’s QPACK encoder to know when it is safe to evict an entry.¶

The same Stream ID can be identified multiple times, as multiple header blocks can be sent on a single stream in the case of intermediate responses, trailers, and pushed requests. Since header frames on each stream are received and processed in order, this gives the encoder precise feedback on which header blocks within a stream have been fully processed.¶

When blocking references are permitted, the encoder uses acknowledgement of header blocks to update the Largest Known Received index. If a header block was potentially blocking, the acknowledgement implies that the decoder has received all dynamic table state necessary to process the header block. If the Largest Reference of an acknowledged header block was greater than the encoder’s current Largest Known Received index, the block’s Largest Reference becomes the new Largest Known Received.¶

A stream that is reset might have multiple outstanding header blocks. A decoder that receives a stream reset before the end of a stream generates a Stream Cancellation instruction on the decoder stream. Similarly, a decoder that abandons reading of a stream needs to signal this using the Stream Cancellation instruction. This signals to the encoder that all references to the dynamic table on that stream are no longer outstanding.¶

An encoder cannot infer from this instruction that any updates to the dynamic table have been received.¶

The instruction begins with the ‘01’ two-bit pattern. The instruction includes the stream ID of the affected stream - a request or push stream - encoded as a 6-bit prefix integer.¶

Header data is prefixed with two integers, Largest Reference and Base Index.¶

Largest Reference identifies the largest absolute dynamic index referenced in the block. Blocking decoders use the Largest Reference to determine when it is safe to process the rest of the block.¶

Base Index is used to resolve references in the dynamic table as described in Section 2.2.1.¶

A single-pass encoder is expected to determine the absolute value of Base Index before encoding a header block. If the encoder inserted entries in the dynamic table while encoding the header block, Largest Reference will be greater than Base Index, so the encoded difference is negative and the sign bit is set to 1. If the header block did not reference the most recent entry in the table and did not insert any new entries, Base Index will be greater than the Largest Reference, so the delta will be positive and the sign bit is set to 0.¶

An encoder that produces table updates before encoding a header block might set Largest Reference and Base Index to the same value. When Largest Reference and Base Index are equal, the Delta Base Index is encoded with a zero sign bit. A sign bit set to 1 when the Delta Base Index is 0 MUST be treated as a decoder error.¶

A header block that does not reference the dynamic table can use any value for Base Index; setting both Largest Reference and Base Index to zero is the most efficient encoding.¶

The encoder MUST NOT permit an entry to be evicted while a reference to that entry remains unacknowledged. If a new header to be inserted into the dynamic table would cause the eviction of such an entry, the encoder MUST NOT emit the insert instruction until the reference has been processed by the decoder and acknowledged.¶

The encoder can emit a literal representation for the new header in order to avoid encoding delays, and MAY insert the header into the table later if desired.¶

To ensure that the blocked eviction case is rare, references to the oldest entries in the dynamic table SHOULD be avoided. When one of the oldest entries in the table is still actively used for references, the encoder SHOULD emit an Duplicate representation instead (see Section 5.2.3).¶

For header blocks encoded in non-blocking mode, the encoder needs to forego indexed representations that refer to table updates which have not yet been acknowledged with Section 5.3. Since all table updates are processed in sequence on the control stream, an index into the dynamic table is sufficient to track which entries have been acknowledged.¶

To track blocked streams, the necessary Base Index value for each stream can be used. Whenever the decoder processes a table update, it can begin decoding any blocked streams that now have their dependencies satisfied.¶