idnits 2.17.1 draft-ietf-quic-qlog-h3-events-01.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 ([QLOG-MAIN]), 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 -- The document date (7 March 2022) is 781 days in the past. Is this intentional? Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) == Outdated reference: A later version (-08) exists of draft-ietf-quic-qlog-main-schema-02 == Outdated reference: A later version (-07) exists of draft-ietf-quic-qlog-quic-events-01 -- No information found for draft-ietf-quic-http-latest - is the name correct? -- Possible downref: Normative reference to a draft: ref. 'QUIC-HTTP' -- No information found for draft-ietf-quic-qpack-latest - is the name correct? -- Possible downref: Normative reference to a draft: ref. 'QUIC-QPACK' Summary: 1 error (**), 0 flaws (~~), 3 warnings (==), 5 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 QUIC R. Marx 3 Internet-Draft KU Leuven 4 Intended status: Standards Track L. Niccolini, Ed. 5 Expires: 8 September 2022 Facebook 6 M. Seemann, Ed. 7 Protocol Labs 8 7 March 2022 10 HTTP/3 and QPACK qlog event definitions 11 draft-ietf-quic-qlog-h3-events-01 13 Abstract 15 This document describes concrete qlog event definitions and their 16 metadata for HTTP/3 and QPACK-related events. These events can then 17 be embedded in the higher level schema defined in [QLOG-MAIN]. 19 Status of This Memo 21 This Internet-Draft is submitted in full conformance with the 22 provisions of BCP 78 and BCP 79. 24 Internet-Drafts are working documents of the Internet Engineering 25 Task Force (IETF). Note that other groups may also distribute 26 working documents as Internet-Drafts. The list of current Internet- 27 Drafts is at https://datatracker.ietf.org/drafts/current/. 29 Internet-Drafts are draft documents valid for a maximum of six months 30 and may be updated, replaced, or obsoleted by other documents at any 31 time. It is inappropriate to use Internet-Drafts as reference 32 material or to cite them other than as "work in progress." 34 This Internet-Draft will expire on 8 September 2022. 36 Copyright Notice 38 Copyright (c) 2022 IETF Trust and the persons identified as the 39 document authors. All rights reserved. 41 This document is subject to BCP 78 and the IETF Trust's Legal 42 Provisions Relating to IETF Documents (https://trustee.ietf.org/ 43 license-info) in effect on the date of publication of this document. 44 Please review these documents carefully, as they describe your rights 45 and restrictions with respect to this document. Code Components 46 extracted from this document must include Revised BSD License text as 47 described in Section 4.e of the Trust Legal Provisions and are 48 provided without warranty as described in the Revised BSD License. 50 Table of Contents 52 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 53 1.1. Notational Conventions . . . . . . . . . . . . . . . . . 3 54 2. Overview . . . . . . . . . . . . . . . . . . . . . . . . . . 4 55 2.1. Usage with QUIC . . . . . . . . . . . . . . . . . . . . . 4 56 2.2. Links to the main schema . . . . . . . . . . . . . . . . 4 57 2.2.1. Raw packet and frame information . . . . . . . . . . 4 58 3. HTTP/3 and QPACK event definitions . . . . . . . . . . . . . 5 59 3.1. http . . . . . . . . . . . . . . . . . . . . . . . . . . 5 60 3.1.1. parameters_set . . . . . . . . . . . . . . . . . . . 5 61 3.1.2. parameters_restored . . . . . . . . . . . . . . . . . 6 62 3.1.3. stream_type_set . . . . . . . . . . . . . . . . . . . 7 63 3.1.4. frame_created . . . . . . . . . . . . . . . . . . . . 8 64 3.1.5. frame_parsed . . . . . . . . . . . . . . . . . . . . 8 65 3.1.6. push_resolved . . . . . . . . . . . . . . . . . . . . 9 66 3.2. qpack . . . . . . . . . . . . . . . . . . . . . . . . . . 9 67 3.2.1. state_updated . . . . . . . . . . . . . . . . . . . . 10 68 3.2.2. stream_state_updated . . . . . . . . . . . . . . . . 10 69 3.2.3. dynamic_table_updated . . . . . . . . . . . . . . . . 11 70 3.2.4. headers_encoded . . . . . . . . . . . . . . . . . . . 11 71 3.2.5. headers_decoded . . . . . . . . . . . . . . . . . . . 12 72 3.2.6. instruction_created . . . . . . . . . . . . . . . . . 12 73 3.2.7. instruction_parsed . . . . . . . . . . . . . . . . . 13 74 4. Security Considerations . . . . . . . . . . . . . . . . . . . 13 75 5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 13 76 6. References . . . . . . . . . . . . . . . . . . . . . . . . . 13 77 6.1. Normative References . . . . . . . . . . . . . . . . . . 13 78 6.2. Informative References . . . . . . . . . . . . . . . . . 14 79 Appendix A. HTTP/3 data field definitions . . . . . . . . . . . 14 80 A.1. ProtocolEventBody extension . . . . . . . . . . . . . . . 14 81 A.2. Owner . . . . . . . . . . . . . . . . . . . . . . . . . . 15 82 A.3. HTTP/3 Frames . . . . . . . . . . . . . . . . . . . . . . 15 83 A.3.1. DataFrame . . . . . . . . . . . . . . . . . . . . . . 15 84 A.3.2. HeadersFrame . . . . . . . . . . . . . . . . . . . . 15 85 A.3.3. CancelPushFrame . . . . . . . . . . . . . . . . . . . 16 86 A.3.4. SettingsFrame . . . . . . . . . . . . . . . . . . . . 16 87 A.3.5. PushPromiseFrame . . . . . . . . . . . . . . . . . . 17 88 A.3.6. GoAwayFrame . . . . . . . . . . . . . . . . . . . . . 17 89 A.3.7. MaxPushIDFrame . . . . . . . . . . . . . . . . . . . 17 90 A.3.8. ReservedFrame . . . . . . . . . . . . . . . . . . . . 17 91 A.3.9. UnknownFrame . . . . . . . . . . . . . . . . . . . . 18 92 A.4. ApplicationError . . . . . . . . . . . . . . . . . . . . 18 93 Appendix B. QPACK DATA type definitions . . . . . . . . . . . . 18 94 B.1. ProtocolEventBody extension . . . . . . . . . . . . . . . 18 95 B.2. QPACK Instructions . . . . . . . . . . . . . . . . . . . 19 96 B.2.1. SetDynamicTableCapacityInstruction . . . . . . . . . 19 97 B.2.2. InsertWithNameReferenceInstruction . . . . . . . . . 19 98 B.2.3. InsertWithoutNameReferenceInstruction . . . . . . . . 20 99 B.2.4. DuplicateInstruction . . . . . . . . . . . . . . . . 20 100 B.2.5. SectionAcknowledgementInstruction . . . . . . . . . . 20 101 B.2.6. StreamCancellationInstruction . . . . . . . . . . . . 20 102 B.2.7. InsertCountIncrementInstruction . . . . . . . . . . . 20 103 B.3. QPACK Header compression . . . . . . . . . . . . . . . . 21 104 B.3.1. IndexedHeaderField . . . . . . . . . . . . . . . . . 21 105 B.3.2. LiteralHeaderFieldWithName . . . . . . . . . . . . . 21 106 B.3.3. LiteralHeaderFieldWithoutName . . . . . . . . . . . . 22 107 B.3.4. QPACKHeaderBlockPrefix . . . . . . . . . . . . . . . 22 108 B.3.5. QPACKTableType . . . . . . . . . . . . . . . . . . . 23 109 Appendix C. Change Log . . . . . . . . . . . . . . . . . . . . . 23 110 C.1. Since draft-ietf-quic-qlog-h3-events-00: . . . . . . . . 23 111 C.2. Since draft-marx-qlog-event-definitions-quic-h3-02: . . . 23 112 C.3. Since draft-marx-qlog-event-definitions-quic-h3-01: . . . 23 113 C.4. Since draft-marx-qlog-event-definitions-quic-h3-00: . . . 25 114 Appendix D. Design Variations . . . . . . . . . . . . . . . . . 25 115 Appendix E. Acknowledgements . . . . . . . . . . . . . . . . . . 25 116 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 25 118 1. Introduction 120 This document describes the values of the qlog name ("category" + 121 "event") and "data" fields and their semantics for the HTTP/3 and 122 QPACK protocols. This document is based on draft-34 of the HTTP/3 123 I-D [QUIC-HTTP] and draft-21 of the QPACK I-D [QUIC-QPACK]. QUIC 124 events are defined in a separate document [QLOG-QUIC]. 126 Feedback and discussion are welcome at https://github.com/quicwg/qlog 127 (https://github.com/quicwg/qlog). Readers are advised to refer to 128 the "editor's draft" at that URL for an up-to-date version of this 129 document. 131 Concrete examples of integrations of this schema in various 132 programming languages can be found at https://github.com/quiclog/ 133 qlog/ (https://github.com/quiclog/qlog/). 135 1.1. Notational Conventions 137 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 138 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 139 document are to be interpreted as described in [RFC2119]. 141 The event and data structure definitions in ths document are 142 expressed in the Concise Data Definition Language [CDDL] and its 143 extensions described in [QLOG-MAIN]. 145 2. Overview 147 This document describes the values of the qlog "name" ("category" + 148 "event") and "data" fields and their semantics for the HTTP/3 and 149 QPACK protocols. 151 This document assumes the usage of the encompassing main qlog schema 152 defined in [QLOG-MAIN]. Each subsection below defines a separate 153 category (for example http, qpack) and each subsubsection is an event 154 type (for example frame_created). 156 For each event type, its importance and data definition is laid out, 157 often accompanied by possible values for the optional "trigger" 158 field. For the definition and semantics of "importance" and 159 "trigger", see the main schema document. 161 Most of the complex datastructures, enums and re-usable definitions 162 are grouped together on the bottom of this document for clarity. 164 2.1. Usage with QUIC 166 The events described in this document can be used with or without 167 logging the related QUIC events defined in [QLOG-QUIC]. If used with 168 QUIC events, the QUIC document takes precedence in terms of 169 recommended filenames and trace separation setups. 171 If used without QUIC events, it is recommended that the 172 implementation assign a globally unique identifier to each HTTP/3 173 connection. This ID can then be used as the value of the qlog 174 "group_id" field, as well as the qlog filename or file identifier, 175 potentially suffixed by the vantagepoint type (For example, 176 abcd1234_server.qlog would contain the server-side trace of the 177 connection with GUID abcd1234). 179 2.2. Links to the main schema 181 This document re-uses all the fields defined in the main qlog schema 182 (e.g., name, category, type, data, group_id, protocol_type, the time- 183 related fields, importance, RawInfo, etc.). 185 One entry in the "protocol_type" qlog array field MUST be "HTTP3" if 186 events from this document are included in a qlog trace. 188 2.2.1. Raw packet and frame information 190 This document re-uses the definition of the RawInfo data class from 191 [QLOG-MAIN]. 193 Note: As HTTP/3 does not use trailers in frames, each HTTP/3 frame 194 header_length can be calculated as header_length = RawInfo:length 195 - RawInfo:payload_length 197 Note: In some cases, the length fields are also explicitly reflected 198 inside of frame headers. For example, all HTTP/3 frames include 199 their explicit payload lengths in the frame header. In these 200 cases, those fields are intentionally preserved in the event 201 definitions. Even though this can lead to duplicate data when the 202 full RawInfo is logged, it allows a more direct mapping of the 203 HTTP/3 specifications to qlog, making it easier for users to 204 interpret. In this case, both fields MUST have the same value. 206 3. HTTP/3 and QPACK event definitions 208 Each subheading in this section is a qlog event category, while each 209 sub-subheading is a qlog event type. 211 For example, for the following two items, we have the category "http" 212 and event type "parameters_set", resulting in a concatenated qlog 213 "name" field value of "http:parameters_set". 215 3.1. http 217 Note: like all category values, the "http" category is written in 218 lowercase. 220 3.1.1. parameters_set 222 Importance: Base 224 This event contains HTTP/3 and QPACK-level settings, mostly those 225 received from the HTTP/3 SETTINGS frame. All these parameters are 226 typically set once and never change. However, they are typically set 227 at different times during the connection, so there can be several 228 instances of this event with different fields set. 230 Note that some settings have two variations (one set locally, one 231 requested by the remote peer). This is reflected in the "owner" 232 field. As such, this field MUST be correct for all settings included 233 a single event instance. If you need to log settings from two sides, 234 you MUST emit two separate event instances. 236 Note: we use the CDDL unwrap operator (~) here to make HTTPParameters 237 into a re-usable list of fields. The unwrap operator copies the 238 fields from the referenced type into the target type directly, 239 extending the target with the unwrapped fields. TODO: explain this 240 better + provide reference and maybe an example. 242 Definition: 244 HTTPParametersSet = { 245 ? owner: Owner 247 ~HTTPParameters 249 ; qlog-specific 250 ; indicates whether this implementation waits for a SETTINGS 251 ; frame before processing requests 252 ? waits_for_settings: bool 253 } 255 HTTPParameters = { 256 ? max_header_list_size: uint64 257 ? max_table_capacity: uint64 258 ? blocked_streams_count: uint64 260 ; additional settings for grease and extensions 261 * text => uint64 262 } 264 Figure 1: HTTPParametersSet definition 266 Note: enabling server push is not explicitly done in HTTP/3 by use of 267 a setting or parameter. Instead, it is communicated by use of the 268 MAX_PUSH_ID frame, which should be logged using the frame_created and 269 frame_parsed events below. 271 Additionally, this event can contain any number of unspecified 272 fields. This is to reflect setting of for example unknown (greased) 273 settings or parameters of (proprietary) extensions. 275 3.1.2. parameters_restored 277 Importance: Base 279 When using QUIC 0-RTT, HTTP/3 clients are expected to remember and 280 reuse the server's SETTINGs from the previous connection. This event 281 is used to indicate which HTTP/3 settings were restored and to which 282 values when utilizing 0-RTT. 284 Definition: 286 HTTPParametersRestored = { 288 ~HTTPParameters 290 } 292 Figure 2: HTTPParametersRestored definition 294 Note that, like for parameters_set above, this event can contain any 295 number of unspecified fields to allow for additional and custom 296 settings. 298 3.1.3. stream_type_set 300 Importance: Base 302 Emitted when a stream's type becomes known. This is typically when a 303 stream is opened and the stream's type indicator is sent or received. 305 Note: most of this information can also be inferred by looking at a 306 stream's id, since id's are strictly partitioned at the QUIC level. 307 Even so, this event has a "Base" importance because it helps a lot in 308 debugging to have this information clearly spelled out. 310 Definition: 312 HTTPStreamTypeSet = { 313 ? owner: Owner 314 stream_id: uint64 316 ? old: HTTPStreamType 317 new: HTTPStreamType 319 ; only when new === "push" 320 ? associated_push_id: uint64 321 } 323 HTTPStreamType = "data" / 324 "control" / 325 "push" / 326 "reserved" / 327 "qpack_encode" / 328 "qpack_decode" 330 Figure 3: HTTPStreamTypeSet definition 332 3.1.4. frame_created 334 Importance: Core 336 HTTP equivalent to the packet_sent event. This event is emitted when 337 the HTTP/3 framing actually happens. Note: this is not necessarily 338 the same as when the HTTP/3 data is passed on to the QUIC layer. For 339 that, see the "data_moved" event in [QLOG-QUIC]. 341 Definition: 343 HTTPFrameCreated = { 344 stream_id: uint64 345 ? length: uint64 346 frame: HTTPFrame 347 ? raw: RawInfo 348 } 350 Figure 4: HTTPFrameCreated definition 352 Note: in HTTP/3, DATA frames can have arbitrarily large lengths to 353 reduce frame header overhead. As such, DATA frames can span many 354 QUIC packets and can be created in a streaming fashion. In this 355 case, the frame_created event is emitted once for the frame header, 356 and further streamed data is indicated using the data_moved event. 358 3.1.5. frame_parsed 360 Importance: Core 362 HTTP equivalent to the packet_received event. This event is emitted 363 when we actually parse the HTTP/3 frame. Note: this is not 364 necessarily the same as when the HTTP/3 data is actually received on 365 the QUIC layer. For that, see the "data_moved" event in [QLOG-QUIC]. 367 Definition: 369 HTTPFrameParsed = { 370 stream_id: uint64 371 ? length: uint64 372 frame: HTTPFrame 373 ? raw: RawInfo 374 } 376 Figure 5: HTTPFrameParsed definition 378 Note: in HTTP/3, DATA frames can have arbitrarily large lengths to 379 reduce frame header overhead. As such, DATA frames can span many 380 QUIC packets and can be processed in a streaming fashion. In this 381 case, the frame_parsed event is emitted once for the frame header, 382 and further streamed data is indicated using the data_moved event. 384 3.1.6. push_resolved 386 Importance: Extra 388 This event is emitted when a pushed resource is successfully claimed 389 (used) or, conversely, abandoned (rejected) by the application on top 390 of HTTP/3 (e.g., the web browser). This event is added to help debug 391 problems with unexpected PUSH behaviour, which is commonplace with 392 HTTP/2. 394 Definition: 396 HTTPPushResolved = { 397 ? push_id: uint64 399 ; in case this is logged from a place that does not have access 400 ; to the push_id 401 ? stream_id: uint64 403 decision: HTTPPushDecision 404 } 406 HTTPPushDecision = "claimed" / "abandoned" 408 Figure 6: HTTPPushResolved definition 410 3.2. qpack 412 Note: like all category values, the "qpack" category is written in 413 lowercase. 415 The QPACK events mainly serve as an aid to debug low-level QPACK 416 issues. The higher-level, plaintext header values SHOULD (also) be 417 logged in the http.frame_created and http.frame_parsed event data 418 (instead). 420 Note: qpack does not have its own parameters_set event. This was 421 merged with http.parameters_set for brevity, since qpack is a 422 required extension for HTTP/3 anyway. Other HTTP/3 extensions MAY 423 also log their SETTINGS fields in http.parameters_set or MAY define 424 their own events. 426 3.2.1. state_updated 428 Importance: Base 430 This event is emitted when one or more of the internal QPACK 431 variables changes value. Note that some variables have two 432 variations (one set locally, one requested by the remote peer). This 433 is reflected in the "owner" field. As such, this field MUST be 434 correct for all variables included a single event instance. If you 435 need to log settings from two sides, you MUST emit two separate event 436 instances. 438 Definition: 440 QPACKStateUpdate = { 441 owner: Owner 442 ? dynamic_table_capacity: uint64 444 ; effective current size, sum of all the entries 445 ? dynamic_table_size: uint64 446 ? known_received_count: uint64 447 ? current_insert_count: uint64 448 } 450 Figure 7: QPACKStateUpdate definition 452 3.2.2. stream_state_updated 454 Importance: Core 456 This event is emitted when a stream becomes blocked or unblocked by 457 header decoding requests or QPACK instructions. 459 Note: This event is of "Core" importance, as it might have a large 460 impact on HTTP/3's observed performance. 462 Definition: 464 QPACKStreamStateUpdate = { 465 stream_id: uint64 466 ; streams are assumed to start "unblocked" 467 ; until they become "blocked" 468 state: QPACKStreamState 469 } 471 QPACKStreamState = "blocked" / "unblocked" 473 Figure 8: QPACKStreamStateUpdate definition 475 3.2.3. dynamic_table_updated 477 Importance: Extra 479 This event is emitted when one or more entries are inserted or 480 evicted from QPACK's dynamic table. 482 Definition: 484 QPACKDynamicTableUpdate = { 485 ; local = the encoder's dynamic table 486 ; remote = the decoder's dynamic table 487 owner: Owner 489 update_type: QPACKDynamicTableUpdateType 490 entries: [+ QPACKDynamicTableEntry] 491 } 493 QPACKDynamicTableUpdateType = "inserted" / "evicted" 495 QPACKDynamicTableEntry = { 496 index: uint64 497 ? name: text / hexstring 498 ? value: text / hexstring 499 } 501 Figure 9: QPACKDynamicTableUpdate definition 503 3.2.4. headers_encoded 505 Importance: Base 507 This event is emitted when an uncompressed header block is encoded 508 successfully. 510 Note: this event has overlap with http.frame_created for the 511 HeadersFrame type. When outputting both events, implementers MAY 512 omit the "headers" field in this event. 514 Definition: 516 QPACKHeadersEncoded = { 517 ? stream_id: uint64 518 ? headers: [+ HTTPField] 520 block_prefix: QPACKHeaderBlockPrefix 521 header_block: [+ QPACKHeaderBlockRepresentation] 523 ? length: uint 524 ? raw: hexstring 525 } 527 Figure 10: QPACKHeadersEncoded definition 529 3.2.5. headers_decoded 531 Importance: Base 533 This event is emitted when a compressed header block is decoded 534 successfully. 536 Note: this event has overlap with http.frame_parsed for the 537 HeadersFrame type. When outputting both events, implementers MAY 538 omit the "headers" field in this event. 540 Definition: 542 QPACKHeadersDecoded = { 543 ? stream_id: uint64 544 ? headers: [+ HTTPField] 546 block_prefix: QPACKHeaderBlockPrefix 547 header_block: [+ QPACKHeaderBlockRepresentation] 549 ? length: uint32 550 ? raw: hexstring 551 } 553 Figure 11: QPACKHeadersDecoded definition 555 3.2.6. instruction_created 557 Importance: Base 559 This event is emitted when a QPACK instruction (both decoder and 560 encoder) is created and added to the encoder/decoder stream. 562 Definition: 564 QPACKInstructionCreated = { 565 ; see definition in appendix 566 instruction: QPACKInstruction 567 ? length: uint32 568 ? raw: hexstring 569 } 571 Figure 12: QPACKInstructionCreated definition 573 Note: encoder/decoder semantics and stream_id's are implicit in 574 either the instruction types or can be logged via other events (e.g., 575 http.stream_type_set) 577 3.2.7. instruction_parsed 579 Importance: Base 581 This event is emitted when a QPACK instruction (both decoder and 582 encoder) is read from the encoder/decoder stream. 584 Definition: 586 QPACKInstructionParsed = { 587 ; see QPACKInstruction definition in appendix 588 instruction: QPACKInstruction 590 ? length: uint32 591 ? raw: hexstring 592 } 594 Figure 13: QPACKInstructionParsed definition 596 Note: encoder/decoder semantics and stream_id's are implicit in 597 either the instruction types or can be logged via other events (e.g., 598 http.stream_type_set) 600 4. Security Considerations 602 TBD 604 5. IANA Considerations 606 TBD 608 6. References 610 6.1. Normative References 612 [CDDL] Birkholz, H., Vigano, C., and C. Bormann, "Concise Data 613 Definition Language (CDDL): A Notational Convention to 614 Express Concise Binary Object Representation (CBOR) and 615 JSON Data Structures", RFC 8610, DOI 10.17487/RFC8610, 616 June 2019, . 618 [QLOG-MAIN] 619 Marx, R., Ed., Niccolini, L., Ed., and M. Seemann, Ed., 620 "Main logging schema for qlog", Work in Progress, 621 Internet-Draft, draft-ietf-quic-qlog-main-schema-02, 622 . 625 [QLOG-QUIC] 626 Marx, R., Ed., Niccolini, L., Ed., and M. Seemann, Ed., 627 "QUIC event definitions for qlog", Work in Progress, 628 Internet-Draft, draft-ietf-quic-qlog-quic-events-01, 629 . 632 [QUIC-HTTP] 633 Bishop, M., Ed., "Hypertext Transfer Protocol Version 3 634 (HTTP/3)", Work in Progress, Internet-Draft, draft-ietf- 635 quic-http-latest, . 638 [QUIC-QPACK] 639 Krasic, C., Bishop, M., and A. Frindell, Ed., "QPACK: 640 Header Compression for HTTP over QUIC", Work in Progress, 641 Internet-Draft, draft-ietf-quic-qpack-latest, 642 . 645 6.2. Informative References 647 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 648 Requirement Levels", BCP 14, RFC 2119, 649 DOI 10.17487/RFC2119, March 1997, 650 . 652 Appendix A. HTTP/3 data field definitions 654 A.1. ProtocolEventBody extension 656 We extend the $ProtocolEventBody extension point defined in 657 [QLOG-MAIN] with the HTTP/3 protocol events defined in this document. 659 HTTPEvents = HTTPParametersSet / HTTPParametersRestored / 660 HTTPStreamTypeSet / HTTPFrameCreated / 661 HTTPFrameParsed / HTTPPushResolved 663 $ProtocolEventBody /= HTTPEvents 665 Figure 14: HTTPEvents definition and ProtocolEventBody extension 667 A.2. Owner 669 Owner = "local" / "remote" 671 Figure 15: Owner definition 673 A.3. HTTP/3 Frames 675 HTTPFrame = HTTPDataFrame / 676 HTTPHeadersFrame / 677 HTTPCancelPushFrame / 678 HTTPSettingsFrame / 679 HTTPPushPromiseFrame / 680 HTTPGoawayFrame / 681 HTTPMaxPushIDFrame / 682 HTTPReservedFrame / 683 UnknownFrame 685 Figure 16: HTTPFrame definition 687 A.3.1. DataFrame 689 HTTPDataFrame = { 690 frame_type: "data" 691 ? raw: hexstring 692 } 694 Figure 17: HTTPDataFrame definition 696 A.3.2. HeadersFrame 698 This represents an _uncompressed_, plaintext HTTP Headers frame 699 (e.g., no QPACK compression is applied). 701 For example: 703 headers: [ 704 { 705 "name": ":path", 706 "value": "/" 707 }, 708 { 709 "name": ":method", 710 "value": "GET" 711 }, 712 { 713 "name": ":authority", 714 "value": "127.0.0.1:4433" 715 }, 716 { 717 "name": ":scheme", 718 "value": "https" 719 } 720 ] 722 Figure 18: HTTPHeadersFrame example 724 HTTPHeadersFrame = { 725 frame_type: "headers" 726 headers: [* HTTPField] 727 } 729 Figure 19: HTTPHeadersFrame definition 731 HTTPField = { 732 name: text 733 value: text 734 } 736 Figure 20: HTTPField definition 738 A.3.3. CancelPushFrame 740 HTTPCancelPushFrame = { 741 frame_type: "cancel_push" 742 push_id: uint64 743 } 745 Figure 21: HTTPCancelPushFrame definition 747 A.3.4. SettingsFrame 748 HTTPSettingsFrame = { 749 frame_type: "settings" 750 settings: [* HTTPSetting] 751 } 753 HTTPSetting = { 754 name: text 755 value: uint64 756 } 758 Figure 22: HTTPSettingsFrame definition 760 A.3.5. PushPromiseFrame 762 HTTPPushPromiseFrame = { 763 frame_type: "push_promise" 764 push_id: uint64 765 headers: [* HTTPField] 766 } 768 Figure 23: HTTPPushPromiseFrame definition 770 A.3.6. GoAwayFrame 772 HTTPGoawayFrame = { 773 frame_type: "goaway" 775 ; Either stream_id or push_id. 776 ; This is implicit from the sender of the frame 777 id: uint64 778 } 780 Figure 24: HTTPGoawayFrame definition 782 A.3.7. MaxPushIDFrame 784 HTTPMaxPushIDFrame = { 785 frame_type: "max_push_id" 786 push_id: uint64 787 } 789 Figure 25: HTTPMaxPushIDFrame definition 791 A.3.8. ReservedFrame 792 HTTPReservedFrame = { 793 frame_type: "reserved" 795 ? length: uint64 796 } 798 Figure 26: HTTPReservedFrame definition 800 A.3.9. UnknownFrame 802 HTTP/3 qlog re-uses QUIC's UnknownFrame definition, since their 803 values and usage overlaps. See [QLOG-QUIC]. 805 A.4. ApplicationError 807 HTTPApplicationError = "http_no_error" / 808 "http_general_protocol_error" / 809 "http_internal_error" / 810 "http_stream_creation_error" / 811 "http_closed_critical_stream" / 812 "http_frame_unexpected" / 813 "http_frame_error" / 814 "http_excessive_load" / 815 "http_id_error" / 816 "http_settings_error" / 817 "http_missing_settings" / 818 "http_request_rejected" / 819 "http_request_cancelled" / 820 "http_request_incomplete" / 821 "http_early_response" / 822 "http_connect_error" / 823 "http_version_fallback" 825 Figure 27: HTTPApplicationError definition 827 The HTTPApplicationError defines the general $ApplicationError 828 definition in the qlog QUIC definition, see [QLOG-QUIC]. 830 ; ensure HTTP errors are properly validate in QUIC events as well 831 ; e.g., QUIC's ConnectionClose Frame 832 $ApplicationError /= HTTPApplicationError 834 Appendix B. QPACK DATA type definitions 836 B.1. ProtocolEventBody extension 838 We extend the $ProtocolEventBody extension point defined in 839 [QLOG-MAIN] with the QPACK protocol events defined in this document. 841 QPACKEvents = QPACKStateUpdate / QPACKStreamStateUpdate / 842 QPACKDynamicTableUpdate / QPACKHeadersEncoded / 843 QPACKHeadersDecoded / QPACKInstructionCreated / 844 QPACKInstructionParsed 846 $ProtocolEventBody /= QPACKEvents 848 Figure 28: QPACKEvents definition and ProtocolEventBody extension 850 B.2. QPACK Instructions 852 Note: the instructions do not have explicit encoder/decoder types, 853 since there is no overlap between the insturctions of both types in 854 neither name nor function. 856 QPACKInstruction = SetDynamicTableCapacityInstruction / 857 InsertWithNameReferenceInstruction / 858 InsertWithoutNameReferenceInstruction / 859 DuplicateInstruction / 860 SectionAcknowledgementInstruction / 861 StreamCancellationInstruction / 862 InsertCountIncrementInstruction 864 Figure 29: QPACKInstruction definition 866 B.2.1. SetDynamicTableCapacityInstruction 868 SetDynamicTableCapacityInstruction = { 869 instruction_type: "set_dynamic_table_capacity" 870 capacity: uint32 871 } 873 Figure 30: SetDynamicTableCapacityInstruction definition 875 B.2.2. InsertWithNameReferenceInstruction 877 InsertWithNameReferenceInstruction = { 878 instruction_type: "insert_with_name_reference" 879 table_type: QPACKTableType 880 name_index: uint32 881 huffman_encoded_value: bool 882 ? value_length: uint32 883 ? value: text 884 } 886 Figure 31: InsertWithNameReferenceInstruction definition 888 B.2.3. InsertWithoutNameReferenceInstruction 890 InsertWithoutNameReferenceInstruction = { 891 instruction_type: "insert_without_name_reference" 892 huffman_encoded_name: bool 893 ? name_length: uint32 894 ? name: text 895 huffman_encoded_value: bool 896 ? value_length: uint32 897 ? value: text 898 } 900 Figure 32: InsertWithoutNameReferenceInstruction definition 902 B.2.4. DuplicateInstruction 904 DuplicateInstruction = { 905 instruction_type: "duplicate" 906 index: uint32 907 } 909 Figure 33: DuplicateInstruction definition 911 B.2.5. SectionAcknowledgementInstruction 913 SectionAcknowledgementInstruction = { 914 instruction_type: "section_acknowledgement" 915 stream_id: uint64 916 } 918 Figure 34: SectionAcknowledgementInstruction definition 920 B.2.6. StreamCancellationInstruction 922 StreamCancellationInstruction = { 923 instruction_type: "stream_cancellation" 924 stream_id: uint64 925 } 927 Figure 35: StreamCancellationInstruction definition 929 B.2.7. InsertCountIncrementInstruction 931 InsertCountIncrementInstruction = { 932 instruction_type: "insert_count_increment" 933 increment: uint32 934 } 935 Figure 36: InsertCountIncrementInstruction definition 937 B.3. QPACK Header compression 939 QPACKHeaderBlockRepresentation = IndexedHeaderField / 940 LiteralHeaderFieldWithName / 941 LiteralHeaderFieldWithoutName 943 Figure 37: QPACKHeaderBlockRepresentation definition 945 B.3.1. IndexedHeaderField 947 Note: also used for "indexed header field with post-base index" 949 IndexedHeaderField = { 950 header_field_type: "indexed_header" 952 ; MUST be "dynamic" if is_post_base is true 953 table_type: QPACKTableType 954 index: uint32 956 ; to represent the "indexed header field with post-base index" 957 ; header field type 958 is_post_base: bool .default false 959 } 961 Figure 38: IndexedHeaderField definition 963 B.3.2. LiteralHeaderFieldWithName 965 Note: also used for "Literal header field with post-base name 966 reference" 967 LiteralHeaderFieldWithName = { 968 header_field_type: "literal_with_name" 970 ; the 3rd "N" bit 971 preserve_literal: bool 973 ; MUST be "dynamic" if is_post_base is true 974 table_type: QPACKTableType 975 name_index: uint32 976 huffman_encoded_value: bool 977 ? value_length: uint32 978 ? value: text 980 ; to represent the "indexed header field with post-base index" 981 ; header field type 982 is_post_base: bool .default false 983 } 985 Figure 39: LiteralHeaderFieldWithName definition 987 B.3.3. LiteralHeaderFieldWithoutName 989 LiteralHeaderFieldWithoutName = { 990 header_field_type: "literal_without_name" 992 ; the 3rd "N" bit 993 preserve_literal: bool 994 huffman_encoded_name: bool 995 ? name_length: uint32 996 ? name: text 998 huffman_encoded_value: bool 999 ? value_length: uint32 1000 ? value: text 1001 } 1003 Figure 40: LiteralHeaderFieldWithoutName definition 1005 B.3.4. QPACKHeaderBlockPrefix 1007 QPACKHeaderBlockPrefix = { 1008 required_insert_count: uint32 1009 sign_bit: bool 1010 delta_base: uint32 1011 } 1013 Figure 41: QPACKHeaderBlockPrefix definition 1015 B.3.5. QPACKTableType 1017 QPACKTableType = "static" / "dynamic" 1019 Figure 42: QPACKTableType definition 1021 Appendix C. Change Log 1023 C.1. Since draft-ietf-quic-qlog-h3-events-00: 1025 * Change the data definition language from TypeScript to CDDL (#143) 1027 C.2. Since draft-marx-qlog-event-definitions-quic-h3-02: 1029 * These changes were done in preparation of the adoption of the 1030 drafts by the QUIC working group (#137) 1032 * Split QUIC and HTTP/3 events into two separate documents 1034 * Moved RawInfo, Importance, Generic events and Simulation events to 1035 the main schema document. 1037 C.3. Since draft-marx-qlog-event-definitions-quic-h3-01: 1039 Major changes: 1041 * Moved data_moved from http to transport. Also made the "from" and 1042 "to" fields flexible strings instead of an enum (#111,#65) 1044 * Moved packet_type fields to PacketHeader. Moved packet_size field 1045 out of PacketHeader to RawInfo:length (#40) 1047 * Made events that need to log packet_type and packet_number use a 1048 header field instead of logging these fields individually 1050 * Added support for logging retry, stateless reset and initial 1051 tokens (#94,#86,#117) 1053 * Moved separate general event categories into a single category 1054 "generic" (#47) 1056 * Added "transport:connection_closed" event (#43,#85,#78,#49) 1058 * Added version_information and alpn_information events 1059 (#85,#75,#28) 1061 * Added parameters_restored events to help clarify 0-RTT behaviour 1062 (#88) 1064 Smaller changes: 1066 * Merged loss_timer events into one loss_timer_updated event 1068 * Field data types are now strongly defined (#10,#39,#36,#115) 1070 * Renamed qpack instruction_received and instruction_sent to 1071 instruction_created and instruction_parsed (#114) 1073 * Updated qpack:dynamic_table_updated.update_type. It now has the 1074 value "inserted" instead of "added" (#113) 1076 * Updated qpack:dynamic_table_updated. It now has an "owner" field 1077 to differentiate encoder vs decoder state (#112) 1079 * Removed push_allowed from http:parameters_set (#110) 1081 * Removed explicit trigger field indications from events, since this 1082 was moved to be a generic property of the "data" field (#80) 1084 * Updated transport:connection_id_updated to be more in line with 1085 other similar events. Also dropped importance from Core to Base 1086 (#45) 1088 * Added length property to PaddingFrame (#34) 1090 * Added packet_number field to transport:frames_processed (#74) 1092 * Added a way to generically log packet header flags (first 8 bits) 1093 to PacketHeader 1095 * Added additional guidance on which events to log in which 1096 situations (#53) 1098 * Added "simulation:scenario" event to help indicate simulation 1099 details 1101 * Added "packets_acked" event (#107) 1103 * Added "datagram_ids" to the datagram_X and packet_X events to 1104 allow tracking of coalesced QUIC packets (#91) 1106 * Extended connection_state_updated with more fine-grained states 1107 (#49) 1109 C.4. Since draft-marx-qlog-event-definitions-quic-h3-00: 1111 * Event and category names are now all lowercase 1113 * Added many new events and their definitions 1115 * "type" fields have been made more specific (especially important 1116 for PacketType fields, which are now called packet_type instead of 1117 type) 1119 * Events are given an importance indicator (issue #22) 1121 * Event names are more consistent and use past tense (issue #21) 1123 * Triggers have been redefined as properties of the "data" field and 1124 updated for most events (issue #23) 1126 Appendix D. Design Variations 1128 TBD 1130 Appendix E. Acknowledgements 1132 Much of the initial work by Robin Marx was done at Hasselt 1133 University. 1135 Thanks to Marten Seemann, Jana Iyengar, Brian Trammell, Dmitri 1136 Tikhonov, Stephen Petrides, Jari Arkko, Marcus Ihlar, Victor 1137 Vasiliev, Mirja Kuehlewind, Jeremy Laine, Kazu Yamamoto, Christian 1138 Huitema, and Lucas Pardue for their feedback and suggestions. 1140 Authors' Addresses 1142 Robin Marx 1143 KU Leuven 1144 Email: robin.marx@kuleuven.be 1146 Luca Niccolini (editor) 1147 Facebook 1148 Email: lniccolini@fb.com 1150 Marten Seemann (editor) 1151 Protocol Labs 1152 Email: marten@protocol.ai