idnits 2.17.1 draft-ietf-quic-qpack-06.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 (January 23, 2019) is 1914 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 1222 -- Looks like a reference, but probably isn't: '2' on line 1224 -- Looks like a reference, but probably isn't: '3' on line 1226 == Outdated reference: A later version (-34) exists of draft-ietf-quic-http-18 == Outdated reference: A later version (-34) exists of draft-ietf-quic-transport-17 -- 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: July 27, 2019 Akamai Technologies 6 A. Frindell, Ed. 7 Facebook 8 January 23, 2019 10 QPACK: Header Compression for HTTP over QUIC 11 draft-ietf-quic-qpack-06 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 July 27, 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 . . . . . . . . . . . . . . . . 8 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. Initial Dynamic Table Capacity . . . . . . . . . . . 11 83 3.2.5. Absolute Indexing . . . . . . . . . . . . . . . . . . 11 84 3.2.6. Relative Indexing . . . . . . . . . . . . . . . . . . 11 85 3.2.7. Post-Base Indexing . . . . . . . . . . . . . . . . . 12 86 3.2.8. Invalid References . . . . . . . . . . . . . . . . . 13 87 4. Wire Format . . . . . . . . . . . . . . . . . . . . . . . . . 13 88 4.1. Primitives . . . . . . . . . . . . . . . . . . . . . . . 13 89 4.1.1. Prefixed Integers . . . . . . . . . . . . . . . . . . 13 90 4.1.2. String Literals . . . . . . . . . . . . . . . . . . . 13 91 4.2. Stream Types . . . . . . . . . . . . . . . . . . . . . . 14 92 4.3. Encoder Stream . . . . . . . . . . . . . . . . . . . . . 14 93 4.3.1. Insert With Name Reference . . . . . . . . . . . . . 15 94 4.3.2. Insert Without Name Reference . . . . . . . . . . . . 15 95 4.3.3. Duplicate . . . . . . . . . . . . . . . . . . . . . . 16 96 4.3.4. Set Dynamic Table Capacity . . . . . . . . . . . . . 16 97 4.4. Decoder Stream . . . . . . . . . . . . . . . . . . . . . 17 98 4.4.1. Insert Count Increment . . . . . . . . . . . . . . . 17 99 4.4.2. Header Acknowledgement . . . . . . . . . . . . . . . 18 100 4.4.3. Stream Cancellation . . . . . . . . . . . . . . . . . 18 101 4.5. Request and Push Streams . . . . . . . . . . . . . . . . 19 102 4.5.1. Header Block Prefix . . . . . . . . . . . . . . . . . 19 103 4.5.2. Indexed Header Field . . . . . . . . . . . . . . . . 21 104 4.5.3. Indexed Header Field With Post-Base Index . . . . . . 22 105 4.5.4. Literal Header Field With Name Reference . . . . . . 22 106 4.5.5. Literal Header Field With Post-Base Name Reference . 23 107 4.5.6. Literal Header Field Without Name Reference . . . . . 23 108 5. Configuration . . . . . . . . . . . . . . . . . . . . . . . . 24 109 6. Error Handling . . . . . . . . . . . . . . . . . . . . . . . 24 110 7. Security Considerations . . . . . . . . . . . . . . . . . . . 25 111 8. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 25 112 8.1. Settings Registration . . . . . . . . . . . . . . . . . . 25 113 8.2. Stream Type Registration . . . . . . . . . . . . . . . . 25 114 8.3. Error Code Registration . . . . . . . . . . . . . . . . . 25 115 9. References . . . . . . . . . . . . . . . . . . . . . . . . . 26 116 9.1. Normative References . . . . . . . . . . . . . . . . . . 26 117 9.2. Informative References . . . . . . . . . . . . . . . . . 27 118 9.3. URIs . . . . . . . . . . . . . . . . . . . . . . . . . . 27 119 Appendix A. Static Table . . . . . . . . . . . . . . . . . . . . 27 120 Appendix B. Sample One Pass Encoding Algorithm . . . . . . . . . 32 121 Appendix C. Change Log . . . . . . . . . . . . . . . . . . . . . 34 122 C.1. Since draft-ietf-quic-qpack-05 . . . . . . . . . . . . . 34 123 C.2. Since draft-ietf-quic-qpack-04 . . . . . . . . . . . . . 34 124 C.3. Since draft-ietf-quic-qpack-03 . . . . . . . . . . . . . 34 125 C.4. Since draft-ietf-quic-qpack-02 . . . . . . . . . . . . . 34 126 C.5. Since draft-ietf-quic-qpack-01 . . . . . . . . . . . . . 35 127 C.6. Since draft-ietf-quic-qpack-00 . . . . . . . . . . . . . 35 128 C.7. Since draft-ietf-quic-qcram-00 . . . . . . . . . . . . . 35 129 Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . . . 35 130 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 36 132 1. Introduction 134 The QUIC transport protocol was designed from the outset to support 135 HTTP semantics, and its design subsumes many of the features of 136 HTTP/2. HTTP/2 uses HPACK ([RFC7541]) for header compression, but 137 QUIC's stream multiplexing comes into some conflict with HPACK. A 138 key goal of the design of QUIC is to improve stream multiplexing 139 relative to HTTP/2 by reducing head-of-line blocking. If HPACK were 140 used for HTTP/3, it would induce head-of-line blocking due to built- 141 in assumptions of a total ordering across frames on all streams. 143 QUIC is described in [QUIC-TRANSPORT]. The HTTP/3 mapping is 144 described in [HTTP3]. For a full description of HTTP/2, see 145 [RFC7540]. The description of HPACK is [RFC7541]. 147 QPACK reuses core concepts from HPACK, but is redesigned to allow 148 correctness in the presence of out-of-order delivery, with 149 flexibility for implementations to balance between resilience against 150 head-of-line blocking and optimal compression ratio. The design 151 goals are to closely approach the compression ratio of HPACK with 152 substantially less head-of-line blocking under the same loss 153 conditions. 155 1.1. Conventions and Definitions 157 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 158 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 159 "OPTIONAL" in this document are to be interpreted as described in BCP 160 14 [RFC2119] [RFC8174] when, and only when, they appear in all 161 capitals, as shown here. 163 Definitions of terms that are used in this document: 165 Header field: A name-value pair sent as part of an HTTP message. 167 Header list: An ordered collection of header fields associated with 168 an HTTP message. A header list can contain multiple header fields 169 with the same name. It can also contain duplicate header fields. 171 Header block: The compressed representation of a header list. 173 Encoder: An implementation which transforms a header list into a 174 header block. 176 Decoder: An implementation which transforms a header block into a 177 header list. 179 Absolute Index: A unique index for each entry in the dynamic table. 181 Base: A reference point for relative indicies. Dynamic references 182 are made relative to a Base in header blocks. 184 Insert Count: The total number of entries inserted in the dynamic 185 table. 187 QPACK is a name, not an acronym. 189 1.2. Notational Conventions 191 Diagrams use the format described in Section 3.1 of [RFC2360], with 192 the following additional conventions: 194 x (A) Indicates that x is A bits long 196 x (A+) Indicates that x uses the prefixed integer encoding defined 197 in Section 5.1 of [RFC7541], beginning with an A-bit prefix. 199 x ... Indicates that x is variable-length and extends to the end of 200 the region. 202 2. Compression Process Overview 204 Like HPACK, QPACK uses two tables for associating header fields to 205 indices. The static table (see Section 3.1) is predefined and 206 contains common header fields (some of them with an empty value). 207 The dynamic table (see Section 3.2) is built up over the course of 208 the connection and can be used by the encoder to index header fields 209 in the encoded header lists. 211 QPACK instructions appear in three different types of streams: 213 o The encoder uses a unidirectional stream to modify the state of 214 the dynamic table without emitting header fields associated with 215 any particular request. 217 o HEADERS and PUSH_PROMISE frames on request and push streams 218 reference the table state without modifying it. 220 o The decoder sends feedback to the encoder on a unidirectional 221 stream. This feedback enables the encoder to manage dynamic table 222 state. 224 2.1. Encoder 226 An encoder compresses a header list by emitting either an indexed or 227 a literal representation for each header field in the list. 228 References to the static table and literal representations do not 229 require any dynamic state and never risk head-of-line blocking. 230 References to the dynamic table risk head-of-line blocking if the 231 encoder has not received an acknowledgement indicating the entry is 232 available at the decoder. 234 An encoder MAY insert any entry in the dynamic table it chooses; it 235 is not limited to header fields it is compressing. 237 QPACK preserves the ordering of header fields within each header 238 list. An encoder MUST emit header field representations in the order 239 they appear in the input header list. 241 QPACK is designed to contain the more complex state tracking to the 242 encoder, while the decoder is relatively simple. 244 2.1.1. Reference Tracking 246 An encoder MUST ensure that a header block which references a dynamic 247 table entry is not received by the decoder after the referenced entry 248 has been evicted. Hence the encoder needs to track information about 249 each compressed header block that references the dynamic table until 250 that header block is acknowledged by the decoder. 252 2.1.2. Blocked Dynamic Table Insertions 254 An encoder MUST NOT insert an entry into the dynamic table (or 255 duplicate an existing entry) if doing so would evict an entry with 256 unacknowledged references. For header blocks that might rely on the 257 newly added entry, the encoder can use a literal representation. 259 To ensure that the encoder is not prevented from adding new entries, 260 the encoder can avoid referencing entries that are close to eviction. 261 Rather than reference such an entry, the encoder can emit a Duplicate 262 instruction (see Section 4.3.3), and reference the duplicate instead. 264 Determining which entries are too close to eviction to reference is 265 an encoder preference. One heuristic is to target a fixed amount of 266 available space in the dynamic table: either unused space or space 267 that can be reclaimed by evicting unreferenced entries. To achieve 268 this, the encoder can maintain a draining index, which is the 269 smallest absolute index in the dynamic table that it will emit a 270 reference for. As new entries are inserted, the encoder increases 271 the draining index to maintain the section of the table that it will 272 not reference. If the encoder does not create new references to 273 entries with an absolute index lower than the draining index, the 274 number of unacknowledged references to those entries will eventually 275 become zero, allowing them to be evicted. 277 +----------+---------------------------------+--------+ 278 | Draining | Referenceable | Unused | 279 | Entries | Entries | Space | 280 +----------+---------------------------------+--------+ 281 ^ ^ ^ 282 | | | 283 Dropping Draining Index Insertion Point 284 Point 286 Figure 1: Draining Dynamic Table Entries 288 2.1.3. Avoiding Head-of-Line Blocking 290 Because QUIC does not guarantee order between data on different 291 streams, a header block might reference an entry in the dynamic table 292 that has not yet been received. 294 Each header block contains a Required Insert Count, the lowest 295 possible value for the Insert Count with which the header block can 296 be decoded. For a header block with no references to the dynamic 297 table, the Required Insert Count is zero. 299 When the Required Insert Count is zero, the frame contains no 300 references to the dynamic table and can always be processed 301 immediately. 303 If the Required Insert Count is greater than the number of dynamic 304 table entries received, the stream is considered "blocked." While 305 blocked, header field data SHOULD remain in the blocked stream's flow 306 control window. A stream becomes unblocked when the Insert Count 307 becomes greater than or equal to the Required Insert Count for all 308 header blocks the decoder has started reading from the stream. 310 If the decoder encounters a header block where the largest Absolute 311 Index used is not equal to the largest value permitted by the 312 Required Insert Count, it MAY treat this as a stream error of type 313 HTTP_QPACK_DECOMPRESSION_FAILED. 315 The SETTINGS_QPACK_BLOCKED_STREAMS setting (see Section 5) specifies 316 an upper bound on the number of streams which can be blocked. An 317 encoder MUST limit the number of streams which could become blocked 318 to the value of SETTINGS_QPACK_BLOCKED_STREAMS at all times. Note 319 that the decoder might not actually become blocked on every stream 320 which risks becoming blocked. If the decoder encounters more blocked 321 streams than it promised to support, it MUST treat this as a stream 322 error of type HTTP_QPACK_DECOMPRESSION_FAILED. 324 An encoder can decide whether to risk having a stream become blocked. 325 If permitted by the value of SETTINGS_QPACK_BLOCKED_STREAMS, 326 compression efficiency can often be improved by referencing dynamic 327 table entries that are still in transit, but if there is loss or 328 reordering the stream can become blocked at the decoder. An encoder 329 avoids the risk of blocking by only referencing dynamic table entries 330 which have been acknowledged, but this could mean using literals. 331 Since literals make the header block larger, this can result in the 332 encoder becoming blocked on congestion or flow control limits. 334 2.1.4. Known Received Count 336 In order to identify which dynamic table entries can be safely used 337 without a stream becoming blocked, the encoder tracks the number of 338 entries received by the decoder. The Known Received Count tracks the 339 total number of acknowledged insertions. 341 When blocking references are permitted, the encoder uses header block 342 acknowledgement to maintain the Known Received Count, as described in 343 Section 4.4.2. 345 To acknowledge dynamic table entries which are not referenced by 346 header blocks, for example because the encoder or the decoder have 347 chosen not to risk blocked streams, the decoder sends an Insert Count 348 Increment instruction (see Section 4.4.1). 350 2.2. Decoder 352 As in HPACK, the decoder processes header blocks and emits the 353 corresponding header lists. It also processes dynamic table 354 modifications from instructions on the encoder stream. 356 The decoder MUST emit header fields in the order their 357 representations appear in the input header block. 359 2.2.1. State Synchronization 361 The decoder stream (Section 4.4) signals key events at the decoder 362 that permit the encoder to track the decoder's state. These events 363 are: 365 o Complete processing of a header block 367 o Abandonment of a stream which might have remaining header blocks 369 o Receipt of new dynamic table entries 370 Knowledge that a header block with references to the dynamic table 371 has been processed permits the encoder to evict entries to which no 372 unacknowledged references remain, regardless of whether those 373 references were potentially blocking (see Section 2.1.2). When a 374 stream is reset or abandoned, the indication that these header blocks 375 will never be processed serves a similar function; see Section 4.4.3. 377 The decoder chooses when to emit Insert Count Increment instructions 378 (see Section 4.4.1). Emitting an instruction after adding each new 379 dynamic table entry will provide the most timely feedback to the 380 encoder, but could be redundant with other decoder feedback. By 381 delaying an Insert Count Increment instruction, the decoder might be 382 able to coalesce multiple Insert Count Increment instructions, or 383 replace them entirely with Header Acknowledgements (see 384 Section 4.4.2). However, delaying too long may lead to compression 385 inefficiencies if the encoder waits for an entry to be acknowledged 386 before using it. 388 2.2.2. Blocked Decoding 390 To track blocked streams, the Required Insert Count value for each 391 stream can be used. Whenever the decoder processes a table update, 392 it can begin decoding any blocked streams that now have their 393 dependencies satisfied. 395 3. Header Tables 397 Unlike in HPACK, entries in the QPACK static and dynamic tables are 398 addressed separately. The following sections describe how entries in 399 each table are addressed. 401 3.1. Static Table 403 The static table consists of a predefined static list of header 404 fields, each of which has a fixed index over time. Its entries are 405 defined in Appendix A. 407 Note the QPACK static table is indexed from 0, whereas the HPACK 408 static table is indexed from 1. 410 When the decoder encounters an invalid static table index on a 411 request stream or push stream it MUST treat this as a stream error of 412 type "HTTP_QPACK_DECOMPRESSION_FAILED". If this index is received on 413 the encoder stream, this MUST be treated as a connection error of 414 type "HTTP_QPACK_ENCODER_STREAM_ERROR". 416 3.2. Dynamic Table 418 The dynamic table consists of a list of header fields maintained in 419 first-in, first-out order. The dynamic table is initially empty. 420 Entries are added by instructions on the encoder stream (see 421 Section 4.3). 423 The dynamic table can contain duplicate entries (i.e., entries with 424 the same name and same value). Therefore, duplicate entries MUST NOT 425 be treated as an error by the decoder. 427 3.2.1. Dynamic Table Size 429 The size of the dynamic table is the sum of the size of its entries. 431 The size of an entry is the sum of its name's length in bytes (as 432 defined in Section 4.1.2), its value's length in bytes, and 32. 434 The size of an entry is calculated using the length of its name and 435 value without Huffman encoding applied. 437 3.2.2. Dynamic Table Capacity and Eviction 439 The encoder sets the capacity of the dynamic table, which serves as 440 the upper limit on its size. 442 Before a new entry is added to the dynamic table, entries are evicted 443 from the end of the dynamic table until the size of the dynamic table 444 is less than or equal to (table capacity - size of new entry) or 445 until the table is empty. The encoder MUST NOT evict a dynamic table 446 entry unless it has first been acknowledged by the decoder. 448 If the size of the new entry is less than or equal to the dynamic 449 table capacity, then that entry is added to the table. It is an 450 error if the encoder attempts to add an entry that is larger than the 451 dynamic table capacity; the decoder MUST treat this as a connection 452 error of type "HTTP_QPACK_ENCODER_STREAM_ERROR". 454 A new entry can reference an entry in the dynamic table that will be 455 evicted when adding this new entry into the dynamic table. 456 Implementations are cautioned to avoid deleting the referenced name 457 or value if the referenced entry is evicted from the dynamic table 458 prior to inserting the new entry. 460 Whenever the dynamic table capacity is reduced by the encoder, 461 entries are evicted from the end of the dynamic table until the size 462 of the dynamic table is less than or equal to the new table capacity. 463 This mechanism can be used to completely clear entries from the 464 dynamic table by setting a capacity of 0, which can subsequently be 465 restored. 467 3.2.3. Maximum Dynamic Table Capacity 469 To bound the memory requirements of the decoder, the decoder limits 470 the maximum value the encoder is permitted to set for the dynamic 471 table capacity. In HTTP/3, this limit is determined by the value of 472 SETTINGS_QPACK_MAX_TABLE_CAPACITY sent by the decoder (see 473 Section 5). The encoder MUST not set a dynamic table capacity that 474 exceeds this maximum, but it can choose to use a lower dynamic table 475 capacity (see Section 4.3.4). 477 3.2.4. Initial Dynamic Table Capacity 479 The initial dynamic table capacity is determined by the corresponding 480 setting when HTTP requests or responses are first permitted to be 481 sent. For clients using 0-RTT data in HTTP/3, the initial table 482 capacity is the remembered value of the setting, even if the server 483 later specifies a larger maximum dynamic table capacity in its 484 SETTINGS frame. For HTTP/3 servers and HTTP/3 clients when 0-RTT is 485 not attempted or is rejected, the initial table capacity is the value 486 of the setting in the peer's SETTINGS frame. 488 3.2.5. Absolute Indexing 490 Each entry possesses both an absolute index which is fixed for the 491 lifetime of that entry and a relative index which changes based on 492 the context of the reference. The first entry inserted has an 493 absolute index of "0"; indices increase by one with each insertion. 495 3.2.6. Relative Indexing 497 The relative index begins at zero and increases in the opposite 498 direction from the absolute index. Determining which entry has a 499 relative index of "0" depends on the context of the reference. 501 On the encoder stream, a relative index of "0" always refers to the 502 most recently inserted value in the dynamic table. Note that this 503 means the entry referenced by a given relative index will change 504 while interpreting instructions on the encoder stream. 506 +-----+---------------+-------+ 507 | n-1 | ... | d | Absolute Index 508 + - - +---------------+ - - - + 509 | 0 | ... | n-d-1 | Relative Index 510 +-----+---------------+-------+ 511 ^ | 512 | V 513 Insertion Point Dropping Point 515 n = count of entries inserted 516 d = count of entries dropped 518 Example Dynamic Table Indexing - Control Stream 520 Unlike on the encoder stream, relative indices on push and request 521 streams are relative to the Base at the beginning of the header block 522 (see Section 4.5.1). This ensures that references are stable even if 523 the dynamic table is updated while decoding a header block. 525 The Base is encoded as a value relative to the Required Insert Count. 526 The Base identifies which dynamic table entries can be referenced 527 using relative indexing, starting with 0 at the last entry added. 529 Post-Base references are used for entries inserted after base, 530 starting at 0 for the first entry added after the Base, see 531 Section 3.2.7. 533 Required 534 Insert 535 Count Base 536 | | 537 V V 538 +-----+-----+-----+-----+-------+ 539 | n-1 | n-2 | n-3 | ... | d | Absolute Index 540 +-----+-----+ - +-----+ - + 541 | 0 | ... | n-d-3 | Relative Index 542 +-----+-----+-------+ 544 n = count of entries inserted 545 d = count of entries dropped 547 Example Dynamic Table Indexing - Relative Index on Request Stream 549 3.2.7. Post-Base Indexing 551 A header block on the request stream can reference entries added 552 after the entry identified by the Base. This allows an encoder to 553 process a header block in a single pass and include references to 554 entries added while processing this (or other) header blocks. Newly 555 added entries are referenced using Post-Base instructions. Indices 556 for Post-Base instructions increase in the same direction as absolute 557 indices, with the zero value being the first entry inserted after the 558 Base. 560 Base 561 | 562 V 563 +-----+-----+-----+-----+-----+ 564 | n-1 | n-2 | n-3 | ... | d | Absolute Index 565 +-----+-----+-----+-----+-----+ 566 | 1 | 0 | Post-Base Index 567 +-----+-----+ 569 n = count of entries inserted 570 d = count of entries dropped 572 Example Dynamic Table Indexing - Post-Base Index on Request Stream 574 3.2.8. Invalid References 576 If the decoder encounters a reference on a request or push stream to 577 a dynamic table entry which has already been evicted or which has an 578 absolute index greater than or equal to the declared Required Insert 579 Count (see Section 4.5.1), it MUST treat this as a stream error of 580 type "HTTP_QPACK_DECOMPRESSION_FAILED". 582 If the decoder encounters a reference on the encoder stream to a 583 dynamic table entry which has already been dropped, it MUST treat 584 this as a connection error of type "HTTP_QPACK_ENCODER_STREAM_ERROR". 586 4. Wire Format 588 4.1. Primitives 590 4.1.1. Prefixed Integers 592 The prefixed integer from Section 5.1 of [RFC7541] is used heavily 593 throughout this document. The format from [RFC7541] is used 594 unmodified. QPACK implementations MUST be able to decode integers up 595 to 62 bits long. 597 4.1.2. String Literals 599 The string literal defined by Section 5.2 of [RFC7541] is also used 600 throughout. This string format includes optional Huffman encoding. 602 HPACK defines string literals to begin on a byte boundary. They 603 begin with a single flag (indicating whether the string is Huffman- 604 coded), followed by the Length encoded as a 7-bit prefix integer, and 605 finally Length bytes of data. When Huffman encoding is enabled, the 606 Huffman table from Appendix B of [RFC7541] is used without 607 modification. 609 This document expands the definition of string literals and permits 610 them to begin other than on a byte boundary. An "N-bit prefix string 611 literal" begins with the same Huffman flag, followed by the length 612 encoded as an (N-1)-bit prefix integer. The remainder of the string 613 literal is unmodified. 615 A string literal without a prefix length noted is an 8-bit prefix 616 string literal and follows the definitions in [RFC7541] without 617 modification. 619 4.2. Stream Types 621 QPACK instructions occur in three locations, each of which uses a 622 separate instruction space: 624 o The encoder stream is a unidirectional stream of type "0x48" 625 (ASCII 'H') which carries table updates from encoder to decoder. 627 o The decoder stream is a unidirectional stream of type "0x68" 628 (ASCII 'h') which carries acknowledgements of table modifications 629 and header processing from decoder to encoder. 631 o Finally, the contents of HEADERS and PUSH_PROMISE frames on 632 request streams and push streams reference the QPACK table state. 634 There MUST be exactly one of each unidirectional stream type in each 635 direction. Receipt of a second instance of either stream type MUST 636 be treated as a connection error of HTTP_WRONG_STREAM_COUNT. These 637 streams MUST NOT be closed. Closure of either unidirectional stream 638 MUST be treated as a connection error of type 639 HTTP_CLOSED_CRITICAL_STREAM. 641 This section describes the instructions which are possible on each 642 stream type. 644 4.3. Encoder Stream 646 Table updates can add a table entry, possibly using existing entries 647 to avoid transmitting redundant information. The name can be 648 transmitted as a reference to an existing entry in the static or the 649 dynamic table or as a string literal. For entries which already 650 exist in the dynamic table, the full entry can also be used by 651 reference, creating a duplicate entry. 653 The contents of the encoder stream are an unframed sequence of the 654 following instructions. 656 4.3.1. Insert With Name Reference 658 An addition to the header table where the header field name matches 659 the header field name of an entry stored in the static table or the 660 dynamic table starts with the '1' one-bit pattern. The "S" bit 661 indicates whether the reference is to the static (S=1) or dynamic 662 (S=0) table. The 6-bit prefix integer (see Section 5.1 of [RFC7541]) 663 that follows is used to locate the table entry for the header name. 664 When S=1, the number represents the static table index; when S=0, the 665 number is the relative index of the entry in the dynamic table. 667 The header name reference is followed by the header field value 668 represented as a string literal (see Section 5.2 of [RFC7541]). 670 0 1 2 3 4 5 6 7 671 +---+---+---+---+---+---+---+---+ 672 | 1 | S | Name Index (6+) | 673 +---+---+-----------------------+ 674 | H | Value Length (7+) | 675 +---+---------------------------+ 676 | Value String (Length bytes) | 677 +-------------------------------+ 679 Insert Header Field -- Indexed Name 681 4.3.2. Insert Without Name Reference 683 An addition to the header table where both the header field name and 684 the header field value are represented as string literals (see 685 Section 4.1) starts with the '01' two-bit pattern. 687 The name is represented as a 6-bit prefix string literal, while the 688 value is represented as an 8-bit prefix string literal. 690 0 1 2 3 4 5 6 7 691 +---+---+---+---+---+---+---+---+ 692 | 0 | 1 | H | Name Length (5+) | 693 +---+---+---+-------------------+ 694 | Name String (Length bytes) | 695 +---+---------------------------+ 696 | H | Value Length (7+) | 697 +---+---------------------------+ 698 | Value String (Length bytes) | 699 +-------------------------------+ 701 Insert Header Field -- New Name 703 4.3.3. Duplicate 705 Duplication of an existing entry in the dynamic table starts with the 706 '000' three-bit pattern. The relative index of the existing entry is 707 represented as an integer with a 5-bit prefix. 709 0 1 2 3 4 5 6 7 710 +---+---+---+---+---+---+---+---+ 711 | 0 | 0 | 0 | Index (5+) | 712 +---+---+---+-------------------+ 714 Figure 2: Duplicate 716 The existing entry is re-inserted into the dynamic table without 717 resending either the name or the value. This is useful to mitigate 718 the eviction of older entries which are frequently referenced, both 719 to avoid the need to resend the header and to avoid the entry in the 720 table blocking the ability to insert new headers. 722 4.3.4. Set Dynamic Table Capacity 724 An encoder informs the decoder of a change to the dynamic table 725 capacity using an instruction which begins with the '001' three-bit 726 pattern. The new dynamic table capacity is represented as an integer 727 with a 5-bit prefix (see Section 5.1 of [RFC7541]). 729 0 1 2 3 4 5 6 7 730 +---+---+---+---+---+---+---+---+ 731 | 0 | 0 | 1 | Capacity (5+) | 732 +---+---+---+-------------------+ 734 Figure 3: Set Dynamic Table Capacity 736 The new capacity MUST be lower than or equal to the limit described 737 in Section 3.2.3. In HTTP/3, this limit is the value of the 738 SETTINGS_QPACK_MAX_TABLE_CAPACITY parameter (see Section 5) received 739 from the decoder. The decoder MUST treat a new dynamic table 740 capacity value that exceeds this limit as a connection error of type 741 "HTTP_QPACK_ENCODER_STREAM_ERROR". 743 Reducing the dynamic table capacity can cause entries to be evicted 744 (see Section 3.2.2). This MUST NOT cause the eviction of entries 745 with outstanding references (see Section 2.1.1). Changing the 746 capacity of the dynamic table is not acknowledged as this instruction 747 does not insert an entry. 749 4.4. Decoder Stream 751 The decoder stream carries information used to ensure consistency of 752 the dynamic table. Information is sent from the decoder to the 753 encoder; that is, the server informs the client about the processing 754 of the client's header blocks and table updates, and the client 755 informs the server about the processing of the server's header blocks 756 and table updates. 758 The contents of the decoder stream are an unframed sequence of the 759 following instructions. 761 4.4.1. Insert Count Increment 763 The Insert Count Increment instruction begins with the '00' two-bit 764 pattern. The instruction specifies the total number of dynamic table 765 inserts and duplications since the last Insert Count Increment or 766 Header Acknowledgement that increased the Known Received Count for 767 the dynamic table (see Section 2.1.4). The Increment field is 768 encoded as a 6-bit prefix integer. The encoder uses this value to 769 determine which table entries might cause a stream to become blocked, 770 as described in Section 2.2.1. 772 0 1 2 3 4 5 6 7 773 +---+---+---+---+---+---+---+---+ 774 | 0 | 0 | Increment (6+) | 775 +---+---+-----------------------+ 777 Figure 4: Insert Count Increment 779 An encoder that receives an Increment field equal to zero or one that 780 increases the Known Received Count beyond what the encoder has sent 781 MUST treat this as a connection error of type 782 "HTTP_QPACK_DECODER_STREAM_ERROR". 784 4.4.2. Header Acknowledgement 786 After processing a header block whose declared Required Insert Count 787 is not zero, the decoder emits a Header Acknowledgement instruction 788 on the decoder stream. The instruction begins with the '1' one-bit 789 pattern and includes the request stream's stream ID, encoded as a 790 7-bit prefix integer. It is used by the peer's encoder to know when 791 it is safe to evict an entry, and possibly update the Known Received 792 Count. 794 0 1 2 3 4 5 6 7 795 +---+---+---+---+---+---+---+---+ 796 | 1 | Stream ID (7+) | 797 +---+---------------------------+ 799 Figure 5: Header Acknowledgement 801 The same Stream ID can be identified multiple times, as multiple 802 header blocks can be sent on a single stream in the case of 803 intermediate responses, trailers, and pushed requests. Since header 804 frames on each stream are received and processed in order, this gives 805 the encoder precise feedback on which header blocks within a stream 806 have been fully processed. 808 If an encoder receives a Header Acknowledgement instruction referring 809 to a stream on which every header block with a non-zero Required 810 Insert Count has already been acknowledged, that MUST be treated as a 811 connection error of type "HTTP_QPACK_DECODER_STREAM_ERROR". 813 When blocking references are permitted, the encoder uses 814 acknowledgement of header blocks to update the Known Received Count. 815 If a header block was potentially blocking, the acknowledgement 816 implies that the decoder has received all dynamic table state 817 necessary to process the header block. If the Required Insert Count 818 of an acknowledged header block was greater than the encoder's 819 current Known Received Count, the block's Required Insert Count 820 becomes the new Known Received Count. 822 4.4.3. Stream Cancellation 824 The instruction begins with the '01' two-bit pattern. The 825 instruction includes the stream ID of the affected stream - a request 826 or push stream - encoded as a 6-bit prefix integer. 828 0 1 2 3 4 5 6 7 829 +---+---+---+---+---+---+---+---+ 830 | 0 | 1 | Stream ID (6+) | 831 +---+---+-----------------------+ 833 Figure 6: Stream Cancellation 835 A stream that is reset might have multiple outstanding header blocks 836 with dynamic table references. When an endpoint receives a stream 837 reset before the end of a stream, it generates a Stream Cancellation 838 instruction on the decoder stream. Similarly, when an endpoint 839 abandons reading of a stream it needs to signal this using the Stream 840 Cancellation instruction. This signals to the encoder that all 841 references to the dynamic table on that stream are no longer 842 outstanding. A decoder with a maximum dynamic table capacity equal 843 to zero (see Section 3.2.3) MAY omit sending Stream Cancellations, 844 because the encoder cannot have any dynamic table references. 846 An encoder cannot infer from this instruction that any updates to the 847 dynamic table have been received. 849 4.5. Request and Push Streams 851 HEADERS and PUSH_PROMISE frames on request and push streams reference 852 the dynamic table in a particular state without modifying it. Frames 853 on these streams emit the headers for an HTTP request or response. 855 4.5.1. Header Block Prefix 857 Each header block is prefixed with two integers. The Required Insert 858 Count is encoded as an integer with an 8-bit prefix after the 859 encoding described in Section 4.5.1.1). The Base is encoded as sign- 860 and-modulus integer, using a single sign bit and a value with a 7-bit 861 prefix (see Section 4.5.1.2). 863 These two values are followed by instructions for compressed headers. 864 The entire block is expected to be framed by the using protocol. 866 0 1 2 3 4 5 6 7 867 +---+---+---+---+---+---+---+---+ 868 | Required Insert Count (8+) | 869 +---+---------------------------+ 870 | S | Delta Base (7+) | 871 +---+---------------------------+ 872 | Compressed Headers ... 873 +-------------------------------+ 875 Figure 7: Frame Payload 877 4.5.1.1. Required Insert Count 879 Required Insert Count identifies the state of the dynamic table 880 needed to process the header block. Blocking decoders use the 881 Required Insert Count to determine when it is safe to process the 882 rest of the block. 884 If no references are made to the dynamic table, a value of 0 is 885 encoded. Alternatively, where the Required Insert Count is greater 886 than zero, the encoder transforms it as follows before encoding: 888 EncodedInsertCount = (ReqInsertCount mod (2 * MaxEntries)) + 1 890 Here "MaxEntries" is the maximum number of entries that the dynamic 891 table can have. The smallest entry has empty name and value strings 892 and has the size of 32. Hence "MaxEntries" is calculated as 894 MaxEntries = floor( MaxTableCapacity / 32 ) 896 "MaxTableCapacity" is the maximum capacity of the dynamic table as 897 specified by the decoder (see Section 3.2.3). 899 The decoder reconstructs the Required Insert Count using the 900 following algorithm, where TotalNumberOfInserts is the total number 901 of inserts into the decoder's dynamic table: 903 if EncodedInsertCount == 0: 904 ReqInsertCount = 0 905 else: 906 InsertCount = EncodedInsertCount - 1 907 CurrentWrapped = TotalNumberOfInserts mod (2 * MaxEntries) 909 if CurrentWrapped >= InsertCount + MaxEntries: 910 # Insert Count wrapped around 1 extra time 911 ReqInsertCount += 2 * MaxEntries 912 else if CurrentWrapped + MaxEntries < InsertCount: 913 # Decoder wrapped around 1 extra time 914 CurrentWrapped += 2 * MaxEntries 916 ReqInsertCount += TotalNumberOfInserts - CurrentWrapped 918 This encoding limits the length of the prefix on long-lived 919 connections. 921 For example, if the dynamic table is 100 bytes, then the Required 922 Insert Count will be encoded modulo 6. If a decoder has received 10 923 inserts, then an encoded value of 3 indicates that the Required 924 Insert Count is 9 for the header block. 926 4.5.1.2. Base 928 The "Base" is used to resolve references in the dynamic table as 929 described in Section 3.2.6. 931 To save space, the Base is encoded relative to the Insert Count using 932 a one-bit sign and the "Delta Base" value. A sign bit of 0 indicates 933 that the Base is greater than or equal to the value of the Insert 934 Count; the value of Delta Base is added to the Insert Count to 935 determine the value of the Base. A sign bit of 1 indicates that the 936 Base is less than the Insert Count. That is: 938 if S == 0: 939 Base = ReqInsertCount + DeltaBase 940 else: 941 Base = ReqInsertCount - DeltaBase - 1 943 A single-pass encoder determines the Base before encoding a header 944 block. If the encoder inserted entries in the dynamic table while 945 encoding the header block, Required Insert Count will be greater than 946 the Base, so the encoded difference is negative and the sign bit is 947 set to 1. If the header block did not reference the most recent 948 entry in the table and did not insert any new entries, the Base will 949 be greater than the Required Insert Count, so the delta will be 950 positive and the sign bit is set to 0. 952 An encoder that produces table updates before encoding a header block 953 might set Required Insert Count and the Base to the same value. In 954 such case, both the sign bit and the Delta Base will be set to zero. 956 A header block that does not reference the dynamic table can use any 957 value for the Base; setting Delta Base to zero is the most efficient 958 encoding. 960 For example, with an Required Insert Count of 9, a decoder receives a 961 S bit of 1 and a Delta Base of 2. This sets the Base to 6 and 962 enables post-base indexing for three entries. In this example, a 963 regular index of 1 refers to the 5th entry that was added to the 964 table; a post-base index of 1 refers to the 8th entry. 966 4.5.2. Indexed Header Field 968 An indexed header field representation identifies an entry in either 969 the static table or the dynamic table and causes that header field to 970 be added to the decoded header list, as described in Section 3.2 of 971 [RFC7541]. 973 0 1 2 3 4 5 6 7 974 +---+---+---+---+---+---+---+---+ 975 | 1 | S | Index (6+) | 976 +---+---+-----------------------+ 978 Indexed Header Field 980 If the entry is in the static table, or in the dynamic table with an 981 absolute index less than the Base, this representation starts with 982 the '1' 1-bit pattern, followed by the "S" bit indicating whether the 983 reference is into the static (S=1) or dynamic (S=0) table. Finally, 984 the relative index of the matching header field is represented as an 985 integer with a 6-bit prefix (see Section 5.1 of [RFC7541]). 987 4.5.3. Indexed Header Field With Post-Base Index 989 If the entry is in the dynamic table with an absolute index greater 990 than or equal to the Base, the representation starts with the '0001' 991 4-bit pattern, followed by the post-base index (see Section 3.2.7) of 992 the matching header field, represented as an integer with a 4-bit 993 prefix (see Section 5.1 of [RFC7541]). 995 0 1 2 3 4 5 6 7 996 +---+---+---+---+---+---+---+---+ 997 | 0 | 0 | 0 | 1 | Index (4+) | 998 +---+---+---+---+---------------+ 1000 Indexed Header Field with Post-Base Index 1002 4.5.4. Literal Header Field With Name Reference 1004 A literal header field with a name reference represents a header 1005 where the header field name matches the header field name of an entry 1006 stored in the static table or the dynamic table. 1008 If the entry is in the static table, or in the dynamic table with an 1009 absolute index less than the Base, this representation starts with 1010 the '01' two-bit pattern. If the entry is in the dynamic table with 1011 an absolute index greater than or equal to the Base, the 1012 representation starts with the '0000' four-bit pattern. 1014 The following bit, 'N', indicates whether an intermediary is 1015 permitted to add this header to the dynamic header table on 1016 subsequent hops. When the 'N' bit is set, the encoded header MUST 1017 always be encoded with a literal representation. In particular, when 1018 a peer sends a header field that it received represented as a literal 1019 header field with the 'N' bit set, it MUST use a literal 1020 representation to forward this header field. This bit is intended 1021 for protecting header field values that are not to be put at risk by 1022 compressing them (see Section 7.1 of [RFC7541] for more details). 1024 0 1 2 3 4 5 6 7 1025 +---+---+---+---+---+---+---+---+ 1026 | 0 | 1 | N | S |Name Index (4+)| 1027 +---+---+---+---+---------------+ 1028 | H | Value Length (7+) | 1029 +---+---------------------------+ 1030 | Value String (Length bytes) | 1031 +-------------------------------+ 1033 Literal Header Field With Name Reference 1035 For entries in the static table or in the dynamic table with an 1036 absolute index less than the Base, the header field name is 1037 represented using the relative index of that entry, which is 1038 represented as an integer with a 4-bit prefix (see Section 5.1 of 1039 [RFC7541]). The "S" bit indicates whether the reference is to the 1040 static (S=1) or dynamic (S=0) table. 1042 4.5.5. Literal Header Field With Post-Base Name Reference 1044 For entries in the dynamic table with an absolute index greater than 1045 or equal to the Base, the header field name is represented using the 1046 post-base index of that entry (see Section 3.2.7) encoded as an 1047 integer with a 3-bit prefix. 1049 0 1 2 3 4 5 6 7 1050 +---+---+---+---+---+---+---+---+ 1051 | 0 | 0 | 0 | 0 | N |NameIdx(3+)| 1052 +---+---+---+---+---+-----------+ 1053 | H | Value Length (7+) | 1054 +---+---------------------------+ 1055 | Value String (Length bytes) | 1056 +-------------------------------+ 1058 Literal Header Field With Post-Base Name Reference 1060 4.5.6. Literal Header Field Without Name Reference 1062 An addition to the header table where both the header field name and 1063 the header field value are represented as string literals (see 1064 Section 4.1) starts with the '001' three-bit pattern. 1066 The fourth bit, 'N', indicates whether an intermediary is permitted 1067 to add this header to the dynamic header table on subsequent hops. 1068 When the 'N' bit is set, the encoded header MUST always be encoded 1069 with a literal representation. In particular, when a peer sends a 1070 header field that it received represented as a literal header field 1071 with the 'N' bit set, it MUST use a literal representation to forward 1072 this header field. This bit is intended for protecting header field 1073 values that are not to be put at risk by compressing them (see 1074 Section 7.1 of [RFC7541] for more details). 1076 The name is represented as a 4-bit prefix string literal, while the 1077 value is represented as an 8-bit prefix string literal. 1079 0 1 2 3 4 5 6 7 1080 +---+---+---+---+---+---+---+---+ 1081 | 0 | 0 | 1 | N | H |NameLen(3+)| 1082 +---+---+---+---+---+-----------+ 1083 | Name String (Length bytes) | 1084 +---+---------------------------+ 1085 | H | Value Length (7+) | 1086 +---+---------------------------+ 1087 | Value String (Length bytes) | 1088 +-------------------------------+ 1090 Literal Header Field Without Name Reference 1092 5. Configuration 1094 QPACK defines two settings which are included in the HTTP/3 SETTINGS 1095 frame. 1097 SETTINGS_QPACK_MAX_TABLE_CAPACITY (0x1): An integer with a maximum 1098 value of 2^30 - 1. The default value is zero bytes. See 1099 Section 3.2 for usage. This is the equivalent of the 1100 SETTINGS_HEADER_TABLE_SIZE from HTTP/2. 1102 SETTINGS_QPACK_BLOCKED_STREAMS (0x7): An integer with a maximum 1103 value of 2^16 - 1. The default value is zero. See Section 2.1.3. 1105 6. Error Handling 1107 The following error codes are defined for HTTP/3 to indicate failures 1108 of QPACK which prevent the stream or connection from continuing: 1110 HTTP_QPACK_DECOMPRESSION_FAILED (TBD): The decoder failed to 1111 interpret an instruction on a request or push stream and is not 1112 able to continue decoding that header block. 1114 HTTP_QPACK_ENCODER_STREAM_ERROR (TBD): The decoder failed to 1115 interpret an instruction on the encoder stream. 1117 HTTP_QPACK_DECODER_STREAM_ERROR (TBD): The encoder failed to 1118 interpret an instruction on the decoder stream. 1120 Upon encountering an error, an implementation MAY elect to treat it 1121 as a connection error even if this document prescribes that it MUST 1122 be treated as a stream error. 1124 7. Security Considerations 1126 TBD. 1128 8. IANA Considerations 1130 8.1. Settings Registration 1132 This document creates two new settings in the "HTTP/3 Settings" 1133 registry established in [HTTP3]. 1135 The entries in the following table are registered by this document. 1137 +--------------------------+------+---------------+ 1138 | Setting Name | Code | Specification | 1139 +--------------------------+------+---------------+ 1140 | QPACK_MAX_TABLE_CAPACITY | 0x1 | Section 5 | 1141 | | | | 1142 | QPACK_BLOCKED_STREAMS | 0x7 | Section 5 | 1143 +--------------------------+------+---------------+ 1145 8.2. Stream Type Registration 1147 This document creates two new settings in the "HTTP/3 Stream Type" 1148 registry established in [HTTP3]. 1150 The entries in the following table are registered by this document. 1152 +----------------------+------+---------------+--------+ 1153 | Stream Type | Code | Specification | Sender | 1154 +----------------------+------+---------------+--------+ 1155 | QPACK Encoder Stream | 0x48 | Section 4 | Both | 1156 | | | | | 1157 | QPACK Decoder Stream | 0x68 | Section 4 | Both | 1158 +----------------------+------+---------------+--------+ 1160 8.3. Error Code Registration 1162 This document establishes the following new error codes in the 1163 "HTTP/3 Error Code" registry established in [HTTP3]. 1165 +------------------------------+------+--------------+--------------+ 1166 | Name | Code | Description | Specificatio | 1167 | | | | n | 1168 +------------------------------+------+--------------+--------------+ 1169 | HTTP_QPACK_DECOMPRESSION_FAI | TBD | Decompressio | Section 6 | 1170 | LED | | n of a | | 1171 | | | header block | | 1172 | | | failed | | 1173 | | | | | 1174 | HTTP_QPACK_ENCODER_STREAM_ER | TBD | Error on the | Section 6 | 1175 | ROR | | encoder | | 1176 | | | stream | | 1177 | | | | | 1178 | HTTP_QPACK_DECODER_STREAM_ER | TBD | Error on the | Section 6 | 1179 | ROR | | decoder | | 1180 | | | stream | | 1181 +------------------------------+------+--------------+--------------+ 1183 9. References 1185 9.1. Normative References 1187 [HTTP3] Bishop, M., Ed., "Hypertext Transfer Protocol Version 3 1188 (HTTP/3)", draft-ietf-quic-http-18 (work in progress), 1189 January 2019. 1191 [QUIC-TRANSPORT] 1192 Iyengar, J., Ed. and M. Thomson, Ed., "QUIC: A UDP-Based 1193 Multiplexed and Secure Transport", draft-ietf-quic- 1194 transport-17 (work in progress), January 2019. 1196 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1197 Requirement Levels", BCP 14, RFC 2119, 1198 DOI 10.17487/RFC2119, March 1997, 1199 . 1201 [RFC7541] Peon, R. and H. Ruellan, "HPACK: Header Compression for 1202 HTTP/2", RFC 7541, DOI 10.17487/RFC7541, May 2015, 1203 . 1205 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 1206 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 1207 May 2017, . 1209 9.2. Informative References 1211 [RFC2360] Scott, G., "Guide for Internet Standards Writers", BCP 22, 1212 RFC 2360, DOI 10.17487/RFC2360, June 1998, 1213 . 1215 [RFC7540] Belshe, M., Peon, R., and M. Thomson, Ed., "Hypertext 1216 Transfer Protocol Version 2 (HTTP/2)", RFC 7540, 1217 DOI 10.17487/RFC7540, May 2015, 1218 . 1220 9.3. URIs 1222 [1] https://mailarchive.ietf.org/arch/search/?email_list=quic 1224 [2] https://github.com/quicwg 1226 [3] https://github.com/quicwg/base-drafts/labels/-qpack 1228 Appendix A. Static Table 1230 +------+-----------------------------+------------------------------+ 1231 | Inde | Name | Value | 1232 | x | | | 1233 +------+-----------------------------+------------------------------+ 1234 | 0 | :authority | | 1235 | | | | 1236 | 1 | :path | / | 1237 | | | | 1238 | 2 | age | 0 | 1239 | | | | 1240 | 3 | content-disposition | | 1241 | | | | 1242 | 4 | content-length | 0 | 1243 | | | | 1244 | 5 | cookie | | 1245 | | | | 1246 | 6 | date | | 1247 | | | | 1248 | 7 | etag | | 1249 | | | | 1250 | 8 | if-modified-since | | 1251 | | | | 1252 | 9 | if-none-match | | 1253 | | | | 1254 | 10 | last-modified | | 1255 | | | | 1256 | 11 | link | | 1257 | | | | 1258 | 12 | location | | 1259 | | | | 1260 | 13 | referer | | 1261 | | | | 1262 | 14 | set-cookie | | 1263 | | | | 1264 | 15 | :method | CONNECT | 1265 | | | | 1266 | 16 | :method | DELETE | 1267 | | | | 1268 | 17 | :method | GET | 1269 | | | | 1270 | 18 | :method | HEAD | 1271 | | | | 1272 | 19 | :method | OPTIONS | 1273 | | | | 1274 | 20 | :method | POST | 1275 | | | | 1276 | 21 | :method | PUT | 1277 | | | | 1278 | 22 | :scheme | http | 1279 | | | | 1280 | 23 | :scheme | https | 1281 | | | | 1282 | 24 | :status | 103 | 1283 | | | | 1284 | 25 | :status | 200 | 1285 | | | | 1286 | 26 | :status | 304 | 1287 | | | | 1288 | 27 | :status | 404 | 1289 | | | | 1290 | 28 | :status | 503 | 1291 | | | | 1292 | 29 | accept | */* | 1293 | | | | 1294 | 30 | accept | application/dns-message | 1295 | | | | 1296 | 31 | accept-encoding | gzip, deflate, br | 1297 | | | | 1298 | 32 | accept-ranges | bytes | 1299 | | | | 1300 | 33 | access-control-allow- | cache-control | 1301 | | headers | | 1302 | | | | 1303 | 34 | access-control-allow- | content-type | 1304 | | headers | | 1305 | | | | 1306 | 35 | access-control-allow-origin | * | 1307 | | | | 1308 | 36 | cache-control | max-age=0 | 1309 | | | | 1310 | 37 | cache-control | max-age=2592000 | 1311 | | | | 1312 | 38 | cache-control | max-age=604800 | 1313 | | | | 1314 | 39 | cache-control | no-cache | 1315 | | | | 1316 | 40 | cache-control | no-store | 1317 | | | | 1318 | 41 | cache-control | public, max-age=31536000 | 1319 | | | | 1320 | 42 | content-encoding | br | 1321 | | | | 1322 | 43 | content-encoding | gzip | 1323 | | | | 1324 | 44 | content-type | application/dns-message | 1325 | | | | 1326 | 45 | content-type | application/javascript | 1327 | | | | 1328 | 46 | content-type | application/json | 1329 | | | | 1330 | 47 | content-type | application/x-www-form- | 1331 | | | urlencoded | 1332 | | | | 1333 | 48 | content-type | image/gif | 1334 | | | | 1335 | 49 | content-type | image/jpeg | 1336 | | | | 1337 | 50 | content-type | image/png | 1338 | | | | 1339 | 51 | content-type | text/css | 1340 | | | | 1341 | 52 | content-type | text/html; charset=utf-8 | 1342 | | | | 1343 | 53 | content-type | text/plain | 1344 | | | | 1345 | 54 | content-type | text/plain;charset=utf-8 | 1346 | | | | 1347 | 55 | range | bytes=0- | 1348 | | | | 1349 | 56 | strict-transport-security | max-age=31536000 | 1350 | | | | 1351 | 57 | strict-transport-security | max-age=31536000; | 1352 | | | includesubdomains | 1353 | | | | 1354 | 58 | strict-transport-security | max-age=31536000; | 1355 | | | includesubdomains; preload | 1356 | | | | 1357 | 59 | vary | accept-encoding | 1358 | | | | 1359 | 60 | vary | origin | 1360 | | | | 1361 | 61 | x-content-type-options | nosniff | 1362 | | | | 1363 | 62 | x-xss-protection | 1; mode=block | 1364 | | | | 1365 | 63 | :status | 100 | 1366 | | | | 1367 | 64 | :status | 204 | 1368 | | | | 1369 | 65 | :status | 206 | 1370 | | | | 1371 | 66 | :status | 302 | 1372 | | | | 1373 | 67 | :status | 400 | 1374 | | | | 1375 | 68 | :status | 403 | 1376 | | | | 1377 | 69 | :status | 421 | 1378 | | | | 1379 | 70 | :status | 425 | 1380 | | | | 1381 | 71 | :status | 500 | 1382 | | | | 1383 | 72 | accept-language | | 1384 | | | | 1385 | 73 | access-control-allow- | FALSE | 1386 | | credentials | | 1387 | | | | 1388 | 74 | access-control-allow- | TRUE | 1389 | | credentials | | 1390 | | | | 1391 | 75 | access-control-allow- | * | 1392 | | headers | | 1393 | | | | 1394 | 76 | access-control-allow- | get | 1395 | | methods | | 1396 | | | | 1397 | 77 | access-control-allow- | get, post, options | 1398 | | methods | | 1399 | | | | 1400 | 78 | access-control-allow- | options | 1401 | | methods | | 1402 | | | | 1403 | 79 | access-control-expose- | content-length | 1404 | | headers | | 1405 | | | | 1406 | 80 | access-control-request- | content-type | 1407 | | headers | | 1408 | | | | 1409 | 81 | access-control-request- | get | 1410 | | method | | 1411 | | | | 1412 | 82 | access-control-request- | post | 1413 | | method | | 1414 | | | | 1415 | 83 | alt-svc | clear | 1416 | | | | 1417 | 84 | authorization | | 1418 | | | | 1419 | 85 | content-security-policy | script-src 'none'; object- | 1420 | | | src 'none'; base-uri 'none' | 1421 | | | | 1422 | 86 | early-data | 1 | 1423 | | | | 1424 | 87 | expect-ct | | 1425 | | | | 1426 | 88 | forwarded | | 1427 | | | | 1428 | 89 | if-range | | 1429 | | | | 1430 | 90 | origin | | 1431 | | | | 1432 | 91 | purpose | prefetch | 1433 | | | | 1434 | 92 | server | | 1435 | | | | 1436 | 93 | timing-allow-origin | * | 1437 | | | | 1438 | 94 | upgrade-insecure-requests | 1 | 1439 | | | | 1440 | 95 | user-agent | | 1441 | | | | 1442 | 96 | x-forwarded-for | | 1443 | | | | 1444 | 97 | x-frame-options | deny | 1445 | | | | 1446 | 98 | x-frame-options | sameorigin | 1447 +------+-----------------------------+------------------------------+ 1449 Appendix B. Sample One Pass Encoding Algorithm 1451 Pseudo-code for single pass encoding, excluding handling of 1452 duplicates, non-blocking mode, and reference tracking. 1454 baseIndex = dynamicTable.baseIndex 1455 largestReference = 0 1456 for header in headers: 1457 staticIdx = staticTable.getIndex(header) 1458 if staticIdx: 1459 encodeIndexReference(streamBuffer, staticIdx) 1460 continue 1462 dynamicIdx = dynamicTable.getIndex(header) 1463 if !dynamicIdx: 1464 # No matching entry. Either insert+index or encode literal 1465 nameIdx = getNameIndex(header) 1466 if shouldIndex(header) and dynamicTable.canIndex(header): 1467 encodeLiteralWithIncrementalIndex(controlBuffer, nameIdx, 1468 header) 1469 dynamicTable.add(header) 1470 dynamicIdx = dynamicTable.baseIndex 1472 if !dynamicIdx: 1473 # Couldn't index it, literal 1474 if nameIdx <= staticTable.size: 1475 encodeLiteral(streamBuffer, nameIndex, header) 1476 else: 1477 # encode literal, possibly with nameIdx above baseIndex 1478 encodeDynamicLiteral(streamBuffer, nameIndex, baseIndex, 1479 header) 1480 largestReference = max(largestReference, 1481 dynamicTable.toAbsolute(nameIdx)) 1482 else: 1483 # Dynamic index reference 1484 assert(dynamicIdx) 1485 largestReference = max(largestReference, dynamicIdx) 1486 # Encode dynamicIdx, possibly with dynamicIdx above baseIndex 1487 encodeDynamicIndexReference(streamBuffer, dynamicIdx, 1488 baseIndex) 1490 # encode the prefix 1491 encodeInteger(prefixBuffer, 0x00, largestReference, 8) 1492 if baseIndex >= largestReference: 1493 encodeInteger(prefixBuffer, 0, baseIndex - largestReference, 7) 1494 else: 1495 encodeInteger(prefixBuffer, 0x80, 1496 largestReference - baseIndex, 7) 1498 return controlBuffer, prefixBuffer + streamBuffer 1500 Appendix C. Change Log 1502 *RFC Editor's Note:* Please remove this section prior to 1503 publication of a final version of this document. 1505 C.1. Since draft-ietf-quic-qpack-05 1507 o Introduced the terms dynamic table capacity and maximum dynamic 1508 table capacity. 1510 o Renamed SETTINGS_HEADER_TABLE_SIZE to 1511 SETTINGS_QPACK_MAX_TABLE_CAPACITY. 1513 C.2. Since draft-ietf-quic-qpack-04 1515 o Changed calculation of Delta Base Index to avoid an illegal value 1516 (#2002, #2005) 1518 C.3. Since draft-ietf-quic-qpack-03 1520 o Change HTTP settings defaults (#2038) 1522 o Substantial editorial reorganization 1524 C.4. Since draft-ietf-quic-qpack-02 1526 o Largest Reference encoded modulo MaxEntries (#1763) 1528 o New Static Table (#1355) 1530 o Table Size Update with Insert Count=0 is a connection error 1531 (#1762) 1533 o Stream Cancellations are optional when 1534 SETTINGS_HEADER_TABLE_SIZE=0 (#1761) 1536 o Implementations must handle 62 bit integers (#1760) 1538 o Different error types for each QPACK stream, other changes to 1539 error handling (#1726) 1541 o Preserve header field order (#1725) 1543 o Initial table size is the maximum permitted when table is first 1544 usable (#1642) 1546 C.5. Since draft-ietf-quic-qpack-01 1548 o Only header blocks that reference the dynamic table are 1549 acknowledged (#1603, #1605) 1551 C.6. Since draft-ietf-quic-qpack-00 1553 o Renumbered instructions for consistency (#1471, #1472) 1555 o Decoder is allowed to validate largest reference (#1404, #1469) 1557 o Header block acknowledgments also acknowledge the associated 1558 largest reference (#1370, #1400) 1560 o Added an acknowledgment for unread streams (#1371, #1400) 1562 o Removed framing from encoder stream (#1361,#1467) 1564 o Control streams use typed unidirectional streams rather than fixed 1565 stream IDs (#910,#1359) 1567 C.7. Since draft-ietf-quic-qcram-00 1569 o Separate instruction sets for table updates and header blocks 1570 (#1235, #1142, #1141) 1572 o Reworked indexing scheme (#1176, #1145, #1136, #1130, #1125, 1573 #1314) 1575 o Added mechanisms that support one-pass encoding (#1138, #1320) 1577 o Added a setting to control the number of blocked decoders (#238, 1578 #1140, #1143) 1580 o Moved table updates and acknowledgments to dedicated streams 1581 (#1121, #1122, #1238) 1583 Acknowledgments 1585 This draft draws heavily on the text of [RFC7541]. The indirect 1586 input of those authors is gratefully acknowledged, as well as ideas 1587 from: 1589 o Ryan Hamilton 1591 o Patrick McManus 1593 o Kazuho Oku 1594 o Biren Roy 1596 o Ian Swett 1598 o Dmitri Tikhonov 1600 Buck's contribution was supported by Google during his employment 1601 there. 1603 A substantial portion of Mike's contribution was supported by 1604 Microsoft during his employment there. 1606 Authors' Addresses 1608 Charles 'Buck' Krasic 1609 Netflix 1611 Email: ckrasic@netflix.com 1613 Mike Bishop 1614 Akamai Technologies 1616 Email: mbishop@evequefou.be 1618 Alan Frindell (editor) 1619 Facebook 1621 Email: afrind@fb.com