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