idnits 2.17.1 draft-ietf-quic-qpack-11.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** The abstract seems to contain references ([2], [3], [1]), which it shouldn't. Please replace those with straight textual mentions of the documents in question. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year == Using lowercase 'not' together with uppercase 'MUST', 'SHALL', 'SHOULD', or 'RECOMMENDED' is not an accepted usage according to RFC 2119. Please use uppercase 'NOT' together with RFC 2119 keywords (if that is what you mean). Found 'MUST not' in this paragraph: To bound the memory requirements of the decoder, the decoder limits the maximum value the encoder is permitted to set for the dynamic table capacity. In HTTP/3, this limit is determined by the value of SETTINGS_QPACK_MAX_TABLE_CAPACITY sent by the decoder (see Section 5). The encoder MUST not set a dynamic table capacity that exceeds this maximum, but it can choose to use a lower dynamic table capacity (see Section 4.3.1). -- The document date (November 04, 2019) is 1628 days in the past. Is this intentional? -- Found something which looks like a code comment -- if you have code sections in the document, please surround them with '' and '' lines. Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) -- Looks like a reference, but probably isn't: '1' on line 1284 -- Looks like a reference, but probably isn't: '2' on line 1286 -- Looks like a reference, but probably isn't: '3' on line 1288 == Outdated reference: A later version (-34) exists of draft-ietf-quic-http-24 == Outdated reference: A later version (-34) exists of draft-ietf-quic-transport-24 -- Obsolete informational reference (is this intentional?): RFC 7540 (Obsoleted by RFC 9113) Summary: 1 error (**), 0 flaws (~~), 4 warnings (==), 6 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 QUIC C. Krasic 3 Internet-Draft Netflix 4 Intended status: Standards Track M. Bishop 5 Expires: May 7, 2020 Akamai Technologies 6 A. Frindell, Ed. 7 Facebook 8 November 04, 2019 10 QPACK: Header Compression for HTTP/3 11 draft-ietf-quic-qpack-11 13 Abstract 15 This specification defines QPACK, a compression format for 16 efficiently representing HTTP header fields, to be used in HTTP/3. 17 This is a variation of HPACK header compression that seeks to reduce 18 head-of-line blocking. 20 Note to Readers 22 Discussion of this draft takes place on the QUIC working group 23 mailing list (quic@ietf.org), which is archived at 24 https://mailarchive.ietf.org/arch/search/?email_list=quic [1]. 26 Working Group information can be found at https://github.com/quicwg 27 [2]; source code and issues list for this draft can be found at 28 https://github.com/quicwg/base-drafts/labels/-qpack [3]. 30 Status of This Memo 32 This Internet-Draft is submitted in full conformance with the 33 provisions of BCP 78 and BCP 79. 35 Internet-Drafts are working documents of the Internet Engineering 36 Task Force (IETF). Note that other groups may also distribute 37 working documents as Internet-Drafts. The list of current Internet- 38 Drafts is at https://datatracker.ietf.org/drafts/current/. 40 Internet-Drafts are draft documents valid for a maximum of six months 41 and may be updated, replaced, or obsoleted by other documents at any 42 time. It is inappropriate to use Internet-Drafts as reference 43 material or to cite them other than as "work in progress." 45 This Internet-Draft will expire on May 7, 2020. 47 Copyright Notice 49 Copyright (c) 2019 IETF Trust and the persons identified as the 50 document authors. All rights reserved. 52 This document is subject to BCP 78 and the IETF Trust's Legal 53 Provisions Relating to IETF Documents 54 (https://trustee.ietf.org/license-info) in effect on the date of 55 publication of this document. Please review these documents 56 carefully, as they describe your rights and restrictions with respect 57 to this document. Code Components extracted from this document must 58 include Simplified BSD License text as described in Section 4.e of 59 the Trust Legal Provisions and are provided without warranty as 60 described in the Simplified BSD License. 62 Table of Contents 64 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 65 1.1. Conventions and Definitions . . . . . . . . . . . . . . . 4 66 1.2. Notational Conventions . . . . . . . . . . . . . . . . . 4 67 2. Compression Process Overview . . . . . . . . . . . . . . . . 5 68 2.1. Encoder . . . . . . . . . . . . . . . . . . . . . . . . . 5 69 2.1.1. Reference Tracking . . . . . . . . . . . . . . . . . 5 70 2.1.2. Blocked Dynamic Table Insertions . . . . . . . . . . 6 71 2.1.3. Blocked Streams . . . . . . . . . . . . . . . . . . . 7 72 2.1.4. Known Received Count . . . . . . . . . . . . . . . . 8 73 2.2. Decoder . . . . . . . . . . . . . . . . . . . . . . . . . 8 74 2.2.1. Blocked Decoding . . . . . . . . . . . . . . . . . . 8 75 2.2.2. State Synchronization . . . . . . . . . . . . . . . . 9 76 2.2.3. Invalid References . . . . . . . . . . . . . . . . . 10 77 3. Header Tables . . . . . . . . . . . . . . . . . . . . . . . . 10 78 3.1. Static Table . . . . . . . . . . . . . . . . . . . . . . 10 79 3.2. Dynamic Table . . . . . . . . . . . . . . . . . . . . . . 11 80 3.2.1. Dynamic Table Size . . . . . . . . . . . . . . . . . 11 81 3.2.2. Dynamic Table Capacity and Eviction . . . . . . . . . 11 82 3.2.3. Maximum Dynamic Table Capacity . . . . . . . . . . . 12 83 3.2.4. Absolute Indexing . . . . . . . . . . . . . . . . . . 12 84 3.2.5. Relative Indexing . . . . . . . . . . . . . . . . . . 12 85 3.2.6. Post-Base Indexing . . . . . . . . . . . . . . . . . 13 86 4. Wire Format . . . . . . . . . . . . . . . . . . . . . . . . . 14 87 4.1. Primitives . . . . . . . . . . . . . . . . . . . . . . . 14 88 4.1.1. Prefixed Integers . . . . . . . . . . . . . . . . . . 14 89 4.1.2. String Literals . . . . . . . . . . . . . . . . . . . 14 90 4.2. Encoder and Decoder Streams . . . . . . . . . . . . . . . 15 91 4.3. Encoder Instructions . . . . . . . . . . . . . . . . . . 15 92 4.3.1. Set Dynamic Table Capacity . . . . . . . . . . . . . 16 93 4.3.2. Insert With Name Reference . . . . . . . . . . . . . 16 94 4.3.3. Insert Without Name Reference . . . . . . . . . . . . 17 95 4.3.4. Duplicate . . . . . . . . . . . . . . . . . . . . . . 17 96 4.4. Decoder Instructions . . . . . . . . . . . . . . . . . . 18 97 4.4.1. Header Acknowledgement . . . . . . . . . . . . . . . 18 98 4.4.2. Stream Cancellation . . . . . . . . . . . . . . . . . 18 99 4.4.3. Insert Count Increment . . . . . . . . . . . . . . . 19 100 4.5. Header Block Representations . . . . . . . . . . . . . . 19 101 4.5.1. Header Block Prefix . . . . . . . . . . . . . . . . . 19 102 4.5.2. Indexed Header Field . . . . . . . . . . . . . . . . 22 103 4.5.3. Indexed Header Field With Post-Base Index . . . . . . 22 104 4.5.4. Literal Header Field With Name Reference . . . . . . 23 105 4.5.5. Literal Header Field With Post-Base Name Reference . 24 106 4.5.6. Literal Header Field Without Name Reference . . . . . 24 107 5. Configuration . . . . . . . . . . . . . . . . . . . . . . . . 25 108 6. Error Handling . . . . . . . . . . . . . . . . . . . . . . . 25 109 7. Security Considerations . . . . . . . . . . . . . . . . . . . 26 110 8. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 26 111 8.1. Settings Registration . . . . . . . . . . . . . . . . . . 26 112 8.2. Stream Type Registration . . . . . . . . . . . . . . . . 26 113 8.3. Error Code Registration . . . . . . . . . . . . . . . . . 27 114 9. References . . . . . . . . . . . . . . . . . . . . . . . . . 27 115 9.1. Normative References . . . . . . . . . . . . . . . . . . 27 116 9.2. Informative References . . . . . . . . . . . . . . . . . 28 117 9.3. URIs . . . . . . . . . . . . . . . . . . . . . . . . . . 28 118 Appendix A. Static Table . . . . . . . . . . . . . . . . . . . . 28 119 Appendix B. Sample One Pass Encoding Algorithm . . . . . . . . . 33 120 Appendix C. Change Log . . . . . . . . . . . . . . . . . . . . . 35 121 C.1. Since draft-ietf-quic-qpack-10 . . . . . . . . . . . . . 35 122 C.2. Since draft-ietf-quic-qpack-09 . . . . . . . . . . . . . 35 123 C.3. Since draft-ietf-quic-qpack-08 . . . . . . . . . . . . . 35 124 C.4. Since draft-ietf-quic-qpack-06 . . . . . . . . . . . . . 35 125 C.5. Since draft-ietf-quic-qpack-05 . . . . . . . . . . . . . 35 126 C.6. Since draft-ietf-quic-qpack-04 . . . . . . . . . . . . . 35 127 C.7. Since draft-ietf-quic-qpack-03 . . . . . . . . . . . . . 35 128 C.8. Since draft-ietf-quic-qpack-02 . . . . . . . . . . . . . 36 129 C.9. Since draft-ietf-quic-qpack-01 . . . . . . . . . . . . . 36 130 C.10. Since draft-ietf-quic-qpack-00 . . . . . . . . . . . . . 36 131 C.11. Since draft-ietf-quic-qcram-00 . . . . . . . . . . . . . 36 132 Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . . . 37 133 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 37 135 1. Introduction 137 The QUIC transport protocol [QUIC-TRANSPORT] is designed to support 138 HTTP semantics, and its design subsumes many of the features of 139 HTTP/2 [RFC7540]. HTTP/2 uses HPACK [RFC7541] for header 140 compression. If HPACK were used for HTTP/3 [HTTP3], it would induce 141 head-of-line blocking due to built-in assumptions of a total ordering 142 across frames on all streams. 144 QPACK reuses core concepts from HPACK, but is redesigned to allow 145 correctness in the presence of out-of-order delivery, with 146 flexibility for implementations to balance between resilience against 147 head-of-line blocking and optimal compression ratio. The design 148 goals are to closely approach the compression ratio of HPACK with 149 substantially less head-of-line blocking under the same loss 150 conditions. 152 1.1. Conventions and Definitions 154 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 155 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 156 "OPTIONAL" in this document are to be interpreted as described in BCP 157 14 [RFC2119] [RFC8174] when, and only when, they appear in all 158 capitals, as shown here. 160 Definitions of terms that are used in this document: 162 Header field: A name-value pair sent as part of an HTTP message. 164 Header list: An ordered collection of header fields associated with 165 an HTTP message. A header list can contain multiple header fields 166 with the same name. It can also contain duplicate header fields. 168 Header block: The compressed representation of a header list. 170 Encoder: An implementation which transforms a header list into a 171 header block. 173 Decoder: An implementation which transforms a header block into a 174 header list. 176 Absolute Index: A unique index for each entry in the dynamic table. 178 Base: A reference point for relative and post-base indices. 179 References to dynamic table entries in header blocks are relative 180 to a Base. 182 Insert Count: The total number of entries inserted in the dynamic 183 table. 185 QPACK is a name, not an acronym. 187 1.2. Notational Conventions 189 Diagrams use the format described in Section 3.1 of [RFC2360], with 190 the following additional conventions: 192 x (A) Indicates that x is A bits long 194 x (A+) Indicates that x uses the prefixed integer encoding defined 195 in Section 4.1.1, beginning with an A-bit prefix. 197 x ... Indicates that x is variable-length and extends to the end of 198 the region. 200 2. Compression Process Overview 202 Like HPACK, QPACK uses two tables for associating header fields to 203 indices. The static table (see Section 3.1) is predefined and 204 contains common header fields (some of them with an empty value). 205 The dynamic table (see Section 3.2) is built up over the course of 206 the connection and can be used by the encoder to index header fields 207 in the encoded header lists. 209 QPACK defines unidirectional streams for sending instructions from 210 encoder to decoder and vice versa. 212 2.1. Encoder 214 An encoder converts a header list into a header block by emitting 215 either an indexed or a literal representation for each header field 216 in the list (see Section 4.5). Indexed representations achieve high 217 compression by replacing the literal name and possibly the value with 218 an index to either the static or dynamic table. References to the 219 static table and literal representations do not require any dynamic 220 state and never risk head-of-line blocking. References to the 221 dynamic table risk head-of-line blocking if the encoder has not 222 received an acknowledgement indicating the entry is available at the 223 decoder. 225 An encoder MAY insert any entry in the dynamic table it chooses; it 226 is not limited to header fields it is compressing. 228 QPACK preserves the ordering of header fields within each header 229 list. An encoder MUST emit header field representations in the order 230 they appear in the input header list. 232 QPACK is designed to contain the more complex state tracking to the 233 encoder, while the decoder is relatively simple. 235 2.1.1. Reference Tracking 237 An encoder MUST ensure that a header block which references a dynamic 238 table entry is not processed by the decoder after the referenced 239 entry has been evicted. Hence the encoder needs to retain 240 information about each compressed header block that references the 241 dynamic table until that header block is acknowledged by the decoder 242 (see Section 4.4.1). 244 2.1.2. Blocked Dynamic Table Insertions 246 A dynamic table entry is considered blocking and cannot be evicted 247 until its insertion has been acknowledged and there are no 248 outstanding unacknowledged references to the entry. In particular, a 249 dynamic table entry that has never been referenced can still be 250 blocking. 252 An encoder MUST NOT insert an entry into the dynamic table (or 253 duplicate an existing entry) if doing so would evict a blocking 254 entry. In order to avoid this, an encoder that uses the dynamic 255 table has to keep track of blocking entries. 257 Note: A blocking entry is unrelated to a blocked stream, see 258 Section 2.1.3. 260 2.1.2.1. Avoiding Blocked Insertions 262 To ensure that the encoder is not prevented from adding new entries, 263 the encoder can avoid referencing entries that are close to eviction. 264 Rather than reference such an entry, the encoder can emit a Duplicate 265 instruction (see Section 4.3.4), and reference the duplicate instead. 267 Determining which entries are too close to eviction to reference is 268 an encoder preference. One heuristic is to target a fixed amount of 269 available space in the dynamic table: either unused space or space 270 that can be reclaimed by evicting non-blocking entries. To achieve 271 this, the encoder can maintain a draining index, which is the 272 smallest absolute index (see Section 3.2.4) in the dynamic table that 273 it will emit a reference for. As new entries are inserted, the 274 encoder increases the draining index to maintain the section of the 275 table that it will not reference. If the encoder does not create new 276 references to entries with an absolute index lower than the draining 277 index, the number of unacknowledged references to those entries will 278 eventually become zero, allowing them to be evicted. 280 +----------+---------------------------------+--------+ 281 | Draining | Referenceable | Unused | 282 | Entries | Entries | Space | 283 +----------+---------------------------------+--------+ 284 ^ ^ ^ 285 | | | 286 Dropping Draining Index Insertion Point 287 Point 289 Figure 1: Draining Dynamic Table Entries 291 2.1.3. Blocked Streams 293 Because QUIC does not guarantee order between data on different 294 streams, a decoder might encounter a header block that references a 295 dynamic table entry that it has not yet received. 297 Each header block contains a Required Insert Count (see 298 Section 4.5.1), the lowest possible value for the Insert Count with 299 which the header block can be decoded. For a header block with 300 references to the dynamic table, the Required Insert Count is one 301 larger than the largest absolute index of all referenced dynamic 302 table entries. For a header block with no references to the dynamic 303 table, the Required Insert Count is zero. 305 When the decoder receives a header block with a Required Insert Count 306 greater than its own Insert Count, the stream cannot be processed 307 immediately, and is considered "blocked" (see Section 2.2.1). 309 The decoder specifies an upper bound on the number of streams which 310 can be blocked using the SETTINGS_QPACK_BLOCKED_STREAMS setting (see 311 Section 5). An encoder MUST limit the number of streams which could 312 become blocked to the value of SETTINGS_QPACK_BLOCKED_STREAMS at all 313 times. If a decoder encounters more blocked streams than it promised 314 to support, it MUST treat this as a connection error of type 315 HTTP_QPACK_DECOMPRESSION_FAILED. 317 Note that the decoder might not become blocked on every stream which 318 risks becoming blocked. 320 An encoder can decide whether to risk having a stream become blocked. 321 If permitted by the value of SETTINGS_QPACK_BLOCKED_STREAMS, 322 compression efficiency can often be improved by referencing dynamic 323 table entries that are still in transit, but if there is loss or 324 reordering the stream can become blocked at the decoder. An encoder 325 can avoid the risk of blocking by only referencing dynamic table 326 entries which have been acknowledged, but this could mean using 327 literals. Since literals make the header block larger, this can 328 result in the encoder becoming blocked on congestion or flow control 329 limits. 331 2.1.4. Known Received Count 333 The Known Received Count is the total number of dynamic table 334 insertions and duplications acknowledged by the decoder. The encoder 335 tracks the Known Received Count in order to identify which dynamic 336 table entries can be referenced without potentially blocking a 337 stream. The decoder tracks the Known Received Count in order to be 338 able to send Insert Count Increment instructions (see Section 4.4.3). 340 If a header block was potentially blocking, the encoder infers from 341 receiving a Header Acknowledgement instruction (Section 4.4.1) that 342 the decoder has received all dynamic table state necessary to process 343 that header block. If the Required Insert Count of the acknowledged 344 header block is greater than the current Known Received Count, the 345 encoder updates the Known Received Count to the value of the Required 346 Insert Count of the acknowledged header block. 348 To acknowledge dynamic table entries which are not referenced by 349 header blocks, for example because the encoder or the decoder have 350 chosen not to risk blocked streams, the decoder sends an Insert Count 351 Increment instruction (see Section 4.4.3). 353 2.2. Decoder 355 As in HPACK, the decoder processes header blocks and emits the 356 corresponding header lists. It also processes instructions received 357 on the encoder stream that modify the dynamic table. Note that 358 header blocks and encoder stream instructions arrive on separate 359 streams. This is unlike HPACK, where header blocks can contain 360 instructions that modify the dynamic table, and there is no dedicated 361 stream of HPACK instructions. 363 The decoder MUST emit header fields in the order their 364 representations appear in the input header block. 366 2.2.1. Blocked Decoding 368 Upon receipt of a header block, the decoder examines the Required 369 Insert Count. When the Required Insert Count is less than or equal 370 to the decoder's Insert Count, the header block can be processed 371 immediately. Otherwise, the stream on which the header block was 372 received becomes blocked. 374 While blocked, header block data SHOULD remain in the blocked 375 stream's flow control window. A stream becomes unblocked when the 376 Insert Count becomes greater than or equal to the Required Insert 377 Count for all header blocks the decoder has started reading from the 378 stream. 380 When processing header blocks, the decoder expects the Required 381 Insert Count to exactly match the value defined in Section 2.1.3. If 382 it encounters a smaller value than expected, it MUST treat this as a 383 connection error of type HTTP_QPACK_DECOMPRESSION_FAILED (see 384 Section 2.2.3). If it encounters a larger value than expected, it 385 MAY treat this as a connection error of type 386 HTTP_QPACK_DECOMPRESSION_FAILED. 388 2.2.2. State Synchronization 390 The decoder signals the following events by emitting decoder 391 instructions (Section 4.4) on the decoder stream. 393 2.2.2.1. Completed Processing of a Header Block 395 After the decoder finishes decoding a header block containing dynamic 396 table references, it MUST emit a Header Acknowledgement instruction 397 (Section 4.4.1). A stream may carry multiple header blocks in the 398 case of intermediate responses, trailers, and pushed requests. The 399 encoder interprets each Header Acknowledgement instruction as 400 acknowledging the earliest unacknowledged header block containing 401 dynamic table references sent on the given stream. 403 2.2.2.2. Abandonment of a Stream 405 When an endpoint receives a stream reset before the end of a stream 406 or before all header blocks are processed on that stream, or when it 407 abandons reading of a stream, it generates a Stream Cancellation 408 instruction (see Section 4.4.2). This signals to the encoder that 409 all references to the dynamic table on that stream are no longer 410 outstanding. A decoder with a maximum dynamic table capacity equal 411 to zero (see Section 3.2.3) MAY omit sending Stream Cancellations, 412 because the encoder cannot have any dynamic table references. An 413 encoder cannot infer from this instruction that any updates to the 414 dynamic table have been received. 416 The Header Acknowledgement and Stream Cancellation instructions 417 permit the encoder to remove references to entries in the dynamic 418 table. When an entry with absolute index lower than the Known 419 Received Count has zero references, then it is no longer considered 420 blocking (see Section 2.1.2). 422 2.2.2.3. New Table Entries 424 After receiving new table entries on the encoder stream, the decoder 425 chooses when to emit Insert Count Increment instructions (see 426 Section 4.4.3). Emitting this instruction after adding each new 427 dynamic table entry will provide the timeliest feedback to the 428 encoder, but could be redundant with other decoder feedback. By 429 delaying an Insert Count Increment instruction, the decoder might be 430 able to coalesce multiple Insert Count Increment instructions, or 431 replace them entirely with Header Acknowledgements (see 432 Section 4.4.1). However, delaying too long may lead to compression 433 inefficiencies if the encoder waits for an entry to be acknowledged 434 before using it. 436 2.2.3. Invalid References 438 If the decoder encounters a reference in a header block 439 representation to a dynamic table entry which has already been 440 evicted or which has an absolute index greater than or equal to the 441 declared Required Insert Count (see Section 4.5.1), it MUST treat 442 this as a connection error of type "HTTP_QPACK_DECOMPRESSION_FAILED". 444 If the decoder encounters a reference in an encoder instruction to a 445 dynamic table entry which has already been evicted, it MUST treat 446 this as a connection error of type "HTTP_QPACK_ENCODER_STREAM_ERROR". 448 3. Header Tables 450 Unlike in HPACK, entries in the QPACK static and dynamic tables are 451 addressed separately. The following sections describe how entries in 452 each table are addressed. 454 3.1. Static Table 456 The static table consists of a predefined static list of header 457 fields, each of which has a fixed index over time. Its entries are 458 defined in Appendix A. 460 All entries in the static table have a name and a value. However, 461 values can be empty (that is, have a length of 0). Each entry is 462 identified by a unique index. 464 Note that the QPACK static table is indexed from 0, whereas the HPACK 465 static table is indexed from 1. 467 When the decoder encounters an invalid static table index in a header 468 block representation it MUST treat this as a connection error of type 469 "HTTP_QPACK_DECOMPRESSION_FAILED". If this index is received on the 470 encoder stream, this MUST be treated as a connection error of type 471 "HTTP_QPACK_ENCODER_STREAM_ERROR". 473 3.2. Dynamic Table 475 The dynamic table consists of a list of header fields maintained in 476 first-in, first-out order. Each HTTP/3 endpoint holds a dynamic 477 table that is initially empty. Entries are added by encoder 478 instructions received on the encoder stream (see Section 4.3). 480 The dynamic table can contain duplicate entries (i.e., entries with 481 the same name and same value). Therefore, duplicate entries MUST NOT 482 be treated as an error by the decoder. 484 Dynamic table entries can have empty values. 486 3.2.1. Dynamic Table Size 488 The size of the dynamic table is the sum of the size of its entries. 490 The size of an entry is the sum of its name's length in bytes, its 491 value's length in bytes, and 32. The size of an entry is calculated 492 using the length of its name and value without Huffman encoding 493 applied. 495 3.2.2. Dynamic Table Capacity and Eviction 497 The encoder sets the capacity of the dynamic table, which serves as 498 the upper limit on its size. The initial capacity of the dynamic 499 table is zero. The encoder sends a Set Dynamic Table Capacity 500 instruction (Section 4.3.1) with a non-zero capacity to begin using 501 the dynamic table. 503 Before a new entry is added to the dynamic table, entries are evicted 504 from the end of the dynamic table until the size of the dynamic table 505 is less than or equal to (table capacity - size of new entry). The 506 encoder MUST NOT cause a blocking dynamic table entry to be evicted 507 (see Section 2.1.2). The new entry is then added to the table. It 508 is an error if the encoder attempts to add an entry that is larger 509 than the dynamic table capacity; the decoder MUST treat this as a 510 connection error of type "HTTP_QPACK_ENCODER_STREAM_ERROR". 512 A new entry can reference an entry in the dynamic table that will be 513 evicted when adding this new entry into the dynamic table. 514 Implementations are cautioned to avoid deleting the referenced name 515 or value if the referenced entry is evicted from the dynamic table 516 prior to inserting the new entry. 518 Whenever the dynamic table capacity is reduced by the encoder (see 519 Section 4.3.1), entries are evicted from the end of the dynamic table 520 until the size of the dynamic table is less than or equal to the new 521 table capacity. This mechanism can be used to completely clear 522 entries from the dynamic table by setting a capacity of 0, which can 523 subsequently be restored. 525 3.2.3. Maximum Dynamic Table Capacity 527 To bound the memory requirements of the decoder, the decoder limits 528 the maximum value the encoder is permitted to set for the dynamic 529 table capacity. In HTTP/3, this limit is determined by the value of 530 SETTINGS_QPACK_MAX_TABLE_CAPACITY sent by the decoder (see 531 Section 5). The encoder MUST not set a dynamic table capacity that 532 exceeds this maximum, but it can choose to use a lower dynamic table 533 capacity (see Section 4.3.1). 535 For clients using 0-RTT data in HTTP/3, the server's maximum table 536 capacity is the remembered value of the setting, or zero if the value 537 was not previously sent. When the client's 0-RTT value of the 538 SETTING is zero, the server MAY set it to a non-zero value in its 539 SETTINGS frame. If the remembered value is non-zero, the server MUST 540 send the same non-zero value in its SETTINGS frame. If it specifies 541 any other value, or omits SETTINGS_QPACK_MAX_TABLE_CAPACITY from 542 SETTINGS, the encoder must treat this as a connection error of type 543 "HTTP_QPACK_DECODER_STREAM_ERROR". 545 For HTTP/3 servers and HTTP/3 clients when 0-RTT is not attempted or 546 is rejected, the maximum table capacity is 0 until the encoder 547 processes a SETTINGS frame with a non-zero value of 548 SETTINGS_QPACK_MAX_TABLE_CAPACITY. 550 When the maximum table capacity is zero, the encoder MUST NOT insert 551 entries into the dynamic table, and MUST NOT send any encoder 552 instructions on the encoder stream. 554 3.2.4. Absolute Indexing 556 Each entry possesses an absolute index which is fixed for the 557 lifetime of that entry. The first entry inserted has an absolute 558 index of "0"; indices increase by one with each insertion. 560 3.2.5. Relative Indexing 562 Relative indices begin at zero and increase in the opposite direction 563 from the absolute index. Determining which entry has a relative 564 index of "0" depends on the context of the reference. 566 In encoder instructions (see Section 4.3), a relative index of "0" 567 refers to the most recently inserted value in the dynamic table. 568 Note that this means the entry referenced by a given relative index 569 will change while interpreting instructions on the encoder stream. 571 +-----+---------------+-------+ 572 | n-1 | ... | d | Absolute Index 573 + - - +---------------+ - - - + 574 | 0 | ... | n-d-1 | Relative Index 575 +-----+---------------+-------+ 576 ^ | 577 | V 578 Insertion Point Dropping Point 580 n = count of entries inserted 581 d = count of entries dropped 583 Example Dynamic Table Indexing - Encoder Stream 585 Unlike in encoder instructions, relative indices in header block 586 representations are relative to the Base at the beginning of the 587 header block (see Section 4.5.1). This ensures that references are 588 stable even if header blocks and dynamic table updates are processed 589 out of order. 591 In a header block a relative index of "0" refers to the entry with 592 absolute index equal to Base - 1. 594 Base 595 | 596 V 597 +-----+-----+-----+-----+-------+ 598 | n-1 | n-2 | n-3 | ... | d | Absolute Index 599 +-----+-----+ - +-----+ - + 600 | 0 | ... | n-d-3 | Relative Index 601 +-----+-----+-------+ 603 n = count of entries inserted 604 d = count of entries dropped 605 In this example, Base = n - 2 607 Example Dynamic Table Indexing - Relative Index in Header Block 609 3.2.6. Post-Base Indexing 611 Post-Base indices are used in header block instructions for entries 612 with absolute indices greater than or equal to Base, starting at 0 613 for the entry with absolute index equal to Base, and increasing in 614 the same direction as the absolute index. 616 Post-Base indices allow an encoder to process a header block in a 617 single pass and include references to entries added while processing 618 this (or other) header blocks. 620 Base 621 | 622 V 623 +-----+-----+-----+-----+-----+ 624 | n-1 | n-2 | n-3 | ... | d | Absolute Index 625 +-----+-----+-----+-----+-----+ 626 | 1 | 0 | Post-Base Index 627 +-----+-----+ 629 n = count of entries inserted 630 d = count of entries dropped 631 In this example, Base = n - 2 633 Example Dynamic Table Indexing - Post-Base Index in Header Block 635 4. Wire Format 637 4.1. Primitives 639 4.1.1. Prefixed Integers 641 The prefixed integer from Section 5.1 of [RFC7541] is used heavily 642 throughout this document. The format from [RFC7541] is used 643 unmodified. Note, however, that QPACK uses some prefix sizes not 644 actually used in HPACK. 646 QPACK implementations MUST be able to decode integers up to and 647 including 62 bits long. 649 4.1.2. String Literals 651 The string literal defined by Section 5.2 of [RFC7541] is also used 652 throughout. This string format includes optional Huffman encoding. 654 HPACK defines string literals to begin on a byte boundary. They 655 begin with a single bit flag, denoted as 'H' in this document 656 (indicating whether the string is Huffman-coded), followed by the 657 Length encoded as a 7-bit prefix integer, and finally Length bytes of 658 data. When Huffman encoding is enabled, the Huffman table from 659 Appendix B of [RFC7541] is used without modification. 661 This document expands the definition of string literals and permits 662 them to begin other than on a byte boundary. An "N-bit prefix string 663 literal" begins with the same Huffman flag, followed by the length 664 encoded as an (N-1)-bit prefix integer. The prefix size, N, can have 665 a value between 2 and 8 inclusive. The remainder of the string 666 literal is unmodified. 668 A string literal without a prefix length noted is an 8-bit prefix 669 string literal and follows the definitions in [RFC7541] without 670 modification. 672 4.2. Encoder and Decoder Streams 674 QPACK defines two unidirectional stream types: 676 o An encoder stream is a unidirectional stream of type "0x02". It 677 carries an unframed sequence of encoder instructions from encoder 678 to decoder. 680 o A decoder stream is a unidirectional stream of type "0x03". It 681 carries an unframed sequence of decoder instructions from decoder 682 to encoder. 684 HTTP/3 endpoints contain a QPACK encoder and decoder. Each endpoint 685 MUST initiate at most one encoder stream and at most one decoder 686 stream. Receipt of a second instance of either stream type MUST be 687 treated as a connection error of type HTTP_STREAM_CREATION_ERROR. 688 These streams MUST NOT be closed. Closure of either unidirectional 689 stream type MUST be treated as a connection error of type 690 HTTP_CLOSED_CRITICAL_STREAM. 692 An endpoint MAY avoid creating an encoder stream if it's not going to 693 be used (for example if its encoder doesn't wish to use the dynamic 694 table, or if the maximum size of the dynamic table permitted by the 695 peer is zero). 697 An endpoint MAY avoid creating a decoder stream if its decoder sets 698 the maximum capacity of the dynamic table to zero. 700 An endpoint MUST allow its peer to create an encoder stream and a 701 decoder stream even if the connection's settings prevent their use. 703 4.3. Encoder Instructions 705 An encoder sends encoder instructions on the encoder stream to set 706 the capacity of the dynamic table and add dynamic table entries. 707 Instructions adding table entries can use existing entries to avoid 708 transmitting redundant information. The name can be transmitted as a 709 reference to an existing entry in the static or the dynamic table or 710 as a string literal. For entries which already exist in the dynamic 711 table, the full entry can also be used by reference, creating a 712 duplicate entry. 714 This section specifies the following encoder instructions. 716 4.3.1. Set Dynamic Table Capacity 718 An encoder informs the decoder of a change to the dynamic table 719 capacity using an instruction which begins with the '001' three-bit 720 pattern. This is followed by the new dynamic table capacity 721 represented as an integer with a 5-bit prefix (see Section 4.1.1). 723 0 1 2 3 4 5 6 7 724 +---+---+---+---+---+---+---+---+ 725 | 0 | 0 | 1 | Capacity (5+) | 726 +---+---+---+-------------------+ 728 Figure 2: Set Dynamic Table Capacity 730 The new capacity MUST be lower than or equal to the limit described 731 in Section 3.2.3. In HTTP/3, this limit is the value of the 732 SETTINGS_QPACK_MAX_TABLE_CAPACITY parameter (see Section 5) received 733 from the decoder. The decoder MUST treat a new dynamic table 734 capacity value that exceeds this limit as a connection error of type 735 "HTTP_QPACK_ENCODER_STREAM_ERROR". 737 Reducing the dynamic table capacity can cause entries to be evicted 738 (see Section 3.2.2). This MUST NOT cause the eviction of blocking 739 entries (see Section 2.1.2). Changing the capacity of the dynamic 740 table is not acknowledged as this instruction does not insert an 741 entry. 743 4.3.2. Insert With Name Reference 745 An encoder adds an entry to the dynamic table where the header field 746 name matches the header field name of an entry stored in the static 747 or the dynamic table using an instruction that starts with the '1' 748 one-bit pattern. The second ('T') bit indicates whether the 749 reference is to the static or dynamic table. The 6-bit prefix 750 integer (see Section 4.1.1) that follows is used to locate the table 751 entry for the header name. When T=1, the number represents the 752 static table index; when T=0, the number is the relative index of the 753 entry in the dynamic table. 755 The header name reference is followed by the header field value 756 represented as a string literal (see Section 4.1.2). 758 0 1 2 3 4 5 6 7 759 +---+---+---+---+---+---+---+---+ 760 | 1 | T | Name Index (6+) | 761 +---+---+-----------------------+ 762 | H | Value Length (7+) | 763 +---+---------------------------+ 764 | Value String (Length bytes) | 765 +-------------------------------+ 767 Insert Header Field -- Indexed Name 769 4.3.3. Insert Without Name Reference 771 An encoder adds an entry to the dynamic table where both the header 772 field name and the header field value are represented as string 773 literals using an instruction that starts with the '01' two-bit 774 pattern. 776 This is followed by the name represented as a 6-bit prefix string 777 literal, and the value represented as an 8-bit prefix string literal 778 (see Section 4.1.2). 780 0 1 2 3 4 5 6 7 781 +---+---+---+---+---+---+---+---+ 782 | 0 | 1 | H | Name Length (5+) | 783 +---+---+---+-------------------+ 784 | Name String (Length bytes) | 785 +---+---------------------------+ 786 | H | Value Length (7+) | 787 +---+---------------------------+ 788 | Value String (Length bytes) | 789 +-------------------------------+ 791 Insert Header Field -- New Name 793 4.3.4. Duplicate 795 An encoder duplicates an existing entry in the dynamic table using an 796 instruction that begins with the '000' three-bit pattern. This is 797 followed by the relative index of the existing entry represented as 798 an integer with a 5-bit prefix (see Section 4.1.1. 800 0 1 2 3 4 5 6 7 801 +---+---+---+---+---+---+---+---+ 802 | 0 | 0 | 0 | Index (5+) | 803 +---+---+---+-------------------+ 805 Figure 3: Duplicate 807 The existing entry is re-inserted into the dynamic table without 808 resending either the name or the value. This is useful to avoid 809 adding a reference to an older entry, which might block inserting new 810 entries. 812 4.4. Decoder Instructions 814 A decoder sends decoder instructions on the decoder stream to inform 815 the encoder about the processing of header blocks and table updates 816 to ensure consistency of the dynamic table. 818 This section specifies the following decoder instructions. 820 4.4.1. Header Acknowledgement 822 After processing a header block whose declared Required Insert Count 823 is not zero, the decoder emits a Header Acknowledgement instruction. 824 The instruction begins with the '1' one-bit pattern which is followed 825 by the header block's associated stream ID encoded as a 7-bit prefix 826 integer (see Section 4.1.1). 828 This instruction is used as described in Section 2.1.4 and in 829 Section 2.2.2. 831 0 1 2 3 4 5 6 7 832 +---+---+---+---+---+---+---+---+ 833 | 1 | Stream ID (7+) | 834 +---+---------------------------+ 836 Figure 4: Header Acknowledgement 838 If an encoder receives a Header Acknowledgement instruction referring 839 to a stream on which every header block with a non-zero Required 840 Insert Count has already been acknowledged, that MUST be treated as a 841 connection error of type "HTTP_QPACK_DECODER_STREAM_ERROR". 843 4.4.2. Stream Cancellation 845 When a stream is reset or reading is abandoned, the decoder emits a 846 Stream Cancellation instruction. The instruction begins with the 847 '01' two-bit pattern, which is followed by the stream ID of the 848 affected stream encoded as a 6-bit prefix integer. 850 This instruction is used as described in Section 2.2.2. 852 0 1 2 3 4 5 6 7 853 +---+---+---+---+---+---+---+---+ 854 | 0 | 1 | Stream ID (6+) | 855 +---+---+-----------------------+ 857 Figure 5: Stream Cancellation 859 4.4.3. Insert Count Increment 861 The Insert Count Increment instruction begins with the '00' two-bit 862 pattern, followed by the Increment encoded as a 6-bit prefix integer. 863 The value of the Increment is the total number of dynamic table 864 insertions and duplications processed by the decoder since the last 865 time it sent a Header Acknowledgement instruction that increased the 866 Known Received Count (see Section 2.1.4) or an Insert Count Increment 867 instruction. The encoder uses this value to update the Known 868 Received Count, as described in Section 2.2.2. 870 0 1 2 3 4 5 6 7 871 +---+---+---+---+---+---+---+---+ 872 | 0 | 0 | Increment (6+) | 873 +---+---+-----------------------+ 875 Figure 6: Insert Count Increment 877 An encoder that receives an Increment field equal to zero, or one 878 that increases the Known Received Count beyond what the encoder has 879 sent MUST treat this as a connection error of type 880 "HTTP_QPACK_DECODER_STREAM_ERROR". 882 4.5. Header Block Representations 884 A header block consists of a prefix and a possibly empty sequence of 885 representations defined in this section. Each representation 886 corresponds to a single header field. These representations 887 reference the static table or the dynamic table in a particular 888 state, but do not modify that state. 890 Header blocks are carried in frames on streams defined by the 891 enclosing protocol. 893 4.5.1. Header Block Prefix 895 Each header block is prefixed with two integers. The Required Insert 896 Count is encoded as an integer with an 8-bit prefix after the 897 encoding described in Section 4.5.1.1). The Base is encoded as a 898 sign bit ('S') and a Delta Base value with a 7-bit prefix (see 899 Section 4.5.1.2). 901 0 1 2 3 4 5 6 7 902 +---+---+---+---+---+---+---+---+ 903 | Required Insert Count (8+) | 904 +---+---------------------------+ 905 | S | Delta Base (7+) | 906 +---+---------------------------+ 907 | Compressed Headers ... 908 +-------------------------------+ 910 Figure 7: Header Block 912 4.5.1.1. Required Insert Count 914 Required Insert Count identifies the state of the dynamic table 915 needed to process the header block. Blocking decoders use the 916 Required Insert Count to determine when it is safe to process the 917 rest of the block. 919 The encoder transforms the Required Insert Count as follows before 920 encoding: 922 if ReqInsertCount == 0: 923 EncInsertCount = 0 924 else: 925 EncInsertCount = (ReqInsertCount mod (2 * MaxEntries)) + 1 927 Here "MaxEntries" is the maximum number of entries that the dynamic 928 table can have. The smallest entry has empty name and value strings 929 and has the size of 32. Hence "MaxEntries" is calculated as 931 MaxEntries = floor( MaxTableCapacity / 32 ) 933 "MaxTableCapacity" is the maximum capacity of the dynamic table as 934 specified by the decoder (see Section 3.2.3). 936 This encoding limits the length of the prefix on long-lived 937 connections. 939 The decoder can reconstruct the Required Insert Count using an 940 algorithm such as the following. If the decoder encounters a value 941 of EncodedInsertCount that could not have been produced by a 942 conformant encoder, it MUST treat this as a connection error of type 943 "HTTP_QPACK_DECOMPRESSION_FAILED". 945 TotalNumberOfInserts is the total number of inserts into the 946 decoder's dynamic table. 948 FullRange = 2 * MaxEntries 949 if EncodedInsertCount == 0: 950 ReqInsertCount = 0 951 else: 952 if EncodedInsertCount > FullRange: 953 Error 954 MaxValue = TotalNumberOfInserts + MaxEntries 956 # MaxWrapped is the largest possible value of 957 # ReqInsertCount that is 0 mod 2*MaxEntries 958 MaxWrapped = floor(MaxValue / FullRange) * FullRange 959 ReqInsertCount = MaxWrapped + EncodedInsertCount - 1 961 # If ReqInsertCount exceeds MaxValue, the Encoder's value 962 # must have wrapped one fewer time 963 if ReqInsertCount > MaxValue: 964 if ReqInsertCount <= FullRange: 965 Error 966 ReqInsertCount -= FullRange 968 # Value of 0 must be encoded as 0. 969 if ReqInsertCount == 0: 970 Error 972 For example, if the dynamic table is 100 bytes, then the Required 973 Insert Count will be encoded modulo 6. If a decoder has received 10 974 inserts, then an encoded value of 3 indicates that the Required 975 Insert Count is 9 for the header block. 977 4.5.1.2. Base 979 The "Base" is used to resolve references in the dynamic table as 980 described in Section 3.2.5. 982 To save space, the Base is encoded relative to the Required Insert 983 Count using a one-bit sign ('S') and the "Delta Base" value. A sign 984 bit of 0 indicates that the Base is greater than or equal to the 985 value of the Required Insert Count; the decoder adds the value of 986 Delta Base to the Required Insert Count to determine the value of the 987 Base. A sign bit of 1 indicates that the Base is less than the 988 Required Insert Count; the decoder subtracts the value of Delta Base 989 from the Required Insert Count and also subtracts one to determine 990 the value of the Base. That is: 992 if S == 0: 993 Base = ReqInsertCount + DeltaBase 994 else: 995 Base = ReqInsertCount - DeltaBase - 1 997 A single-pass encoder determines the Base before encoding a header 998 block. If the encoder inserted entries in the dynamic table while 999 encoding the header block, Required Insert Count will be greater than 1000 the Base, so the encoded difference is negative and the sign bit is 1001 set to 1. If the header block did not reference the most recent 1002 entry in the table and did not insert any new entries, the Base will 1003 be greater than the Required Insert Count, so the delta will be 1004 positive and the sign bit is set to 0. 1006 An encoder that produces table updates before encoding a header block 1007 might set Base to the value of Required Insert Count. In such case, 1008 both the sign bit and the Delta Base will be set to zero. 1010 A header block that does not reference the dynamic table can use any 1011 value for the Base; setting Delta Base to zero is one of the most 1012 efficient encodings. 1014 For example, with a Required Insert Count of 9, a decoder receives an 1015 S bit of 1 and a Delta Base of 2. This sets the Base to 6 and 1016 enables post-base indexing for three entries. In this example, a 1017 relative index of 1 refers to the 5th entry that was added to the 1018 table; a post-base index of 1 refers to the 8th entry. 1020 4.5.2. Indexed Header Field 1022 An indexed header field representation identifies an entry in the 1023 static table, or an entry in the dynamic table with an absolute index 1024 less than the Base. 1026 0 1 2 3 4 5 6 7 1027 +---+---+---+---+---+---+---+---+ 1028 | 1 | T | Index (6+) | 1029 +---+---+-----------------------+ 1031 Indexed Header Field 1033 This representation starts with the '1' 1-bit pattern, followed by 1034 the 'T' bit indicating whether the reference is into the static or 1035 dynamic table. The 6-bit prefix integer (see Section 4.1.1) that 1036 follows is used to locate the table entry for the header field. When 1037 T=1, the number represents the static table index; when T=0, the 1038 number is the relative index of the entry in the dynamic table. 1040 4.5.3. Indexed Header Field With Post-Base Index 1042 An indexed header field with post-base index representation 1043 identifies an entry in the dynamic table with an absolute index 1044 greater than or equal to the Base. 1046 0 1 2 3 4 5 6 7 1047 +---+---+---+---+---+---+---+---+ 1048 | 0 | 0 | 0 | 1 | Index (4+) | 1049 +---+---+---+---+---------------+ 1051 Indexed Header Field with Post-Base Index 1053 This representation starts with the '0001' 4-bit pattern. This is 1054 followed by the post-base index (see Section 3.2.6) of the matching 1055 header field, represented as an integer with a 4-bit prefix (see 1056 Section 4.1.1). 1058 4.5.4. Literal Header Field With Name Reference 1060 A literal header field with name reference representation encodes a 1061 header field where the header field name matches the header field 1062 name of an entry in the static table, or the header field name of an 1063 entry in the dynamic table with an absolute index less than the Base. 1065 0 1 2 3 4 5 6 7 1066 +---+---+---+---+---+---+---+---+ 1067 | 0 | 1 | N | T |Name Index (4+)| 1068 +---+---+---+---+---------------+ 1069 | H | Value Length (7+) | 1070 +---+---------------------------+ 1071 | Value String (Length bytes) | 1072 +-------------------------------+ 1074 Literal Header Field With Name Reference 1076 This representation starts with the '01' two-bit pattern. The 1077 following bit, 'N', indicates whether an intermediary is permitted to 1078 add this header to the dynamic header table on subsequent hops. When 1079 the 'N' bit is set, the encoded header MUST always be encoded with a 1080 literal representation. In particular, when a peer sends a header 1081 field that it received represented as a literal header field with the 1082 'N' bit set, it MUST use a literal representation to forward this 1083 header field. This bit is intended for protecting header field 1084 values that are not to be put at risk by compressing them (see 1085 Section 7 for more details). 1087 The fourth ('T') bit indicates whether the reference is to the static 1088 or dynamic table. The 4-bit prefix integer (see Section 4.1.1) that 1089 follows is used to locate the table entry for the header name. When 1090 T=1, the number represents the static table index; when T=0, the 1091 number is the relative index of the entry in the dynamic table. 1093 Only the header field name is taken from the dynamic table entry; the 1094 header field value is encoded as an 8-bit prefix string literal (see 1095 Section 4.1.2). 1097 4.5.5. Literal Header Field With Post-Base Name Reference 1099 A literal header field with post-base name reference representation 1100 encodes a header field where the header field name matches the header 1101 field name of a dynamic table entry with an absolute index greater 1102 than or equal to the Base. 1104 0 1 2 3 4 5 6 7 1105 +---+---+---+---+---+---+---+---+ 1106 | 0 | 0 | 0 | 0 | N |NameIdx(3+)| 1107 +---+---+---+---+---+-----------+ 1108 | H | Value Length (7+) | 1109 +---+---------------------------+ 1110 | Value String (Length bytes) | 1111 +-------------------------------+ 1113 Literal Header Field With Post-Base Name Reference 1115 This representation starts with the '0000' four-bit pattern. The 1116 fifth bit is the 'N' bit as described in Section 4.5.4. This is 1117 followed by a post-base index of the dynamic table entry (see 1118 Section 3.2.6) encoded as an integer with a 3-bit prefix (see 1119 Section 4.1.1). 1121 Only the header field name is taken from the dynamic table entry; the 1122 header field value is encoded as an 8-bit prefix string literal (see 1123 Section 4.1.2). 1125 4.5.6. Literal Header Field Without Name Reference 1127 The literal header field without name reference representation 1128 encodes a header field name and a header field value as string 1129 literals. 1131 0 1 2 3 4 5 6 7 1132 +---+---+---+---+---+---+---+---+ 1133 | 0 | 0 | 1 | N | H |NameLen(3+)| 1134 +---+---+---+---+---+-----------+ 1135 | Name String (Length bytes) | 1136 +---+---------------------------+ 1137 | H | Value Length (7+) | 1138 +---+---------------------------+ 1139 | Value String (Length bytes) | 1140 +-------------------------------+ 1142 Literal Header Field Without Name Reference 1144 This representation begins with the '001' three-bit pattern. The 1145 fourth bit is the 'N' bit as described in Section 4.5.4. The name 1146 follows, represented as a 4-bit prefix string literal, then the 1147 value, represented as an 8-bit prefix string literal (see 1148 Section 4.1.2). 1150 5. Configuration 1152 QPACK defines two settings which are included in the HTTP/3 SETTINGS 1153 frame. 1155 SETTINGS_QPACK_MAX_TABLE_CAPACITY (0x1): The default value is zero. 1156 See Section 3.2 for usage. This is the equivalent of the 1157 SETTINGS_HEADER_TABLE_SIZE from HTTP/2. 1159 SETTINGS_QPACK_BLOCKED_STREAMS (0x7): The default value is zero. 1160 See Section 2.1.3. 1162 6. Error Handling 1164 The following error codes are defined for HTTP/3 to indicate failures 1165 of QPACK which prevent the connection from continuing: 1167 HTTP_QPACK_DECOMPRESSION_FAILED (0x200): The decoder failed to 1168 interpret a header block and is not able to continue decoding that 1169 header block. 1171 HTTP_QPACK_ENCODER_STREAM_ERROR (0x201): The decoder failed to 1172 interpret an encoder instruction received on the encoder stream. 1174 HTTP_QPACK_DECODER_STREAM_ERROR (0x202): The encoder failed to 1175 interpret a decoder instruction received on the decoder stream. 1177 7. Security Considerations 1179 TBD. Also see Section 7.1 of [RFC7541]. 1181 While the negotiated limit on the dynamic table size accounts for 1182 much of the memory that can be consumed by a QPACK implementation, 1183 data which cannot be immediately sent due to flow control is not 1184 affected by this limit. Implementations should limit the size of 1185 unsent data, especially on the decoder stream where flexibility to 1186 choose what to send is limited. Possible responses to an excess of 1187 unsent data might include limiting the ability of the peer to open 1188 new streams, reading only from the encoder stream, or closing the 1189 connection. 1191 8. IANA Considerations 1193 8.1. Settings Registration 1195 This document specifies two settings. The entries in the following 1196 table are registered in the "HTTP/3 Settings" registry established in 1197 [HTTP3]. 1199 +--------------------------+------+---------------+---------+ 1200 | Setting Name | Code | Specification | Default | 1201 +--------------------------+------+---------------+---------+ 1202 | QPACK_MAX_TABLE_CAPACITY | 0x1 | Section 5 | 0 | 1203 | | | | | 1204 | QPACK_BLOCKED_STREAMS | 0x7 | Section 5 | 0 | 1205 +--------------------------+------+---------------+---------+ 1207 8.2. Stream Type Registration 1209 This document specifies two stream types. The entries in the 1210 following table are registered in the "HTTP/3 Stream Type" registry 1211 established in [HTTP3]. 1213 +----------------------+------+---------------+--------+ 1214 | Stream Type | Code | Specification | Sender | 1215 +----------------------+------+---------------+--------+ 1216 | QPACK Encoder Stream | 0x02 | Section 4.2 | Both | 1217 | | | | | 1218 | QPACK Decoder Stream | 0x03 | Section 4.2 | Both | 1219 +----------------------+------+---------------+--------+ 1221 8.3. Error Code Registration 1223 This document specifies three error codes. The entries in the 1224 following table are registered in the "HTTP/3 Error Code" registry 1225 established in [HTTP3]. 1227 +-----------------------------+-------+--------------+--------------+ 1228 | Name | Code | Description | Specificatio | 1229 | | | | n | 1230 +-----------------------------+-------+--------------+--------------+ 1231 | HTTP_QPACK_DECOMPRESSION_FA | 0x200 | Decompressio | Section 6 | 1232 | ILED | | n of a | | 1233 | | | header block | | 1234 | | | failed | | 1235 | | | | | 1236 | HTTP_QPACK_ENCODER_STREAM_E | 0x201 | Error on the | Section 6 | 1237 | RROR | | encoder | | 1238 | | | stream | | 1239 | | | | | 1240 | HTTP_QPACK_DECODER_STREAM_E | 0x202 | Error on the | Section 6 | 1241 | RROR | | decoder | | 1242 | | | stream | | 1243 +-----------------------------+-------+--------------+--------------+ 1245 9. References 1247 9.1. Normative References 1249 [HTTP3] Bishop, M., Ed., "Hypertext Transfer Protocol Version 3 1250 (HTTP/3)", draft-ietf-quic-http-24 (work in progress), 1251 November 2019. 1253 [QUIC-TRANSPORT] 1254 Iyengar, J., Ed. and M. Thomson, Ed., "QUIC: A UDP-Based 1255 Multiplexed and Secure Transport", draft-ietf-quic- 1256 transport-24 (work in progress), November 2019. 1258 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1259 Requirement Levels", BCP 14, RFC 2119, 1260 DOI 10.17487/RFC2119, March 1997, 1261 . 1263 [RFC7541] Peon, R. and H. Ruellan, "HPACK: Header Compression for 1264 HTTP/2", RFC 7541, DOI 10.17487/RFC7541, May 2015, 1265 . 1267 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 1268 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 1269 May 2017, . 1271 9.2. Informative References 1273 [RFC2360] Scott, G., "Guide for Internet Standards Writers", BCP 22, 1274 RFC 2360, DOI 10.17487/RFC2360, June 1998, 1275 . 1277 [RFC7540] Belshe, M., Peon, R., and M. Thomson, Ed., "Hypertext 1278 Transfer Protocol Version 2 (HTTP/2)", RFC 7540, 1279 DOI 10.17487/RFC7540, May 2015, 1280 . 1282 9.3. URIs 1284 [1] https://mailarchive.ietf.org/arch/search/?email_list=quic 1286 [2] https://github.com/quicwg 1288 [3] https://github.com/quicwg/base-drafts/labels/-qpack 1290 Appendix A. Static Table 1292 +------+-----------------------------+------------------------------+ 1293 | Inde | Name | Value | 1294 | x | | | 1295 +------+-----------------------------+------------------------------+ 1296 | 0 | :authority | | 1297 | | | | 1298 | 1 | :path | / | 1299 | | | | 1300 | 2 | age | 0 | 1301 | | | | 1302 | 3 | content-disposition | | 1303 | | | | 1304 | 4 | content-length | 0 | 1305 | | | | 1306 | 5 | cookie | | 1307 | | | | 1308 | 6 | date | | 1309 | | | | 1310 | 7 | etag | | 1311 | | | | 1312 | 8 | if-modified-since | | 1313 | | | | 1314 | 9 | if-none-match | | 1315 | | | | 1316 | 10 | last-modified | | 1317 | | | | 1318 | 11 | link | | 1319 | | | | 1320 | 12 | location | | 1321 | | | | 1322 | 13 | referer | | 1323 | | | | 1324 | 14 | set-cookie | | 1325 | | | | 1326 | 15 | :method | CONNECT | 1327 | | | | 1328 | 16 | :method | DELETE | 1329 | | | | 1330 | 17 | :method | GET | 1331 | | | | 1332 | 18 | :method | HEAD | 1333 | | | | 1334 | 19 | :method | OPTIONS | 1335 | | | | 1336 | 20 | :method | POST | 1337 | | | | 1338 | 21 | :method | PUT | 1339 | | | | 1340 | 22 | :scheme | http | 1341 | | | | 1342 | 23 | :scheme | https | 1343 | | | | 1344 | 24 | :status | 103 | 1345 | | | | 1346 | 25 | :status | 200 | 1347 | | | | 1348 | 26 | :status | 304 | 1349 | | | | 1350 | 27 | :status | 404 | 1351 | | | | 1352 | 28 | :status | 503 | 1353 | | | | 1354 | 29 | accept | */* | 1355 | | | | 1356 | 30 | accept | application/dns-message | 1357 | | | | 1358 | 31 | accept-encoding | gzip, deflate, br | 1359 | | | | 1360 | 32 | accept-ranges | bytes | 1361 | | | | 1362 | 33 | access-control-allow- | cache-control | 1363 | | headers | | 1364 | | | | 1365 | 34 | access-control-allow- | content-type | 1366 | | headers | | 1367 | | | | 1368 | 35 | access-control-allow-origin | * | 1369 | | | | 1370 | 36 | cache-control | max-age=0 | 1371 | | | | 1372 | 37 | cache-control | max-age=2592000 | 1373 | | | | 1374 | 38 | cache-control | max-age=604800 | 1375 | | | | 1376 | 39 | cache-control | no-cache | 1377 | | | | 1378 | 40 | cache-control | no-store | 1379 | | | | 1380 | 41 | cache-control | public, max-age=31536000 | 1381 | | | | 1382 | 42 | content-encoding | br | 1383 | | | | 1384 | 43 | content-encoding | gzip | 1385 | | | | 1386 | 44 | content-type | application/dns-message | 1387 | | | | 1388 | 45 | content-type | application/javascript | 1389 | | | | 1390 | 46 | content-type | application/json | 1391 | | | | 1392 | 47 | content-type | application/x-www-form- | 1393 | | | urlencoded | 1394 | | | | 1395 | 48 | content-type | image/gif | 1396 | | | | 1397 | 49 | content-type | image/jpeg | 1398 | | | | 1399 | 50 | content-type | image/png | 1400 | | | | 1401 | 51 | content-type | text/css | 1402 | | | | 1403 | 52 | content-type | text/html; charset=utf-8 | 1404 | | | | 1405 | 53 | content-type | text/plain | 1406 | | | | 1407 | 54 | content-type | text/plain;charset=utf-8 | 1408 | | | | 1409 | 55 | range | bytes=0- | 1410 | | | | 1411 | 56 | strict-transport-security | max-age=31536000 | 1412 | | | | 1413 | 57 | strict-transport-security | max-age=31536000; | 1414 | | | includesubdomains | 1415 | | | | 1416 | 58 | strict-transport-security | max-age=31536000; | 1417 | | | includesubdomains; preload | 1418 | | | | 1419 | 59 | vary | accept-encoding | 1420 | | | | 1421 | 60 | vary | origin | 1422 | | | | 1423 | 61 | x-content-type-options | nosniff | 1424 | | | | 1425 | 62 | x-xss-protection | 1; mode=block | 1426 | | | | 1427 | 63 | :status | 100 | 1428 | | | | 1429 | 64 | :status | 204 | 1430 | | | | 1431 | 65 | :status | 206 | 1432 | | | | 1433 | 66 | :status | 302 | 1434 | | | | 1435 | 67 | :status | 400 | 1436 | | | | 1437 | 68 | :status | 403 | 1438 | | | | 1439 | 69 | :status | 421 | 1440 | | | | 1441 | 70 | :status | 425 | 1442 | | | | 1443 | 71 | :status | 500 | 1444 | | | | 1445 | 72 | accept-language | | 1446 | | | | 1447 | 73 | access-control-allow- | FALSE | 1448 | | credentials | | 1449 | | | | 1450 | 74 | access-control-allow- | TRUE | 1451 | | credentials | | 1452 | | | | 1453 | 75 | access-control-allow- | * | 1454 | | headers | | 1455 | | | | 1456 | 76 | access-control-allow- | get | 1457 | | methods | | 1458 | | | | 1459 | 77 | access-control-allow- | get, post, options | 1460 | | methods | | 1461 | | | | 1462 | 78 | access-control-allow- | options | 1463 | | methods | | 1464 | | | | 1465 | 79 | access-control-expose- | content-length | 1466 | | headers | | 1467 | | | | 1468 | 80 | access-control-request- | content-type | 1469 | | headers | | 1470 | | | | 1471 | 81 | access-control-request- | get | 1472 | | method | | 1473 | | | | 1474 | 82 | access-control-request- | post | 1475 | | method | | 1476 | | | | 1477 | 83 | alt-svc | clear | 1478 | | | | 1479 | 84 | authorization | | 1480 | | | | 1481 | 85 | content-security-policy | script-src 'none'; object- | 1482 | | | src 'none'; base-uri 'none' | 1483 | | | | 1484 | 86 | early-data | 1 | 1485 | | | | 1486 | 87 | expect-ct | | 1487 | | | | 1488 | 88 | forwarded | | 1489 | | | | 1490 | 89 | if-range | | 1491 | | | | 1492 | 90 | origin | | 1493 | | | | 1494 | 91 | purpose | prefetch | 1495 | | | | 1496 | 92 | server | | 1497 | | | | 1498 | 93 | timing-allow-origin | * | 1499 | | | | 1500 | 94 | upgrade-insecure-requests | 1 | 1501 | | | | 1502 | 95 | user-agent | | 1503 | | | | 1504 | 96 | x-forwarded-for | | 1505 | | | | 1506 | 97 | x-frame-options | deny | 1507 | | | | 1508 | 98 | x-frame-options | sameorigin | 1509 +------+-----------------------------+------------------------------+ 1511 Appendix B. Sample One Pass Encoding Algorithm 1513 Pseudo-code for single pass encoding, excluding handling of 1514 duplicates, non-blocking mode, and reference tracking. 1516 baseIndex = dynamicTable.baseIndex 1517 largestReference = 0 1518 for header in headers: 1519 staticIdx = staticTable.getIndex(header) 1520 if staticIdx: 1521 encodeIndexReference(streamBuffer, staticIdx) 1522 continue 1524 dynamicIdx = dynamicTable.getIndex(header) 1525 if !dynamicIdx: 1526 # No matching entry. Either insert+index or encode literal 1527 nameIdx = getNameIndex(header) 1528 if shouldIndex(header) and dynamicTable.canIndex(header): 1529 encodeLiteralWithIncrementalIndex(controlBuffer, nameIdx, 1530 header) 1531 dynamicTable.add(header) 1532 dynamicIdx = dynamicTable.baseIndex 1534 if !dynamicIdx: 1535 # Couldn't index it, literal 1536 if nameIdx <= staticTable.size: 1537 encodeLiteral(streamBuffer, nameIndex, header) 1538 else: 1539 # encode literal, possibly with nameIdx above baseIndex 1540 encodeDynamicLiteral(streamBuffer, nameIndex, baseIndex, 1541 header) 1542 largestReference = max(largestReference, 1543 dynamicTable.toAbsolute(nameIdx)) 1544 else: 1545 # Dynamic index reference 1546 assert(dynamicIdx) 1547 largestReference = max(largestReference, dynamicIdx) 1548 # Encode dynamicIdx, possibly with dynamicIdx above baseIndex 1549 encodeDynamicIndexReference(streamBuffer, dynamicIdx, 1550 baseIndex) 1552 # encode the prefix 1553 encodeInteger(prefixBuffer, 0x00, largestReference, 8) 1554 if baseIndex >= largestReference: 1555 encodeInteger(prefixBuffer, 0, baseIndex - largestReference, 7) 1556 else: 1557 encodeInteger(prefixBuffer, 0x80, 1558 largestReference - baseIndex, 7) 1560 return controlBuffer, prefixBuffer + streamBuffer 1562 Appendix C. Change Log 1564 *RFC Editor's Note:* Please remove this section prior to 1565 publication of a final version of this document. 1567 C.1. Since draft-ietf-quic-qpack-10 1569 Editorial changes 1571 C.2. Since draft-ietf-quic-qpack-09 1573 o Decoders MUST emit Header Acknowledgements (#2939) 1575 o Updated error code for multiple encoder or decoder streams (#2970) 1577 o Added explicit defaults for new SETTINGS (#2974) 1579 C.3. Since draft-ietf-quic-qpack-08 1581 o Endpoints are permitted to create encoder and decoder streams even 1582 if they can't use them (#2100, #2529) 1584 o Maximum values for settings removed (#2766, #2767) 1586 C.4. Since draft-ietf-quic-qpack-06 1588 o Clarify initial dynamic table capacity maximums (#2276, #2330, 1589 #2330) 1591 C.5. Since draft-ietf-quic-qpack-05 1593 o Introduced the terms dynamic table capacity and maximum dynamic 1594 table capacity. 1596 o Renamed SETTINGS_HEADER_TABLE_SIZE to 1597 SETTINGS_QPACK_MAX_TABLE_CAPACITY. 1599 C.6. Since draft-ietf-quic-qpack-04 1601 o Changed calculation of Delta Base Index to avoid an illegal value 1602 (#2002, #2005) 1604 C.7. Since draft-ietf-quic-qpack-03 1606 o Change HTTP settings defaults (#2038) 1608 o Substantial editorial reorganization 1610 C.8. Since draft-ietf-quic-qpack-02 1612 o Largest Reference encoded modulo MaxEntries (#1763) 1614 o New Static Table (#1355) 1616 o Table Size Update with Insert Count=0 is a connection error 1617 (#1762) 1619 o Stream Cancellations are optional when 1620 SETTINGS_HEADER_TABLE_SIZE=0 (#1761) 1622 o Implementations must handle 62 bit integers (#1760) 1624 o Different error types for each QPACK stream, other changes to 1625 error handling (#1726) 1627 o Preserve header field order (#1725) 1629 o Initial table size is the maximum permitted when table is first 1630 usable (#1642) 1632 C.9. Since draft-ietf-quic-qpack-01 1634 o Only header blocks that reference the dynamic table are 1635 acknowledged (#1603, #1605) 1637 C.10. Since draft-ietf-quic-qpack-00 1639 o Renumbered instructions for consistency (#1471, #1472) 1641 o Decoder is allowed to validate largest reference (#1404, #1469) 1643 o Header block acknowledgments also acknowledge the associated 1644 largest reference (#1370, #1400) 1646 o Added an acknowledgment for unread streams (#1371, #1400) 1648 o Removed framing from encoder stream (#1361,#1467) 1650 o Control streams use typed unidirectional streams rather than fixed 1651 stream IDs (#910,#1359) 1653 C.11. Since draft-ietf-quic-qcram-00 1655 o Separate instruction sets for table updates and header blocks 1656 (#1235, #1142, #1141) 1658 o Reworked indexing scheme (#1176, #1145, #1136, #1130, #1125, 1659 #1314) 1661 o Added mechanisms that support one-pass encoding (#1138, #1320) 1663 o Added a setting to control the number of blocked decoders (#238, 1664 #1140, #1143) 1666 o Moved table updates and acknowledgments to dedicated streams 1667 (#1121, #1122, #1238) 1669 Acknowledgments 1671 This draft draws heavily on the text of [RFC7541]. The indirect 1672 input of those authors is gratefully acknowledged, as well as ideas 1673 from: 1675 o Ryan Hamilton 1677 o Patrick McManus 1679 o Kazuho Oku 1681 o Biren Roy 1683 o Ian Swett 1685 o Dmitri Tikhonov 1687 Buck's contribution was supported by Google during his employment 1688 there. 1690 A substantial portion of Mike's contribution was supported by 1691 Microsoft during his employment there. 1693 Authors' Addresses 1695 Charles 'Buck' Krasic 1696 Netflix 1698 Email: ckrasic@netflix.com 1700 Mike Bishop 1701 Akamai Technologies 1703 Email: mbishop@evequefou.be 1704 Alan Frindell (editor) 1705 Facebook 1707 Email: afrind@fb.com