idnits 2.17.1 draft-ietf-quic-qpack-07.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.4). -- The document date (March 11, 2019) is 1871 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 1277 -- Looks like a reference, but probably isn't: '2' on line 1279 -- Looks like a reference, but probably isn't: '3' on line 1281 == Outdated reference: A later version (-34) exists of draft-ietf-quic-http-19 == Outdated reference: A later version (-34) exists of draft-ietf-quic-transport-18 -- 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: September 12, 2019 Akamai Technologies 6 A. Frindell, Ed. 7 Facebook 8 March 11, 2019 10 QPACK: Header Compression for HTTP over QUIC 11 draft-ietf-quic-qpack-07 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 September 12, 2019. 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 . . . . . . . . . . . . . . . . . 5 67 2. Compression Process Overview . . . . . . . . . . . . . . . . 5 68 2.1. Encoder . . . . . . . . . . . . . . . . . . . . . . . . . 5 69 2.1.1. Reference Tracking . . . . . . . . . . . . . . . . . 6 70 2.1.2. Blocked Dynamic Table Insertions . . . . . . . . . . 6 71 2.1.3. Avoiding Head-of-Line Blocking . . . . . . . . . . . 7 72 2.1.4. Known Received Count . . . . . . . . . . . . . . . . 8 73 2.2. Decoder . . . . . . . . . . . . . . . . . . . . . . . . . 8 74 2.2.1. State Synchronization . . . . . . . . . . . . . . . . 9 75 2.2.2. Blocked Decoding . . . . . . . . . . . . . . . . . . 9 76 3. Header Tables . . . . . . . . . . . . . . . . . . . . . . . . 9 77 3.1. Static Table . . . . . . . . . . . . . . . . . . . . . . 9 78 3.2. Dynamic Table . . . . . . . . . . . . . . . . . . . . . . 10 79 3.2.1. Dynamic Table Size . . . . . . . . . . . . . . . . . 10 80 3.2.2. Dynamic Table Capacity and Eviction . . . . . . . . . 10 81 3.2.3. Maximum Dynamic Table Capacity . . . . . . . . . . . 11 82 3.2.4. Absolute Indexing . . . . . . . . . . . . . . . . . . 12 83 3.2.5. Relative Indexing . . . . . . . . . . . . . . . . . . 12 84 3.2.6. Post-Base Indexing . . . . . . . . . . . . . . . . . 13 85 3.2.7. Invalid References . . . . . . . . . . . . . . . . . 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. Instructions . . . . . . . . . . . . . . . . . . . . . . 14 91 4.2.1. Encoder and Decoder Streams . . . . . . . . . . . . . 15 92 4.3. Encoder Instructions . . . . . . . . . . . . . . . . . . 15 93 4.3.1. Insert With Name Reference . . . . . . . . . . . . . 15 94 4.3.2. Insert Without Name Reference . . . . . . . . . . . . 16 95 4.3.3. Duplicate . . . . . . . . . . . . . . . . . . . . . . 16 96 4.3.4. Set Dynamic Table Capacity . . . . . . . . . . . . . 17 97 4.4. Decoder Instructions . . . . . . . . . . . . . . . . . . 17 98 4.4.1. Insert Count Increment . . . . . . . . . . . . . . . 17 99 4.4.2. Header Acknowledgement . . . . . . . . . . . . . . . 18 100 4.4.3. Stream Cancellation . . . . . . . . . . . . . . . . . 19 101 4.5. Header Block Instructions . . . . . . . . . . . . . . . . 19 102 4.5.1. Header Block Prefix . . . . . . . . . . . . . . . . . 20 103 4.5.2. Indexed Header Field . . . . . . . . . . . . . . . . 22 104 4.5.3. Indexed Header Field With Post-Base Index . . . . . . 23 105 4.5.4. Literal Header Field With Name Reference . . . . . . 23 106 4.5.5. Literal Header Field With Post-Base Name Reference . 24 107 4.5.6. Literal Header Field Without Name Reference . . . . . 24 108 5. Configuration . . . . . . . . . . . . . . . . . . . . . . . . 25 109 6. Error Handling . . . . . . . . . . . . . . . . . . . . . . . 25 110 7. Security Considerations . . . . . . . . . . . . . . . . . . . 26 111 8. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 26 112 8.1. Settings Registration . . . . . . . . . . . . . . . . . . 26 113 8.2. Stream Type Registration . . . . . . . . . . . . . . . . 26 114 8.3. Error Code Registration . . . . . . . . . . . . . . . . . 26 115 9. References . . . . . . . . . . . . . . . . . . . . . . . . . 27 116 9.1. Normative References . . . . . . . . . . . . . . . . . . 27 117 9.2. Informative References . . . . . . . . . . . . . . . . . 28 118 9.3. URIs . . . . . . . . . . . . . . . . . . . . . . . . . . 28 119 Appendix A. Static Table . . . . . . . . . . . . . . . . . . . . 28 120 Appendix B. Sample One Pass Encoding Algorithm . . . . . . . . . 33 121 Appendix C. Change Log . . . . . . . . . . . . . . . . . . . . . 35 122 C.1. Since draft-ietf-quic-qpack-06 . . . . . . . . . . . . . 35 123 C.2. Since draft-ietf-quic-qpack-05 . . . . . . . . . . . . . 35 124 C.3. Since draft-ietf-quic-qpack-04 . . . . . . . . . . . . . 35 125 C.4. Since draft-ietf-quic-qpack-03 . . . . . . . . . . . . . 35 126 C.5. Since draft-ietf-quic-qpack-02 . . . . . . . . . . . . . 35 127 C.6. Since draft-ietf-quic-qpack-01 . . . . . . . . . . . . . 36 128 C.7. Since draft-ietf-quic-qpack-00 . . . . . . . . . . . . . 36 129 C.8. Since draft-ietf-quic-qcram-00 . . . . . . . . . . . . . 36 130 Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . . . 36 131 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 37 133 1. Introduction 135 The QUIC transport protocol was designed from the outset to support 136 HTTP semantics, and its design subsumes many of the features of 137 HTTP/2. HTTP/2 uses HPACK ([RFC7541]) for header compression, but 138 QUIC's stream multiplexing comes into some conflict with HPACK. A 139 key goal of the design of QUIC is to improve stream multiplexing 140 relative to HTTP/2 by reducing head-of-line blocking. If HPACK were 141 used for HTTP/3, it would induce head-of-line blocking due to built- 142 in assumptions of a total ordering across frames on all streams. 144 QUIC is described in [QUIC-TRANSPORT]. The HTTP/3 mapping is 145 described in [HTTP3]. For a full description of HTTP/2, see 146 [RFC7540]. The description of HPACK is [RFC7541]. 148 QPACK reuses core concepts from HPACK, but is redesigned to allow 149 correctness in the presence of out-of-order delivery, with 150 flexibility for implementations to balance between resilience against 151 head-of-line blocking and optimal compression ratio. The design 152 goals are to closely approach the compression ratio of HPACK with 153 substantially less head-of-line blocking under the same loss 154 conditions. 156 1.1. Conventions and Definitions 158 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 159 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 160 "OPTIONAL" in this document are to be interpreted as described in BCP 161 14 [RFC2119] [RFC8174] when, and only when, they appear in all 162 capitals, as shown here. 164 Definitions of terms that are used in this document: 166 Header field: A name-value pair sent as part of an HTTP message. 168 Header list: An ordered collection of header fields associated with 169 an HTTP message. A header list can contain multiple header fields 170 with the same name. It can also contain duplicate header fields. 172 Header block: The compressed representation of a header list. 174 Encoder: An implementation which transforms a header list into a 175 header block. 177 Decoder: An implementation which transforms a header block into a 178 header list. 180 Absolute Index: A unique index for each entry in the dynamic table. 182 Base: A reference point for relative indicies. Dynamic references 183 are made relative to a Base in header blocks. 185 Insert Count: The total number of entries inserted in the dynamic 186 table. 188 QPACK is a name, not an acronym. 190 1.2. Notational Conventions 192 Diagrams use the format described in Section 3.1 of [RFC2360], with 193 the following additional conventions: 195 x (A) Indicates that x is A bits long 197 x (A+) Indicates that x uses the prefixed integer encoding defined 198 in Section 5.1 of [RFC7541], beginning with an A-bit prefix. 200 x ... Indicates that x is variable-length and extends to the end of 201 the region. 203 2. Compression Process Overview 205 Like HPACK, QPACK uses two tables for associating header fields to 206 indices. The static table (see Section 3.1) is predefined and 207 contains common header fields (some of them with an empty value). 208 The dynamic table (see Section 3.2) is built up over the course of 209 the connection and can be used by the encoder to index header fields 210 in the encoded header lists. 212 QPACK instructions appear in three different types of streams: 214 o The encoder uses a unidirectional stream to modify the state of 215 the dynamic table without emitting header fields associated with 216 any particular request. 218 o HEADERS and PUSH_PROMISE frames on request and push streams 219 reference the table state without modifying it. 221 o The decoder sends feedback to the encoder on a unidirectional 222 stream. This feedback enables the encoder to manage dynamic table 223 state. 225 2.1. Encoder 227 An encoder compresses a header list by emitting either an indexed or 228 a literal representation for each header field in the list. 229 References to the static table and literal representations do not 230 require any dynamic state and never risk head-of-line blocking. 231 References to the dynamic table risk head-of-line blocking if the 232 encoder has not received an acknowledgement indicating the entry is 233 available at the decoder. 235 An encoder MAY insert any entry in the dynamic table it chooses; it 236 is not limited to header fields it is compressing. 238 QPACK preserves the ordering of header fields within each header 239 list. An encoder MUST emit header field representations in the order 240 they appear in the input header list. 242 QPACK is designed to contain the more complex state tracking to the 243 encoder, while the decoder is relatively simple. 245 2.1.1. Reference Tracking 247 An encoder MUST ensure that a header block which references a dynamic 248 table entry is not received by the decoder after the referenced entry 249 has been evicted. Hence the encoder needs to track information about 250 each compressed header block that references the dynamic table until 251 that header block is acknowledged by the decoder. 253 2.1.2. Blocked Dynamic Table Insertions 255 A dynamic table entry is considered blocking and cannot be evicted 256 until its insertion has been acknowledged and there are no 257 outstanding unacknowledged references to the entry. In particular, a 258 dynamic table entry that has never been referenced can still be 259 blocking. 261 Note: A blocking entry is unrelated to a blocked stream, which is a 262 stream that a decoder cannot decode as a result of references to 263 entries that are not yet available. Any encoder that uses the 264 dynamic table has to keep track of blocked entries, whereas 265 blocked streams are optional. 267 An encoder MUST NOT insert an entry into the dynamic table (or 268 duplicate an existing entry) if doing so would evict a blocking 269 entry. In this case, the encoder can send literal representations of 270 header fields. 272 To ensure that the encoder is not prevented from adding new entries, 273 the encoder can avoid referencing entries that are close to eviction. 274 Rather than reference such an entry, the encoder can emit a Duplicate 275 instruction (see Section 4.3.3), and reference the duplicate instead. 277 Determining which entries are too close to eviction to reference is 278 an encoder preference. One heuristic is to target a fixed amount of 279 available space in the dynamic table: either unused space or space 280 that can be reclaimed by evicting non-blocking entries. To achieve 281 this, the encoder can maintain a draining index, which is the 282 smallest absolute index in the dynamic table that it will emit a 283 reference for. As new entries are inserted, the encoder increases 284 the draining index to maintain the section of the table that it will 285 not reference. If the encoder does not create new references to 286 entries with an absolute index lower than the draining index, the 287 number of unacknowledged references to those entries will eventually 288 become zero, allowing them to be evicted. 290 +----------+---------------------------------+--------+ 291 | Draining | Referenceable | Unused | 292 | Entries | Entries | Space | 293 +----------+---------------------------------+--------+ 294 ^ ^ ^ 295 | | | 296 Dropping Draining Index Insertion Point 297 Point 299 Figure 1: Draining Dynamic Table Entries 301 2.1.3. Avoiding Head-of-Line Blocking 303 Because QUIC does not guarantee order between data on different 304 streams, a header block might reference an entry in the dynamic table 305 that has not yet been received. 307 Each header block contains a Required Insert Count, the lowest 308 possible value for the Insert Count with which the header block can 309 be decoded. For a header block with references to the dynamic table, 310 the Required Insert Count is one larger than the largest Absolute 311 Index of all referenced dynamic table entries. For a header block 312 with no references to the dynamic table, the Required Insert Count is 313 zero. 315 If the decoder encounters a header block with a Required Insert Count 316 value larger than defined above, it MAY treat this as a stream error 317 of type HTTP_QPACK_DECOMPRESSION_FAILED. If the decoder encounters a 318 header block with a Required Insert Count value smaller than defined 319 above, it MUST treat this as a stream error of type 320 HTTP_QPACK_DECOMPRESSION_FAILED as prescribed in Section 3.2.7. 322 When the Required Insert Count is zero, the frame contains no 323 references to the dynamic table and can always be processed 324 immediately. 326 If the Required Insert Count is greater than the number of dynamic 327 table entries received, the stream is considered "blocked." While 328 blocked, header field data SHOULD remain in the blocked stream's flow 329 control window. A stream becomes unblocked when the Insert Count 330 becomes greater than or equal to the Required Insert Count for all 331 header blocks the decoder has started reading from the stream. 333 The SETTINGS_QPACK_BLOCKED_STREAMS setting (see Section 5) specifies 334 an upper bound on the number of streams which can be blocked. An 335 encoder MUST limit the number of streams which could become blocked 336 to the value of SETTINGS_QPACK_BLOCKED_STREAMS at all times. Note 337 that the decoder might not actually become blocked on every stream 338 which risks becoming blocked. If the decoder encounters more blocked 339 streams than it promised to support, it MUST treat this as a stream 340 error of type HTTP_QPACK_DECOMPRESSION_FAILED. 342 An encoder can decide whether to risk having a stream become blocked. 343 If permitted by the value of SETTINGS_QPACK_BLOCKED_STREAMS, 344 compression efficiency can often be improved by referencing dynamic 345 table entries that are still in transit, but if there is loss or 346 reordering the stream can become blocked at the decoder. An encoder 347 avoids the risk of blocking by only referencing dynamic table entries 348 which have been acknowledged, but this could mean using literals. 349 Since literals make the header block larger, this can result in the 350 encoder becoming blocked on congestion or flow control limits. 352 2.1.4. Known Received Count 354 In order to identify which dynamic table entries can be safely used 355 without a stream becoming blocked, the encoder tracks the number of 356 entries received by the decoder. The Known Received Count tracks the 357 total number of acknowledged insertions. 359 When blocking references are permitted, the encoder uses header block 360 acknowledgement to maintain the Known Received Count, as described in 361 Section 4.4.2. 363 To acknowledge dynamic table entries which are not referenced by 364 header blocks, for example because the encoder or the decoder have 365 chosen not to risk blocked streams, the decoder sends an Insert Count 366 Increment instruction (see Section 4.4.1). 368 2.2. Decoder 370 As in HPACK, the decoder processes header blocks and emits the 371 corresponding header lists. It also processes dynamic table 372 modifications from encoder instructions received on the encoder 373 stream. 375 The decoder MUST emit header fields in the order their 376 representations appear in the input header block. 378 2.2.1. State Synchronization 380 The decoder instructions (Section 4.4) signal key events at the 381 decoder that permit the encoder to track the decoder's state. These 382 events are: 384 o Complete processing of a header block 386 o Abandonment of a stream which might have remaining header blocks 388 o Receipt of new dynamic table entries 390 Knowledge that a header block with references to the dynamic table 391 has been processed permits the encoder to evict entries to which no 392 unacknowledged references remain (see Section 2.1.2). When a stream 393 is reset or abandoned, the indication that these header blocks will 394 never be processed serves a similar function (see Section 4.4.3). 396 The decoder chooses when to emit Insert Count Increment instructions 397 (see Section 4.4.1). Emitting an instruction after adding each new 398 dynamic table entry will provide the most timely feedback to the 399 encoder, but could be redundant with other decoder feedback. By 400 delaying an Insert Count Increment instruction, the decoder might be 401 able to coalesce multiple Insert Count Increment instructions, or 402 replace them entirely with Header Acknowledgements (see 403 Section 4.4.2). However, delaying too long may lead to compression 404 inefficiencies if the encoder waits for an entry to be acknowledged 405 before using it. 407 2.2.2. Blocked Decoding 409 To track blocked streams, the Required Insert Count value for each 410 stream can be used. Whenever the decoder processes a table update, 411 it can begin decoding any blocked streams that now have their 412 dependencies satisfied. 414 3. Header Tables 416 Unlike in HPACK, entries in the QPACK static and dynamic tables are 417 addressed separately. The following sections describe how entries in 418 each table are addressed. 420 3.1. Static Table 422 The static table consists of a predefined static list of header 423 fields, each of which has a fixed index over time. Its entries are 424 defined in Appendix A. 426 All entries in the static table have a name and a value. However, 427 values can be empty (that is, have a length of 0). 429 Note the QPACK static table is indexed from 0, whereas the HPACK 430 static table is indexed from 1. 432 When the decoder encounters an invalid static table index in a header 433 block instruction it MUST treat this as a stream error of type 434 "HTTP_QPACK_DECOMPRESSION_FAILED". If this index is received on the 435 encoder stream, this MUST be treated as a connection error of type 436 "HTTP_QPACK_ENCODER_STREAM_ERROR". 438 3.2. Dynamic Table 440 The dynamic table consists of a list of header fields maintained in 441 first-in, first-out order. Each HTTP/3 endpoint holds a dynamic 442 table that is initially empty. Entries are added by encoder 443 instructions received on the encoder stream (see Section 4.3). 445 The dynamic table can contain duplicate entries (i.e., entries with 446 the same name and same value). Therefore, duplicate entries MUST NOT 447 be treated as an error by the decoder. 449 3.2.1. Dynamic Table Size 451 The size of the dynamic table is the sum of the size of its entries. 453 The size of an entry is the sum of its name's length in bytes (as 454 defined in Section 4.1.2), its value's length in bytes, and 32. 456 The size of an entry is calculated using the length of its name and 457 value without Huffman encoding applied. 459 3.2.2. Dynamic Table Capacity and Eviction 461 The encoder sets the capacity of the dynamic table, which serves as 462 the upper limit on its size. The initial capcity of the dynamic 463 table is zero. 465 Before a new entry is added to the dynamic table, entries are evicted 466 from the end of the dynamic table until the size of the dynamic table 467 is less than or equal to (table capacity - size of new entry) or 468 until the table is empty. The encoder MUST NOT evict a blocking 469 dynamic table entry (see Section 2.1.2). 471 If the size of the new entry is less than or equal to the dynamic 472 table capacity, then that entry is added to the table. It is an 473 error if the encoder attempts to add an entry that is larger than the 474 dynamic table capacity; the decoder MUST treat this as a connection 475 error of type "HTTP_QPACK_ENCODER_STREAM_ERROR". 477 A new entry can reference an entry in the dynamic table that will be 478 evicted when adding this new entry into the dynamic table. 479 Implementations are cautioned to avoid deleting the referenced name 480 or value if the referenced entry is evicted from the dynamic table 481 prior to inserting the new entry. 483 Whenever the dynamic table capacity is reduced by the encoder, 484 entries are evicted from the end of the dynamic table until the size 485 of the dynamic table is less than or equal to the new table capacity. 486 This mechanism can be used to completely clear entries from the 487 dynamic table by setting a capacity of 0, which can subsequently be 488 restored. 490 3.2.3. Maximum Dynamic Table Capacity 492 To bound the memory requirements of the decoder, the decoder limits 493 the maximum value the encoder is permitted to set for the dynamic 494 table capacity. In HTTP/3, this limit is determined by the value of 495 SETTINGS_QPACK_MAX_TABLE_CAPACITY sent by the decoder (see 496 Section 5). The encoder MUST not set a dynamic table capacity that 497 exceeds this maximum, but it can choose to use a lower dynamic table 498 capacity (see Section 4.3.4). 500 For clients using 0-RTT data in HTTP/3, the server's maximum table 501 capacity is the remembered value of the setting, or zero if the value 502 was not previously sent. When the client's 0-RTT value of the 503 SETTING is 0, the server MAY set it to a non-zero value in its 504 SETTINGS frame. If the remembered value is non-zero, the server MUST 505 send the same non-zero value in its SETTINGS frame. If it specifies 506 any other value, or omits SETTINGS_QPACK_MAX_TABLE_CAPACITY from 507 SETTINGS, the encoder must treat this as a connection error of type 508 "HTTP_QPACK_DECODER_STREAM_ERROR". 510 For HTTP/3 servers and HTTP/3 clients when 0-RTT is not attempted or 511 is rejected, the maximum table capacity is 0 until the encoder 512 processes a SETTINGS frame with a non-zero value of 513 SETTINGS_QPACK_MAX_TABLE_CAPACITY. 515 When the maximum table capacity is 0, the encoder MUST NOT insert 516 entries into the dynamic table, and MUST NOT send any encoder 517 instructions on the encoder stream. 519 3.2.4. Absolute Indexing 521 Each entry possesses both an absolute index which is fixed for the 522 lifetime of that entry and a relative index which changes based on 523 the context of the reference. The first entry inserted has an 524 absolute index of "0"; indices increase by one with each insertion. 526 3.2.5. Relative Indexing 528 The relative index begins at zero and increases in the opposite 529 direction from the absolute index. Determining which entry has a 530 relative index of "0" depends on the context of the reference. 532 In encoder instructions, a relative index of "0" always refers to the 533 most recently inserted value in the dynamic table. Note that this 534 means the entry referenced by a given relative index will change 535 while interpreting instructions on the encoder stream. 537 +-----+---------------+-------+ 538 | n-1 | ... | d | Absolute Index 539 + - - +---------------+ - - - + 540 | 0 | ... | n-d-1 | Relative Index 541 +-----+---------------+-------+ 542 ^ | 543 | V 544 Insertion Point Dropping Point 546 n = count of entries inserted 547 d = count of entries dropped 549 Example Dynamic Table Indexing - Control Stream 551 Unlike encoder instructions, relative indices in header block 552 instructions are relative to the Base at the beginning of the header 553 block (see Section 4.5.1). This ensures that references are stable 554 even if the dynamic table is updated while decoding a header block. 556 The Base is encoded as a value relative to the Required Insert Count. 557 The Base identifies which dynamic table entries can be referenced 558 using relative indexing, starting with 0 at the last entry added. 560 Post-Base references are used for entries inserted after base, 561 starting at 0 for the first entry added after the Base, see 562 Section 3.2.6. 564 Required 565 Insert 566 Count Base 567 | | 568 V V 569 +-----+-----+-----+-----+-------+ 570 | n-1 | n-2 | n-3 | ... | d | Absolute Index 571 +-----+-----+ - +-----+ - + 572 | 0 | ... | n-d-3 | Relative Index 573 +-----+-----+-------+ 575 n = count of entries inserted 576 d = count of entries dropped 578 Example Dynamic Table Indexing - Relative Index in Header Block 580 3.2.6. Post-Base Indexing 582 A header block can reference entries added after the entry identified 583 by the Base. This allows an encoder to process a header block in a 584 single pass and include references to entries added while processing 585 this (or other) header blocks. Newly added entries are referenced 586 using Post-Base instructions. Indices for Post-Base instructions 587 increase in the same direction as absolute indices, with the zero 588 value being the first entry inserted after the Base. 590 Base 591 | 592 V 593 +-----+-----+-----+-----+-----+ 594 | n-1 | n-2 | n-3 | ... | d | Absolute Index 595 +-----+-----+-----+-----+-----+ 596 | 1 | 0 | Post-Base Index 597 +-----+-----+ 599 n = count of entries inserted 600 d = count of entries dropped 602 Example Dynamic Table Indexing - Post-Base Index in Header Block 604 3.2.7. Invalid References 606 If the decoder encounters a reference in a header block instruction 607 to a dynamic table entry which has already been evicted or which has 608 an absolute index greater than or equal to the declared Required 609 Insert Count (see Section 4.5.1), it MUST treat this as a stream 610 error of type "HTTP_QPACK_DECOMPRESSION_FAILED". 612 If the decoder encounters a reference in an encoder instruction to a 613 dynamic table entry which has already been dropped, it MUST treat 614 this as a connection error of type "HTTP_QPACK_ENCODER_STREAM_ERROR". 616 4. Wire Format 618 4.1. Primitives 620 4.1.1. Prefixed Integers 622 The prefixed integer from Section 5.1 of [RFC7541] is used heavily 623 throughout this document. The format from [RFC7541] is used 624 unmodified. QPACK implementations MUST be able to decode integers up 625 to 62 bits long. 627 4.1.2. String Literals 629 The string literal defined by Section 5.2 of [RFC7541] is also used 630 throughout. This string format includes optional Huffman encoding. 632 HPACK defines string literals to begin on a byte boundary. They 633 begin with a single flag (indicating whether the string is Huffman- 634 coded), followed by the Length encoded as a 7-bit prefix integer, and 635 finally Length bytes of data. When Huffman encoding is enabled, the 636 Huffman table from Appendix B of [RFC7541] is used without 637 modification. 639 This document expands the definition of string literals and permits 640 them to begin other than on a byte boundary. An "N-bit prefix string 641 literal" begins with the same Huffman flag, followed by the length 642 encoded as an (N-1)-bit prefix integer. The remainder of the string 643 literal is unmodified. 645 A string literal without a prefix length noted is an 8-bit prefix 646 string literal and follows the definitions in [RFC7541] without 647 modification. 649 4.2. Instructions 651 There are three separate QPACK instruction spaces. Encoder 652 instructions (Section 4.3) carry table updates, decoder instructions 653 (Section 4.4) carry acknowledgments of table modifications and header 654 processing, and header block instructions (Section 4.5) convey an 655 encoded representation of a header list by referring to the QPACK 656 table state. 658 Encoder and decoder instructions appear on the unidirectional stream 659 types described in this section. Header block instructions are 660 contained in HEADERS and PUSH_PROMISE frames, which are conveyed on 661 request or push streams as described in [HTTP3]. 663 4.2.1. Encoder and Decoder Streams 665 QPACK defines two unidirectional stream types: 667 o An encoder stream is a unidirectional stream of type "0x02". It 668 carries an unframed sequence of encoder instructions from encoder 669 to decoder. 671 o A decoder stream is a unidirectional stream of type "0x03". It 672 carries an unframed sequence of decoder instructions from decoder 673 to encoder. 675 HTTP/3 endpoints contain a QPACK encoder and decoder. Each endpoint 676 MUST initiate a single encoder stream and decoder stream. Receipt of 677 a second instance of either stream type be MUST treated as a 678 connection error of type HTTP_WRONG_STREAM_COUNT. These streams MUST 679 NOT be closed. Closure of either unidirectional stream type MUST be 680 treated as a connection error of type HTTP_CLOSED_CRITICAL_STREAM. 682 4.3. Encoder Instructions 684 Table updates can add a table entry, possibly using existing entries 685 to avoid transmitting redundant information. The name can be 686 transmitted as a reference to an existing entry in the static or the 687 dynamic table or as a string literal. For entries which already 688 exist in the dynamic table, the full entry can also be used by 689 reference, creating a duplicate entry. 691 This section specifies the following encoder instructions. 693 4.3.1. Insert With Name Reference 695 An addition to the header table where the header field name matches 696 the header field name of an entry stored in the static table or the 697 dynamic table starts with the '1' one-bit pattern. The "S" bit 698 indicates whether the reference is to the static (S=1) or dynamic 699 (S=0) table. The 6-bit prefix integer (see Section 5.1 of [RFC7541]) 700 that follows is used to locate the table entry for the header name. 701 When S=1, the number represents the static table index; when S=0, the 702 number is the relative index of the entry in the dynamic table. 704 The header name reference is followed by the header field value 705 represented as a string literal (see Section 5.2 of [RFC7541]). 707 0 1 2 3 4 5 6 7 708 +---+---+---+---+---+---+---+---+ 709 | 1 | S | Name Index (6+) | 710 +---+---+-----------------------+ 711 | H | Value Length (7+) | 712 +---+---------------------------+ 713 | Value String (Length bytes) | 714 +-------------------------------+ 716 Insert Header Field -- Indexed Name 718 4.3.2. Insert Without Name Reference 720 An addition to the header table where both the header field name and 721 the header field value are represented as string literals (see 722 Section 4.1) starts with the '01' two-bit pattern. 724 The name is represented as a 6-bit prefix string literal, while the 725 value is represented as an 8-bit prefix string literal. 727 0 1 2 3 4 5 6 7 728 +---+---+---+---+---+---+---+---+ 729 | 0 | 1 | H | Name Length (5+) | 730 +---+---+---+-------------------+ 731 | Name String (Length bytes) | 732 +---+---------------------------+ 733 | H | Value Length (7+) | 734 +---+---------------------------+ 735 | Value String (Length bytes) | 736 +-------------------------------+ 738 Insert Header Field -- New Name 740 4.3.3. Duplicate 742 Duplication of an existing entry in the dynamic table starts with the 743 '000' three-bit pattern. The relative index of the existing entry is 744 represented as an integer with a 5-bit prefix. 746 0 1 2 3 4 5 6 7 747 +---+---+---+---+---+---+---+---+ 748 | 0 | 0 | 0 | Index (5+) | 749 +---+---+---+-------------------+ 751 Figure 2: Duplicate 753 The existing entry is re-inserted into the dynamic table without 754 resending either the name or the value. This is useful to mitigate 755 the eviction of older entries which are frequently referenced, both 756 to avoid the need to resend the header and to avoid the entry in the 757 table blocking the ability to insert new headers. 759 4.3.4. Set Dynamic Table Capacity 761 An encoder informs the decoder of a change to the dynamic table 762 capacity using an instruction which begins with the '001' three-bit 763 pattern. The new dynamic table capacity is represented as an integer 764 with a 5-bit prefix (see Section 5.1 of [RFC7541]). 766 0 1 2 3 4 5 6 7 767 +---+---+---+---+---+---+---+---+ 768 | 0 | 0 | 1 | Capacity (5+) | 769 +---+---+---+-------------------+ 771 Figure 3: Set Dynamic Table Capacity 773 The new capacity MUST be lower than or equal to the limit described 774 in Section 3.2.3. In HTTP/3, this limit is the value of the 775 SETTINGS_QPACK_MAX_TABLE_CAPACITY parameter (see Section 5) received 776 from the decoder. The decoder MUST treat a new dynamic table 777 capacity value that exceeds this limit as a connection error of type 778 "HTTP_QPACK_ENCODER_STREAM_ERROR". 780 Reducing the dynamic table capacity can cause entries to be evicted 781 (see Section 3.2.2). This MUST NOT cause the eviction of blocking 782 entries (see Section 2.1.2). Changing the capacity of the dynamic 783 table is not acknowledged as this instruction does not insert an 784 entry. 786 4.4. Decoder Instructions 788 Decoder instructions provide information used to ensure consistency 789 of the dynamic table. They are sent from the decoder to the encoder 790 on a decoder stream; that is, the server informs the client about the 791 processing of the client's header blocks and table updates, and the 792 client informs the server about the processing of the server's header 793 blocks and table updates. 795 This section specifies the following decoder instructions. 797 4.4.1. Insert Count Increment 799 The Insert Count Increment instruction begins with the '00' two-bit 800 pattern. The instruction specifies the total number of dynamic table 801 inserts and duplications since the last Insert Count Increment or 802 Header Acknowledgement that increased the Known Received Count for 803 the dynamic table (see Section 2.1.4). The Increment field is 804 encoded as a 6-bit prefix integer. The encoder uses this value to 805 determine which table entries might cause a stream to become blocked, 806 as described in Section 2.2.1. 808 0 1 2 3 4 5 6 7 809 +---+---+---+---+---+---+---+---+ 810 | 0 | 0 | Increment (6+) | 811 +---+---+-----------------------+ 813 Figure 4: Insert Count Increment 815 An encoder that receives an Increment field equal to zero or one that 816 increases the Known Received Count beyond what the encoder has sent 817 MUST treat this as a connection error of type 818 "HTTP_QPACK_DECODER_STREAM_ERROR". 820 4.4.2. 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 on the decoder stream. The instruction begins with the '1' one-bit 825 pattern and includes the header block's associated stream ID, encoded 826 as a 7-bit prefix integer. It is used by the peer's encoder to know 827 when it is safe to evict an entry, and possibly update the Known 828 Received Count. 830 0 1 2 3 4 5 6 7 831 +---+---+---+---+---+---+---+---+ 832 | 1 | Stream ID (7+) | 833 +---+---------------------------+ 835 Figure 5: Header Acknowledgement 837 The same Stream ID can be identified multiple times, as multiple 838 header blocks can be sent on a single stream in the case of 839 intermediate responses, trailers, and pushed requests. Since HEADERS 840 and PUSH_PROMISE frames on each stream are received and processed in 841 order, this gives the encoder precise feedback on which header blocks 842 within a stream have been fully processed. 844 If an encoder receives a Header Acknowledgement instruction referring 845 to a stream on which every header block with a non-zero Required 846 Insert Count has already been acknowledged, that MUST be treated as a 847 connection error of type "HTTP_QPACK_DECODER_STREAM_ERROR". 849 When blocking references are permitted, the encoder uses 850 acknowledgement of header blocks to update the Known Received Count. 852 If a header block was potentially blocking, the acknowledgement 853 implies that the decoder has received all dynamic table state 854 necessary to process the header block. If the Required Insert Count 855 of an acknowledged header block was greater than the encoder's 856 current Known Received Count, the block's Required Insert Count 857 becomes the new Known Received Count. 859 4.4.3. Stream Cancellation 861 The instruction begins with the '01' two-bit pattern. The 862 instruction includes the stream ID of the affected stream - a request 863 or push stream - encoded as a 6-bit prefix integer. 865 0 1 2 3 4 5 6 7 866 +---+---+---+---+---+---+---+---+ 867 | 0 | 1 | Stream ID (6+) | 868 +---+---+-----------------------+ 870 Figure 6: Stream Cancellation 872 A stream that is reset might have multiple outstanding header blocks 873 with dynamic table references. When an endpoint receives a stream 874 reset before the end of a stream, it generates a Stream Cancellation 875 instruction on the decoder stream. Similarly, when an endpoint 876 abandons reading of a stream it needs to signal this using the Stream 877 Cancellation instruction. This signals to the encoder that all 878 references to the dynamic table on that stream are no longer 879 outstanding. A decoder with a maximum dynamic table capacity equal 880 to zero (see Section 3.2.3) MAY omit sending Stream Cancellations, 881 because the encoder cannot have any dynamic table references. 883 An encoder cannot infer from this instruction that any updates to the 884 dynamic table have been received. 886 4.5. Header Block Instructions 888 HTTP/3 endpoints convert header lists to headers blocks and exchange 889 them inside HEADERS and PUSH_PROMISE frames. A decoder interprets 890 header block instructions in order to construct a header list. These 891 instructions reference the static table, or dynamic table in a 892 particular state without modifying it. 894 This section specifies the following header block instructions. 896 4.5.1. Header Block Prefix 898 Each header block is prefixed with two integers. The Required Insert 899 Count is encoded as an integer with an 8-bit prefix after the 900 encoding described in Section 4.5.1.1). The Base is encoded as sign- 901 and-modulus integer, using a single sign bit and a value with a 7-bit 902 prefix (see Section 4.5.1.2). 904 These two values are followed by instructions for compressed headers. 905 The entire block is expected to be framed by the using protocol. 907 0 1 2 3 4 5 6 7 908 +---+---+---+---+---+---+---+---+ 909 | Required Insert Count (8+) | 910 +---+---------------------------+ 911 | S | Delta Base (7+) | 912 +---+---------------------------+ 913 | Compressed Headers ... 914 +-------------------------------+ 916 Figure 7: Frame Payload 918 4.5.1.1. Required Insert Count 920 Required Insert Count identifies the state of the dynamic table 921 needed to process the header block. Blocking decoders use the 922 Required Insert Count to determine when it is safe to process the 923 rest of the block. 925 The encoder transforms the Required Insert Count as follows before 926 encoding: 928 if ReqInsertCount == 0: 929 EncInsertCount = 0 930 else: 931 EncInsertCount = (ReqInsertCount mod (2 * MaxEntries)) + 1 933 Here "MaxEntries" is the maximum number of entries that the dynamic 934 table can have. The smallest entry has empty name and value strings 935 and has the size of 32. Hence "MaxEntries" is calculated as 937 MaxEntries = floor( MaxTableCapacity / 32 ) 939 "MaxTableCapacity" is the maximum capacity of the dynamic table as 940 specified by the decoder (see Section 3.2.3). 942 This encoding limits the length of the prefix on long-lived 943 connections. 945 The decoder can reconstruct the Required Insert Count using an 946 algorithm such as the following. If the decoder encounters a value 947 of EncodedInsertCount that could not have been produced by a 948 conformant encoder, it MUST treat this as a stream error of type 949 "HTTP_QPACK_DECOMPRESSION_FAILED". 951 TotalNumberOfInserts is the total number of inserts into the 952 decoder's dynamic table. 954 FullRange = 2 * MaxEntries 955 if EncodedInsertCount == 0: 956 ReqInsertCount = 0 957 else: 958 if EncodedInsertCount > FullRange: 959 Error 960 MaxValue = TotalNumberOfInserts + MaxEntries 962 # MaxWrapped is the largest possible value of 963 # ReqInsertCount that is 0 mod 2*MaxEntries 964 MaxWrapped = floor(MaxValue / FullRange) * FullRange 965 ReqInsertCount = MaxWrapped + EncodedInsertCount - 1 967 # If ReqInsertCount exceeds MaxValue, the Encoder's value 968 # must have wrapped one fewer time 969 if ReqInsertCount > MaxValue: 970 if ReqInsertCount < FullRange: 971 Error 972 ReqInsertCount -= FullRange 974 For example, if the dynamic table is 100 bytes, then the Required 975 Insert Count will be encoded modulo 6. If a decoder has received 10 976 inserts, then an encoded value of 3 indicates that the Required 977 Insert Count is 9 for the header block. 979 4.5.1.2. Base 981 The "Base" is used to resolve references in the dynamic table as 982 described in Section 3.2.5. 984 To save space, the Base is encoded relative to the Insert Count using 985 a one-bit sign and the "Delta Base" value. A sign bit of 0 indicates 986 that the Base is greater than or equal to the value of the Insert 987 Count; the value of Delta Base is added to the Insert Count to 988 determine the value of the Base. A sign bit of 1 indicates that the 989 Base is less than the Insert Count. That is: 991 if S == 0: 992 Base = ReqInsertCount + DeltaBase 993 else: 994 Base = ReqInsertCount - DeltaBase - 1 996 A single-pass encoder determines the Base before encoding a header 997 block. If the encoder inserted entries in the dynamic table while 998 encoding the header block, Required Insert Count will be greater than 999 the Base, so the encoded difference is negative and the sign bit is 1000 set to 1. If the header block did not reference the most recent 1001 entry in the table and did not insert any new entries, the Base will 1002 be greater than the Required Insert Count, so the delta will be 1003 positive and the sign bit is set to 0. 1005 An encoder that produces table updates before encoding a header block 1006 might set Required Insert Count and the Base to the same value. In 1007 such case, both the sign bit and the Delta Base will be set to zero. 1009 A header block that does not reference the dynamic table can use any 1010 value for the Base; setting Delta Base to zero is the most efficient 1011 encoding. 1013 For example, with an Required Insert Count of 9, a decoder receives a 1014 S bit of 1 and a Delta Base of 2. This sets the Base to 6 and 1015 enables post-base indexing for three entries. In this example, a 1016 regular index of 1 refers to the 5th entry that was added to the 1017 table; a post-base index of 1 refers to the 8th entry. 1019 4.5.2. Indexed Header Field 1021 An indexed header field representation identifies an entry in either 1022 the static table or the dynamic table and causes that header field to 1023 be added to the decoded header list, as described in Section 3.2 of 1024 [RFC7541]. 1026 0 1 2 3 4 5 6 7 1027 +---+---+---+---+---+---+---+---+ 1028 | 1 | S | Index (6+) | 1029 +---+---+-----------------------+ 1031 Indexed Header Field 1033 If the entry is in the static table, or in the dynamic table with an 1034 absolute index less than the Base, this representation starts with 1035 the '1' 1-bit pattern, followed by the "S" bit indicating whether the 1036 reference is into the static (S=1) or dynamic (S=0) table. Finally, 1037 the relative index of the matching header field is represented as an 1038 integer with a 6-bit prefix (see Section 5.1 of [RFC7541]). 1040 4.5.3. Indexed Header Field With Post-Base Index 1042 If the entry is in the dynamic table with an absolute index greater 1043 than or equal to the Base, the representation starts with the '0001' 1044 4-bit pattern, followed by the post-base index (see Section 3.2.6) of 1045 the matching header field, represented as an integer with a 4-bit 1046 prefix (see Section 5.1 of [RFC7541]). 1048 0 1 2 3 4 5 6 7 1049 +---+---+---+---+---+---+---+---+ 1050 | 0 | 0 | 0 | 1 | Index (4+) | 1051 +---+---+---+---+---------------+ 1053 Indexed Header Field with Post-Base Index 1055 4.5.4. Literal Header Field With Name Reference 1057 A literal header field with a name reference represents a header 1058 where the header field name matches the header field name of an entry 1059 stored in the static table or the dynamic table. 1061 If the entry is in the static table, or in the dynamic table with an 1062 absolute index less than the Base, this representation starts with 1063 the '01' two-bit pattern. If the entry is in the dynamic table with 1064 an absolute index greater than or equal to the Base, the 1065 representation starts with the '0000' four-bit pattern. 1067 Only the header field name stored in the static or dynamic table is 1068 used. Any header field value MUST be ignored. 1070 The following bit, 'N', indicates whether an intermediary is 1071 permitted to add this header to the dynamic header table on 1072 subsequent hops. When the 'N' bit is set, the encoded header MUST 1073 always be encoded with a literal representation. In particular, when 1074 a peer sends a header field that it received represented as a literal 1075 header field with the 'N' bit set, it MUST use a literal 1076 representation to forward this header field. This bit is intended 1077 for protecting header field values that are not to be put at risk by 1078 compressing them (see Section 7.1 of [RFC7541] for more details). 1080 0 1 2 3 4 5 6 7 1081 +---+---+---+---+---+---+---+---+ 1082 | 0 | 1 | N | S |Name Index (4+)| 1083 +---+---+---+---+---------------+ 1084 | H | Value Length (7+) | 1085 +---+---------------------------+ 1086 | Value String (Length bytes) | 1087 +-------------------------------+ 1089 Literal Header Field With Name Reference 1091 For entries in the static table or in the dynamic table with an 1092 absolute index less than the Base, the header field name is 1093 represented using the relative index of that entry, which is 1094 represented as an integer with a 4-bit prefix (see Section 5.1 of 1095 [RFC7541]). The "S" bit indicates whether the reference is to the 1096 static (S=1) or dynamic (S=0) table. 1098 4.5.5. Literal Header Field With Post-Base Name Reference 1100 For entries in the dynamic table with an absolute index greater than 1101 or equal to the Base, the header field name is represented using the 1102 post-base index of that entry (see Section 3.2.6) encoded as an 1103 integer with a 3-bit prefix. 1105 0 1 2 3 4 5 6 7 1106 +---+---+---+---+---+---+---+---+ 1107 | 0 | 0 | 0 | 0 | N |NameIdx(3+)| 1108 +---+---+---+---+---+-----------+ 1109 | H | Value Length (7+) | 1110 +---+---------------------------+ 1111 | Value String (Length bytes) | 1112 +-------------------------------+ 1114 Literal Header Field With Post-Base Name Reference 1116 4.5.6. Literal Header Field Without Name Reference 1118 An addition to the header table where both the header field name and 1119 the header field value are represented as string literals (see 1120 Section 4.1) starts with the '001' three-bit pattern. 1122 The fourth bit, 'N', indicates whether an intermediary is permitted 1123 to add this header to the dynamic header table on subsequent hops. 1124 When the 'N' bit is set, the encoded header MUST always be encoded 1125 with a literal representation. In particular, when a peer sends a 1126 header field that it received represented as a literal header field 1127 with the 'N' bit set, it MUST use a literal representation to forward 1128 this header field. This bit is intended for protecting header field 1129 values that are not to be put at risk by compressing them (see 1130 Section 7.1 of [RFC7541] for more details). 1132 The name is represented as a 4-bit prefix string literal, while the 1133 value is represented as an 8-bit prefix string literal. 1135 0 1 2 3 4 5 6 7 1136 +---+---+---+---+---+---+---+---+ 1137 | 0 | 0 | 1 | N | H |NameLen(3+)| 1138 +---+---+---+---+---+-----------+ 1139 | Name String (Length bytes) | 1140 +---+---------------------------+ 1141 | H | Value Length (7+) | 1142 +---+---------------------------+ 1143 | Value String (Length bytes) | 1144 +-------------------------------+ 1146 Literal Header Field Without Name Reference 1148 5. Configuration 1150 QPACK defines two settings which are included in the HTTP/3 SETTINGS 1151 frame. 1153 SETTINGS_QPACK_MAX_TABLE_CAPACITY (0x1): An integer with a maximum 1154 value of 2^30 - 1. The default value is zero bytes. See 1155 Section 3.2 for usage. This is the equivalent of the 1156 SETTINGS_HEADER_TABLE_SIZE from HTTP/2. 1158 SETTINGS_QPACK_BLOCKED_STREAMS (0x7): An integer with a maximum 1159 value of 2^16 - 1. The default value is zero. See Section 2.1.3. 1161 6. Error Handling 1163 The following error codes are defined for HTTP/3 to indicate failures 1164 of QPACK which prevent the stream or connection from continuing: 1166 HTTP_QPACK_DECOMPRESSION_FAILED (TBD): The decoder failed to 1167 interpret a header block instruction and is not able to continue 1168 decoding that header block. 1170 HTTP_QPACK_ENCODER_STREAM_ERROR (TBD): The decoder failed to 1171 interpret an encoder instruction received on the encoder stream. 1173 HTTP_QPACK_DECODER_STREAM_ERROR (TBD): The encoder failed to 1174 interpret a decoder instruction received on the decoder stream. 1176 Upon encountering an error, an implementation MAY elect to treat it 1177 as a connection error even if this document prescribes that it MUST 1178 be treated as a stream error. 1180 7. Security Considerations 1182 TBD. 1184 8. IANA Considerations 1186 8.1. Settings Registration 1188 This document specifies two settings. The entries in the following 1189 table are registered in the "HTTP/3 Settings" registry established in 1190 [HTTP3]. 1192 +--------------------------+------+---------------+ 1193 | Setting Name | Code | Specification | 1194 +--------------------------+------+---------------+ 1195 | QPACK_MAX_TABLE_CAPACITY | 0x1 | Section 5 | 1196 | | | | 1197 | QPACK_BLOCKED_STREAMS | 0x7 | Section 5 | 1198 +--------------------------+------+---------------+ 1200 8.2. Stream Type Registration 1202 This document specifies two stream types. The entries in the 1203 following table are registered in the "HTTP/3 Stream Type" registry 1204 established in [HTTP3]. 1206 +----------------------+------+---------------+--------+ 1207 | Stream Type | Code | Specification | Sender | 1208 +----------------------+------+---------------+--------+ 1209 | QPACK Encoder Stream | 0x02 | Section 4.2.1 | Both | 1210 | | | | | 1211 | QPACK Decoder Stream | 0x03 | Section 4.2.1 | Both | 1212 +----------------------+------+---------------+--------+ 1214 8.3. Error Code Registration 1216 This document specifies three error codes. The entries in the 1217 following table are registered in the "HTTP/3 Error Code" registry 1218 established in [HTTP3]. 1220 +------------------------------+------+--------------+--------------+ 1221 | Name | Code | Description | Specificatio | 1222 | | | | n | 1223 +------------------------------+------+--------------+--------------+ 1224 | HTTP_QPACK_DECOMPRESSION_FAI | TBD | Decompressio | Section 6 | 1225 | LED | | n of a | | 1226 | | | header block | | 1227 | | | failed | | 1228 | | | | | 1229 | HTTP_QPACK_ENCODER_STREAM_ER | TBD | Error on the | Section 6 | 1230 | ROR | | encoder | | 1231 | | | stream | | 1232 | | | | | 1233 | HTTP_QPACK_DECODER_STREAM_ER | TBD | Error on the | Section 6 | 1234 | ROR | | decoder | | 1235 | | | stream | | 1236 +------------------------------+------+--------------+--------------+ 1238 9. References 1240 9.1. Normative References 1242 [HTTP3] Bishop, M., Ed., "Hypertext Transfer Protocol Version 3 1243 (HTTP/3)", draft-ietf-quic-http-19 (work in progress), 1244 March 2019. 1246 [QUIC-TRANSPORT] 1247 Iyengar, J., Ed. and M. Thomson, Ed., "QUIC: A UDP-Based 1248 Multiplexed and Secure Transport", draft-ietf-quic- 1249 transport-18 (work in progress), March 2019. 1251 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1252 Requirement Levels", BCP 14, RFC 2119, 1253 DOI 10.17487/RFC2119, March 1997, 1254 . 1256 [RFC7541] Peon, R. and H. Ruellan, "HPACK: Header Compression for 1257 HTTP/2", RFC 7541, DOI 10.17487/RFC7541, May 2015, 1258 . 1260 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 1261 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 1262 May 2017, . 1264 9.2. Informative References 1266 [RFC2360] Scott, G., "Guide for Internet Standards Writers", BCP 22, 1267 RFC 2360, DOI 10.17487/RFC2360, June 1998, 1268 . 1270 [RFC7540] Belshe, M., Peon, R., and M. Thomson, Ed., "Hypertext 1271 Transfer Protocol Version 2 (HTTP/2)", RFC 7540, 1272 DOI 10.17487/RFC7540, May 2015, 1273 . 1275 9.3. URIs 1277 [1] https://mailarchive.ietf.org/arch/search/?email_list=quic 1279 [2] https://github.com/quicwg 1281 [3] https://github.com/quicwg/base-drafts/labels/-qpack 1283 Appendix A. Static Table 1285 +------+-----------------------------+------------------------------+ 1286 | Inde | Name | Value | 1287 | x | | | 1288 +------+-----------------------------+------------------------------+ 1289 | 0 | :authority | | 1290 | | | | 1291 | 1 | :path | / | 1292 | | | | 1293 | 2 | age | 0 | 1294 | | | | 1295 | 3 | content-disposition | | 1296 | | | | 1297 | 4 | content-length | 0 | 1298 | | | | 1299 | 5 | cookie | | 1300 | | | | 1301 | 6 | date | | 1302 | | | | 1303 | 7 | etag | | 1304 | | | | 1305 | 8 | if-modified-since | | 1306 | | | | 1307 | 9 | if-none-match | | 1308 | | | | 1309 | 10 | last-modified | | 1310 | | | | 1311 | 11 | link | | 1312 | | | | 1313 | 12 | location | | 1314 | | | | 1315 | 13 | referer | | 1316 | | | | 1317 | 14 | set-cookie | | 1318 | | | | 1319 | 15 | :method | CONNECT | 1320 | | | | 1321 | 16 | :method | DELETE | 1322 | | | | 1323 | 17 | :method | GET | 1324 | | | | 1325 | 18 | :method | HEAD | 1326 | | | | 1327 | 19 | :method | OPTIONS | 1328 | | | | 1329 | 20 | :method | POST | 1330 | | | | 1331 | 21 | :method | PUT | 1332 | | | | 1333 | 22 | :scheme | http | 1334 | | | | 1335 | 23 | :scheme | https | 1336 | | | | 1337 | 24 | :status | 103 | 1338 | | | | 1339 | 25 | :status | 200 | 1340 | | | | 1341 | 26 | :status | 304 | 1342 | | | | 1343 | 27 | :status | 404 | 1344 | | | | 1345 | 28 | :status | 503 | 1346 | | | | 1347 | 29 | accept | */* | 1348 | | | | 1349 | 30 | accept | application/dns-message | 1350 | | | | 1351 | 31 | accept-encoding | gzip, deflate, br | 1352 | | | | 1353 | 32 | accept-ranges | bytes | 1354 | | | | 1355 | 33 | access-control-allow- | cache-control | 1356 | | headers | | 1357 | | | | 1358 | 34 | access-control-allow- | content-type | 1359 | | headers | | 1360 | | | | 1361 | 35 | access-control-allow-origin | * | 1362 | | | | 1363 | 36 | cache-control | max-age=0 | 1364 | | | | 1365 | 37 | cache-control | max-age=2592000 | 1366 | | | | 1367 | 38 | cache-control | max-age=604800 | 1368 | | | | 1369 | 39 | cache-control | no-cache | 1370 | | | | 1371 | 40 | cache-control | no-store | 1372 | | | | 1373 | 41 | cache-control | public, max-age=31536000 | 1374 | | | | 1375 | 42 | content-encoding | br | 1376 | | | | 1377 | 43 | content-encoding | gzip | 1378 | | | | 1379 | 44 | content-type | application/dns-message | 1380 | | | | 1381 | 45 | content-type | application/javascript | 1382 | | | | 1383 | 46 | content-type | application/json | 1384 | | | | 1385 | 47 | content-type | application/x-www-form- | 1386 | | | urlencoded | 1387 | | | | 1388 | 48 | content-type | image/gif | 1389 | | | | 1390 | 49 | content-type | image/jpeg | 1391 | | | | 1392 | 50 | content-type | image/png | 1393 | | | | 1394 | 51 | content-type | text/css | 1395 | | | | 1396 | 52 | content-type | text/html; charset=utf-8 | 1397 | | | | 1398 | 53 | content-type | text/plain | 1399 | | | | 1400 | 54 | content-type | text/plain;charset=utf-8 | 1401 | | | | 1402 | 55 | range | bytes=0- | 1403 | | | | 1404 | 56 | strict-transport-security | max-age=31536000 | 1405 | | | | 1406 | 57 | strict-transport-security | max-age=31536000; | 1407 | | | includesubdomains | 1408 | | | | 1409 | 58 | strict-transport-security | max-age=31536000; | 1410 | | | includesubdomains; preload | 1411 | | | | 1412 | 59 | vary | accept-encoding | 1413 | | | | 1414 | 60 | vary | origin | 1415 | | | | 1416 | 61 | x-content-type-options | nosniff | 1417 | | | | 1418 | 62 | x-xss-protection | 1; mode=block | 1419 | | | | 1420 | 63 | :status | 100 | 1421 | | | | 1422 | 64 | :status | 204 | 1423 | | | | 1424 | 65 | :status | 206 | 1425 | | | | 1426 | 66 | :status | 302 | 1427 | | | | 1428 | 67 | :status | 400 | 1429 | | | | 1430 | 68 | :status | 403 | 1431 | | | | 1432 | 69 | :status | 421 | 1433 | | | | 1434 | 70 | :status | 425 | 1435 | | | | 1436 | 71 | :status | 500 | 1437 | | | | 1438 | 72 | accept-language | | 1439 | | | | 1440 | 73 | access-control-allow- | FALSE | 1441 | | credentials | | 1442 | | | | 1443 | 74 | access-control-allow- | TRUE | 1444 | | credentials | | 1445 | | | | 1446 | 75 | access-control-allow- | * | 1447 | | headers | | 1448 | | | | 1449 | 76 | access-control-allow- | get | 1450 | | methods | | 1451 | | | | 1452 | 77 | access-control-allow- | get, post, options | 1453 | | methods | | 1454 | | | | 1455 | 78 | access-control-allow- | options | 1456 | | methods | | 1457 | | | | 1458 | 79 | access-control-expose- | content-length | 1459 | | headers | | 1460 | | | | 1461 | 80 | access-control-request- | content-type | 1462 | | headers | | 1463 | | | | 1464 | 81 | access-control-request- | get | 1465 | | method | | 1466 | | | | 1467 | 82 | access-control-request- | post | 1468 | | method | | 1469 | | | | 1470 | 83 | alt-svc | clear | 1471 | | | | 1472 | 84 | authorization | | 1473 | | | | 1474 | 85 | content-security-policy | script-src 'none'; object- | 1475 | | | src 'none'; base-uri 'none' | 1476 | | | | 1477 | 86 | early-data | 1 | 1478 | | | | 1479 | 87 | expect-ct | | 1480 | | | | 1481 | 88 | forwarded | | 1482 | | | | 1483 | 89 | if-range | | 1484 | | | | 1485 | 90 | origin | | 1486 | | | | 1487 | 91 | purpose | prefetch | 1488 | | | | 1489 | 92 | server | | 1490 | | | | 1491 | 93 | timing-allow-origin | * | 1492 | | | | 1493 | 94 | upgrade-insecure-requests | 1 | 1494 | | | | 1495 | 95 | user-agent | | 1496 | | | | 1497 | 96 | x-forwarded-for | | 1498 | | | | 1499 | 97 | x-frame-options | deny | 1500 | | | | 1501 | 98 | x-frame-options | sameorigin | 1502 +------+-----------------------------+------------------------------+ 1504 Appendix B. Sample One Pass Encoding Algorithm 1506 Pseudo-code for single pass encoding, excluding handling of 1507 duplicates, non-blocking mode, and reference tracking. 1509 baseIndex = dynamicTable.baseIndex 1510 largestReference = 0 1511 for header in headers: 1512 staticIdx = staticTable.getIndex(header) 1513 if staticIdx: 1514 encodeIndexReference(streamBuffer, staticIdx) 1515 continue 1517 dynamicIdx = dynamicTable.getIndex(header) 1518 if !dynamicIdx: 1519 # No matching entry. Either insert+index or encode literal 1520 nameIdx = getNameIndex(header) 1521 if shouldIndex(header) and dynamicTable.canIndex(header): 1522 encodeLiteralWithIncrementalIndex(controlBuffer, nameIdx, 1523 header) 1524 dynamicTable.add(header) 1525 dynamicIdx = dynamicTable.baseIndex 1527 if !dynamicIdx: 1528 # Couldn't index it, literal 1529 if nameIdx <= staticTable.size: 1530 encodeLiteral(streamBuffer, nameIndex, header) 1531 else: 1532 # encode literal, possibly with nameIdx above baseIndex 1533 encodeDynamicLiteral(streamBuffer, nameIndex, baseIndex, 1534 header) 1535 largestReference = max(largestReference, 1536 dynamicTable.toAbsolute(nameIdx)) 1537 else: 1538 # Dynamic index reference 1539 assert(dynamicIdx) 1540 largestReference = max(largestReference, dynamicIdx) 1541 # Encode dynamicIdx, possibly with dynamicIdx above baseIndex 1542 encodeDynamicIndexReference(streamBuffer, dynamicIdx, 1543 baseIndex) 1545 # encode the prefix 1546 encodeInteger(prefixBuffer, 0x00, largestReference, 8) 1547 if baseIndex >= largestReference: 1548 encodeInteger(prefixBuffer, 0, baseIndex - largestReference, 7) 1549 else: 1550 encodeInteger(prefixBuffer, 0x80, 1551 largestReference - baseIndex, 7) 1553 return controlBuffer, prefixBuffer + streamBuffer 1555 Appendix C. Change Log 1557 *RFC Editor's Note:* Please remove this section prior to 1558 publication of a final version of this document. 1560 C.1. Since draft-ietf-quic-qpack-06 1562 o Clarify initial dynamic table capacity maximums (#2276, #2330, 1563 #2330) 1565 C.2. Since draft-ietf-quic-qpack-05 1567 o Introduced the terms dynamic table capacity and maximum dynamic 1568 table capacity. 1570 o Renamed SETTINGS_HEADER_TABLE_SIZE to 1571 SETTINGS_QPACK_MAX_TABLE_CAPACITY. 1573 C.3. Since draft-ietf-quic-qpack-04 1575 o Changed calculation of Delta Base Index to avoid an illegal value 1576 (#2002, #2005) 1578 C.4. Since draft-ietf-quic-qpack-03 1580 o Change HTTP settings defaults (#2038) 1582 o Substantial editorial reorganization 1584 C.5. Since draft-ietf-quic-qpack-02 1586 o Largest Reference encoded modulo MaxEntries (#1763) 1588 o New Static Table (#1355) 1590 o Table Size Update with Insert Count=0 is a connection error 1591 (#1762) 1593 o Stream Cancellations are optional when 1594 SETTINGS_HEADER_TABLE_SIZE=0 (#1761) 1596 o Implementations must handle 62 bit integers (#1760) 1598 o Different error types for each QPACK stream, other changes to 1599 error handling (#1726) 1601 o Preserve header field order (#1725) 1602 o Initial table size is the maximum permitted when table is first 1603 usable (#1642) 1605 C.6. Since draft-ietf-quic-qpack-01 1607 o Only header blocks that reference the dynamic table are 1608 acknowledged (#1603, #1605) 1610 C.7. Since draft-ietf-quic-qpack-00 1612 o Renumbered instructions for consistency (#1471, #1472) 1614 o Decoder is allowed to validate largest reference (#1404, #1469) 1616 o Header block acknowledgments also acknowledge the associated 1617 largest reference (#1370, #1400) 1619 o Added an acknowledgment for unread streams (#1371, #1400) 1621 o Removed framing from encoder stream (#1361,#1467) 1623 o Control streams use typed unidirectional streams rather than fixed 1624 stream IDs (#910,#1359) 1626 C.8. Since draft-ietf-quic-qcram-00 1628 o Separate instruction sets for table updates and header blocks 1629 (#1235, #1142, #1141) 1631 o Reworked indexing scheme (#1176, #1145, #1136, #1130, #1125, 1632 #1314) 1634 o Added mechanisms that support one-pass encoding (#1138, #1320) 1636 o Added a setting to control the number of blocked decoders (#238, 1637 #1140, #1143) 1639 o Moved table updates and acknowledgments to dedicated streams 1640 (#1121, #1122, #1238) 1642 Acknowledgments 1644 This draft draws heavily on the text of [RFC7541]. The indirect 1645 input of those authors is gratefully acknowledged, as well as ideas 1646 from: 1648 o Ryan Hamilton 1649 o Patrick McManus 1651 o Kazuho Oku 1653 o Biren Roy 1655 o Ian Swett 1657 o Dmitri Tikhonov 1659 Buck's contribution was supported by Google during his employment 1660 there. 1662 A substantial portion of Mike's contribution was supported by 1663 Microsoft during his employment there. 1665 Authors' Addresses 1667 Charles 'Buck' Krasic 1668 Netflix 1670 Email: ckrasic@netflix.com 1672 Mike Bishop 1673 Akamai Technologies 1675 Email: mbishop@evequefou.be 1677 Alan Frindell (editor) 1678 Facebook 1680 Email: afrind@fb.com