idnits 2.17.00 (12 Aug 2021) /tmp/idnits59300/draft-ietf-quic-http-14.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 -- The document date (August 15, 2018) is 1374 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 1965 -- Looks like a reference, but probably isn't: '2' on line 1967 -- Looks like a reference, but probably isn't: '3' on line 1969 -- Looks like a reference, but probably isn't: '4' on line 1971 == Outdated reference: A later version (-21) exists of draft-ietf-quic-qpack-02 == Outdated reference: draft-ietf-quic-transport has been published as RFC 9000 Summary: 1 error (**), 0 flaws (~~), 3 warnings (==), 6 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 QUIC M. Bishop, Ed. 3 Internet-Draft Akamai 4 Intended status: Standards Track August 15, 2018 5 Expires: February 16, 2019 7 Hypertext Transfer Protocol (HTTP) over QUIC 8 draft-ietf-quic-http-14 10 Abstract 12 The QUIC transport protocol has several features that are desirable 13 in a transport for HTTP, such as stream multiplexing, per-stream flow 14 control, and low-latency connection establishment. This document 15 describes a mapping of HTTP semantics over QUIC. This document also 16 identifies HTTP/2 features that are subsumed by QUIC, and describes 17 how HTTP/2 extensions can be ported to QUIC. 19 Note to Readers 21 Discussion of this draft takes place on the QUIC working group 22 mailing list (quic@ietf.org), which is archived at 23 https://mailarchive.ietf.org/arch/search/?email_list=quic [1]. 25 Working Group information can be found at https://github.com/quicwg 26 [2]; source code and issues list for this draft can be found at 27 https://github.com/quicwg/base-drafts/labels/-http [3]. 29 Status of This Memo 31 This Internet-Draft is submitted in full conformance with the 32 provisions of BCP 78 and BCP 79. 34 Internet-Drafts are working documents of the Internet Engineering 35 Task Force (IETF). Note that other groups may also distribute 36 working documents as Internet-Drafts. The list of current Internet- 37 Drafts is at https://datatracker.ietf.org/drafts/current/. 39 Internet-Drafts are draft documents valid for a maximum of six months 40 and may be updated, replaced, or obsoleted by other documents at any 41 time. It is inappropriate to use Internet-Drafts as reference 42 material or to cite them other than as "work in progress." 44 This Internet-Draft will expire on February 16, 2019. 46 Copyright Notice 48 Copyright (c) 2018 IETF Trust and the persons identified as the 49 document authors. All rights reserved. 51 This document is subject to BCP 78 and the IETF Trust's Legal 52 Provisions Relating to IETF Documents 53 (https://trustee.ietf.org/license-info) in effect on the date of 54 publication of this document. Please review these documents 55 carefully, as they describe your rights and restrictions with respect 56 to this document. Code Components extracted from this document must 57 include Simplified BSD License text as described in Section 4.e of 58 the Trust Legal Provisions and are provided without warranty as 59 described in the Simplified BSD License. 61 Table of Contents 63 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 64 1.1. Notational Conventions . . . . . . . . . . . . . . . . . 4 65 2. Connection Setup and Management . . . . . . . . . . . . . . . 4 66 2.1. Draft Version Identification . . . . . . . . . . . . . . 4 67 2.2. Discovering an HTTP/QUIC Endpoint . . . . . . . . . . . . 5 68 2.2.1. QUIC Version Hints . . . . . . . . . . . . . . . . . 5 69 2.3. Connection Establishment . . . . . . . . . . . . . . . . 6 70 2.4. Connection Reuse . . . . . . . . . . . . . . . . . . . . 6 71 3. Stream Mapping and Usage . . . . . . . . . . . . . . . . . . 7 72 3.1. HTTP Message Exchanges . . . . . . . . . . . . . . . . . 7 73 3.1.1. Header Formatting and Compression . . . . . . . . . . 9 74 3.1.2. The CONNECT Method . . . . . . . . . . . . . . . . . 9 75 3.1.3. Request Cancellation . . . . . . . . . . . . . . . . 10 76 3.2. Request Prioritization . . . . . . . . . . . . . . . . . 11 77 3.2.1. Placeholders . . . . . . . . . . . . . . . . . . . . 11 78 3.2.2. Priority Tree Maintenance . . . . . . . . . . . . . . 12 79 3.3. Unidirectional Streams . . . . . . . . . . . . . . . . . 13 80 3.3.1. Reserved Stream Types . . . . . . . . . . . . . . . . 13 81 3.3.2. Control Streams . . . . . . . . . . . . . . . . . . . 14 82 3.3.3. Server Push . . . . . . . . . . . . . . . . . . . . . 14 83 4. HTTP Framing Layer . . . . . . . . . . . . . . . . . . . . . 15 84 4.1. Frame Layout . . . . . . . . . . . . . . . . . . . . . . 16 85 4.2. Frame Definitions . . . . . . . . . . . . . . . . . . . . 16 86 4.2.1. Reserved Frame Types . . . . . . . . . . . . . . . . 16 87 4.2.2. DATA . . . . . . . . . . . . . . . . . . . . . . . . 16 88 4.2.3. HEADERS . . . . . . . . . . . . . . . . . . . . . . . 17 89 4.2.4. PRIORITY . . . . . . . . . . . . . . . . . . . . . . 17 90 4.2.5. CANCEL_PUSH . . . . . . . . . . . . . . . . . . . . . 19 91 4.2.6. SETTINGS . . . . . . . . . . . . . . . . . . . . . . 20 92 4.2.7. PUSH_PROMISE . . . . . . . . . . . . . . . . . . . . 23 93 4.2.8. GOAWAY . . . . . . . . . . . . . . . . . . . . . . . 24 94 4.2.9. MAX_PUSH_ID . . . . . . . . . . . . . . . . . . . . . 26 95 5. Connection Management . . . . . . . . . . . . . . . . . . . . 27 96 6. Error Handling . . . . . . . . . . . . . . . . . . . . . . . 27 97 6.1. HTTP/QUIC Error Codes . . . . . . . . . . . . . . . . . . 27 98 7. Extensions to HTTP/QUIC . . . . . . . . . . . . . . . . . . . 29 99 8. Considerations for Transitioning from HTTP/2 . . . . . . . . 30 100 8.1. Streams . . . . . . . . . . . . . . . . . . . . . . . . . 30 101 8.2. HTTP Frame Types . . . . . . . . . . . . . . . . . . . . 30 102 8.3. HTTP/2 SETTINGS Parameters . . . . . . . . . . . . . . . 32 103 8.4. HTTP/2 Error Codes . . . . . . . . . . . . . . . . . . . 33 104 9. Security Considerations . . . . . . . . . . . . . . . . . . . 34 105 10. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 34 106 10.1. Registration of HTTP/QUIC Identification String . . . . 34 107 10.2. Registration of QUIC Version Hint Alt-Svc Parameter . . 35 108 10.3. Frame Types . . . . . . . . . . . . . . . . . . . . . . 35 109 10.4. Settings Parameters . . . . . . . . . . . . . . . . . . 36 110 10.5. Error Codes . . . . . . . . . . . . . . . . . . . . . . 37 111 10.6. Stream Types . . . . . . . . . . . . . . . . . . . . . . 40 112 11. References . . . . . . . . . . . . . . . . . . . . . . . . . 40 113 11.1. Normative References . . . . . . . . . . . . . . . . . . 41 114 11.2. Informative References . . . . . . . . . . . . . . . . . 42 115 11.3. URIs . . . . . . . . . . . . . . . . . . . . . . . . . . 42 116 Appendix A. Change Log . . . . . . . . . . . . . . . . . . . . . 42 117 A.1. Since draft-ietf-quic-http-13 . . . . . . . . . . . . . . 42 118 A.2. Since draft-ietf-quic-http-12 . . . . . . . . . . . . . . 42 119 A.3. Since draft-ietf-quic-http-11 . . . . . . . . . . . . . . 43 120 A.4. Since draft-ietf-quic-http-10 . . . . . . . . . . . . . . 43 121 A.5. Since draft-ietf-quic-http-09 . . . . . . . . . . . . . . 43 122 A.6. Since draft-ietf-quic-http-08 . . . . . . . . . . . . . . 43 123 A.7. Since draft-ietf-quic-http-07 . . . . . . . . . . . . . . 43 124 A.8. Since draft-ietf-quic-http-06 . . . . . . . . . . . . . . 44 125 A.9. Since draft-ietf-quic-http-05 . . . . . . . . . . . . . . 44 126 A.10. Since draft-ietf-quic-http-04 . . . . . . . . . . . . . . 44 127 A.11. Since draft-ietf-quic-http-03 . . . . . . . . . . . . . . 44 128 A.12. Since draft-ietf-quic-http-02 . . . . . . . . . . . . . . 44 129 A.13. Since draft-ietf-quic-http-01 . . . . . . . . . . . . . . 44 130 A.14. Since draft-ietf-quic-http-00 . . . . . . . . . . . . . . 45 131 A.15. Since draft-shade-quic-http2-mapping-00 . . . . . . . . . 45 132 Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . . 45 133 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 46 135 1. Introduction 137 The QUIC transport protocol has several features that are desirable 138 in a transport for HTTP, such as stream multiplexing, per-stream flow 139 control, and low-latency connection establishment. This document 140 describes a mapping of HTTP semantics over QUIC, drawing heavily on 141 the existing TCP mapping, HTTP/2. Specifically, this document 142 identifies HTTP/2 features that are subsumed by QUIC, and describes 143 how the other features can be implemented atop QUIC. 145 QUIC is described in [QUIC-TRANSPORT]. For a full description of 146 HTTP/2, see [RFC7540]. 148 1.1. Notational Conventions 150 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 151 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 152 "OPTIONAL" in this document are to be interpreted as described in BCP 153 14 [RFC2119] [RFC8174] when, and only when, they appear in all 154 capitals, as shown here. 156 Field definitions are given in Augmented Backus-Naur Form (ABNF), as 157 defined in [RFC5234]. 159 This document uses the variable-length integer encoding from 160 [QUIC-TRANSPORT]. 162 Protocol elements called "frames" exist in both this document and 163 [QUIC-TRANSPORT]. Where frames from [QUIC-TRANSPORT] are referenced, 164 the frame name will be prefaced with "QUIC." For example, "QUIC 165 APPLICATION_CLOSE frames." References without this preface refer to 166 frames defined in Section 4.2. 168 2. Connection Setup and Management 170 2.1. Draft Version Identification 172 *RFC Editor's Note:* Please remove this section prior to 173 publication of a final version of this document. 175 HTTP/QUIC uses the token "hq" to identify itself in ALPN and Alt-Svc. 176 Only implementations of the final, published RFC can identify 177 themselves as "hq". Until such an RFC exists, implementations MUST 178 NOT identify themselves using this string. 180 Implementations of draft versions of the protocol MUST add the string 181 "-" and the corresponding draft number to the identifier. For 182 example, draft-ietf-quic-http-01 is identified using the string "hq- 183 01". 185 Non-compatible experiments that are based on these draft versions 186 MUST append the string "-" and an experiment name to the identifier. 187 For example, an experimental implementation based on draft-ietf-quic- 188 http-09 which reserves an extra stream for unsolicited transmission 189 of 1980s pop music might identify itself as "hq-09-rickroll". Note 190 that any label MUST conform to the "token" syntax defined in 191 Section 3.2.6 of [RFC7230]. Experimenters are encouraged to 192 coordinate their experiments on the quic@ietf.org mailing list. 194 2.2. Discovering an HTTP/QUIC Endpoint 196 An HTTP origin advertises the availability of an equivalent HTTP/QUIC 197 endpoint via the Alt-Svc HTTP response header or the HTTP/2 ALTSVC 198 frame ([RFC7838]), using the ALPN token defined in Section 2.3. 200 For example, an origin could indicate in an HTTP/1.1 or HTTP/2 201 response that HTTP/QUIC was available on UDP port 50781 at the same 202 hostname by including the following header in any response: 204 Alt-Svc: hq=":50781" 206 On receipt of an Alt-Svc record indicating HTTP/QUIC support, a 207 client MAY attempt to establish a QUIC connection to the indicated 208 host and port and, if successful, send HTTP requests using the 209 mapping described in this document. 211 Connectivity problems (e.g. firewall blocking UDP) can result in QUIC 212 connection establishment failure, in which case the client SHOULD 213 continue using the existing connection or try another alternative 214 endpoint offered by the origin. 216 Servers MAY serve HTTP/QUIC on any UDP port, since an alternative 217 always includes an explicit port. 219 2.2.1. QUIC Version Hints 221 This document defines the "quic" parameter for Alt-Svc, which MAY be 222 used to provide version-negotiation hints to HTTP/QUIC clients. QUIC 223 versions are four-octet sequences with no additional constraints on 224 format. Leading zeros SHOULD be omitted for brevity. 226 Syntax: 228 quic = DQUOTE version-number [ "," version-number ] * DQUOTE 229 version-number = 1*8HEXDIG; hex-encoded QUIC version 231 Where multiple versions are listed, the order of the values reflects 232 the server's preference (with the first value being the most 233 preferred version). Reserved versions MAY be listed, but unreserved 234 versions which are not supported by the alternative SHOULD NOT be 235 present in the list. Origins MAY omit supported versions for any 236 reason. 238 Clients MUST ignore any included versions which they do not support. 239 The "quic" parameter MUST NOT occur more than once; clients SHOULD 240 process only the first occurrence. 242 For example, suppose a server supported both version 0x00000001 and 243 the version rendered in ASCII as "Q034". If it opted to include the 244 reserved versions (from Section 4 of [QUIC-TRANSPORT]) 0x0 and 245 0x1abadaba, it could specify the following header: 247 Alt-Svc: hq=":49288";quic="1,1abadaba,51303334,0" 249 A client acting on this header would drop the reserved versions 250 (because it does not support them), then attempt to connect to the 251 alternative using the first version in the list which it does 252 support. 254 2.3. Connection Establishment 256 HTTP/QUIC relies on QUIC as the underlying transport. The QUIC 257 version being used MUST use TLS version 1.3 or greater as its 258 handshake protocol. HTTP/QUIC clients MUST indicate the target 259 domain name during the TLS handshake. This may be done using the 260 Server Name Indication (SNI) [RFC6066] extension to TLS or using some 261 other mechanism. 263 QUIC connections are established as described in [QUIC-TRANSPORT]. 264 During connection establishment, HTTP/QUIC support is indicated by 265 selecting the ALPN token "hq" in the TLS handshake. Support for 266 other application-layer protocols MAY be offered in the same 267 handshake. 269 While connection-level options pertaining to the core QUIC protocol 270 are set in the initial crypto handshake, HTTP/QUIC-specific settings 271 are conveyed in the SETTINGS frame. After the QUIC connection is 272 established, a SETTINGS frame (Section 4.2.6) MUST be sent by each 273 endpoint as the initial frame of their respective HTTP control stream 274 (see Section 3.3.2). The server MUST NOT send data on any other 275 stream until the client's SETTINGS frame has been received. 277 2.4. Connection Reuse 279 Once a connection exists to a server endpoint, this connection MAY be 280 reused for requests with multiple different URI authority components. 281 The client MAY send any requests for which the client considers the 282 server authoritative. 284 An authoritative HTTP/QUIC endpoint is typically discovered because 285 the client has received an Alt-Svc record from the request's origin 286 which nominates the endpoint as a valid HTTP Alternative Service for 287 that origin. As required by [RFC7838], clients MUST check that the 288 nominated server can present a valid certificate for the origin 289 before considering it authoritative. Clients MUST NOT assume that an 290 HTTP/QUIC endpoint is authoritative for other origins without an 291 explicit signal. 293 A server that does not wish clients to reuse connections for a 294 particular origin can indicate that it is not authoritative for a 295 request by sending a 421 (Misdirected Request) status code in 296 response to the request (see Section 9.1.2 of [RFC7540]). 298 3. Stream Mapping and Usage 300 A QUIC stream provides reliable in-order delivery of bytes, but makes 301 no guarantees about order of delivery with regard to bytes on other 302 streams. On the wire, data is framed into QUIC STREAM frames, but 303 this framing is invisible to the HTTP framing layer. A QUIC receiver 304 buffers and orders received STREAM frames, exposing the data 305 contained within as a reliable byte stream to the application. 307 When HTTP headers and data are sent over QUIC, the QUIC layer handles 308 most of the stream management. 310 All client-initiated bidirectional streams are used for HTTP requests 311 and responses. A bidirectional stream ensures that the response can 312 be readily correlated with the request. This means that the client's 313 first request occurs on QUIC stream 0, with subsequent requests on 314 stream 4, 8, and so on. HTTP/QUIC does not use server-initiated 315 bidirectional streams. The use of unidirectional streams is 316 discussed in Section 3.3. 318 These streams carry frames related to the request/response (see 319 Section 4.2). When a stream terminates cleanly, if the last frame on 320 the stream was truncated, this MUST be treated as a connection error 321 (see HTTP_MALFORMED_FRAME in Section 6.1). Streams which terminate 322 abruptly may be reset at any point in the frame. 324 HTTP does not need to do any separate multiplexing when using QUIC - 325 data sent over a QUIC stream always maps to a particular HTTP 326 transaction. Requests and responses are considered complete when the 327 corresponding QUIC stream is closed in the appropriate direction. 329 3.1. HTTP Message Exchanges 331 A client sends an HTTP request on a client-initiated bidirectional 332 QUIC stream. A server sends an HTTP response on the same stream as 333 the request. 335 An HTTP message (request or response) consists of: 337 1. one header block (see Section 4.2.3) containing the message 338 headers (see [RFC7230], Section 3.2), 340 2. the payload body (see [RFC7230], Section 3.3), sent as a series 341 of DATA frames (see Section 4.2.2), 343 3. optionally, one header block containing the trailer-part, if 344 present (see [RFC7230], Section 4.1.2). 346 In addition, prior to sending the message header block indicated 347 above, a response may contain zero or more header blocks containing 348 the message headers of informational (1xx) HTTP responses (see 349 [RFC7230], Section 3.2 and [RFC7231], Section 6.2). 351 PUSH_PROMISE frames (see Section 4.2.7) MAY be interleaved with the 352 frames of a response message indicating a pushed resource related to 353 the response. These PUSH_PROMISE frames are not part of the 354 response, but carry the headers of a separate HTTP request message. 355 See Section 3.3.3 for more details. 357 The "chunked" transfer encoding defined in Section 4.1 of [RFC7230] 358 MUST NOT be used. 360 Trailing header fields are carried in an additional header block 361 following the body. Senders MUST send only one header block in the 362 trailers section; receivers MUST discard any subsequent header 363 blocks. 365 An HTTP request/response exchange fully consumes a bidirectional QUIC 366 stream. After sending a request, a client closes the stream for 367 sending; after sending a response, the server closes the stream for 368 sending and the QUIC stream is fully closed. 370 A server can send a complete response prior to the client sending an 371 entire request if the response does not depend on any portion of the 372 request that has not been sent and received. When this is true, a 373 server MAY request that the client abort transmission of a request 374 without error by triggering a QUIC STOP_SENDING with error code 375 HTTP_EARLY_RESPONSE, sending a complete response, and cleanly closing 376 its streams. Clients MUST NOT discard complete responses as a result 377 of having their request terminated abruptly, though clients can 378 always discard responses at their discretion for other reasons. 380 Changes to the state of a request stream, including receiving a 381 RST_STREAM with any error code, do not affect the state of the 382 server's response. Servers do not abort a response in progress 383 solely due to a state change on the request stream. However, if the 384 request stream terminates without containing a usable HTTP request, 385 the server SHOULD abort its response with the error code 386 HTTP_INCOMPLETE_REQUEST. 388 3.1.1. Header Formatting and Compression 390 HTTP header fields carry information as a series of key-value pairs. 391 For a listing of registered HTTP headers, see the "Message Header 392 Field" registry maintained at https://www.iana.org/assignments/ 393 message-headers [4]. 395 Just as in previous versions of HTTP, header field names are strings 396 of ASCII characters that are compared in a case-insensitive fashion. 397 Properties of HTTP header names and values are discussed in more 398 detail in Section 3.2 of [RFC7230], though the wire rendering in 399 HTTP/QUIC differs. As in HTTP/2, header field names MUST be 400 converted to lowercase prior to their encoding. A request or 401 response containing uppercase header field names MUST be treated as 402 malformed. 404 As in HTTP/2, HTTP/QUIC uses special pseudo-header fields beginning 405 with ':' character (ASCII 0x3a) to convey the target URI, the method 406 of the request, and the status code for the response. These pseudo- 407 header fields are defined in Section 8.1.2.3 and 8.1.2.4 of 408 [RFC7540]. Pseudo-header fields are not HTTP header fields. 409 Endpoints MUST NOT generate pseudo-header fields other than those 410 defined in [RFC7540]. The restrictions on the use of pseudo-header 411 fields in Section 8.1.2.1 of [RFC7540] also apply to HTTP/QUIC. 413 HTTP/QUIC uses QPACK header compression as described in [QPACK], a 414 variation of HPACK which allows the flexibility to avoid header- 415 compression-induced head-of-line blocking. See that document for 416 additional details. 418 3.1.2. The CONNECT Method 420 The pseudo-method CONNECT ([RFC7231], Section 4.3.6) is primarily 421 used with HTTP proxies to establish a TLS session with an origin 422 server for the purposes of interacting with "https" resources. In 423 HTTP/1.x, CONNECT is used to convert an entire HTTP connection into a 424 tunnel to a remote host. In HTTP/2, the CONNECT method is used to 425 establish a tunnel over a single HTTP/2 stream to a remote host for 426 similar purposes. 428 A CONNECT request in HTTP/QUIC functions in the same manner as in 429 HTTP/2. The request MUST be formatted as described in [RFC7540], 430 Section 8.3. A CONNECT request that does not conform to these 431 restrictions is malformed. The request stream MUST NOT be half- 432 closed at the end of the request. 434 A proxy that supports CONNECT establishes a TCP connection 435 ([RFC0793]) to the server identified in the ":authority" pseudo- 436 header field. Once this connection is successfully established, the 437 proxy sends a HEADERS frame containing a 2xx series status code to 438 the client, as defined in [RFC7231], Section 4.3.6. 440 All DATA frames on the request stream correspond to data sent on the 441 TCP connection. Any DATA frame sent by the client is transmitted by 442 the proxy to the TCP server; data received from the TCP server is 443 packaged into DATA frames by the proxy. Note that the size and 444 number of TCP segments is not guaranteed to map predictably to the 445 size and number of HTTP DATA or QUIC STREAM frames. 447 The TCP connection can be closed by either peer. When the client 448 ends the request stream (that is, the receive stream at the proxy 449 enters the "Data Recvd" state), the proxy will set the FIN bit on its 450 connection to the TCP server. When the proxy receives a packet with 451 the FIN bit set, it will terminate the send stream that it sends to 452 client. TCP connections which remain half-closed in a single 453 direction are not invalid, but are often handled poorly by servers, 454 so clients SHOULD NOT cause send a STREAM frame with a FIN bit for 455 connections on which they are still expecting data. 457 A TCP connection error is signaled with RST_STREAM. A proxy treats 458 any error in the TCP connection, which includes receiving a TCP 459 segment with the RST bit set, as a stream error of type 460 HTTP_CONNECT_ERROR (Section 6.1). Correspondingly, a proxy MUST send 461 a TCP segment with the RST bit set if it detects an error with the 462 stream or the QUIC connection. 464 3.1.3. Request Cancellation 466 Either client or server can cancel requests by aborting the stream 467 (QUIC RST_STREAM or STOP_SENDING frames, as appropriate) with an 468 error code of HTTP_REQUEST_CANCELLED (Section 6.1). When the client 469 cancels a response, it indicates that this response is no longer of 470 interest. Clients SHOULD cancel requests by aborting both directions 471 of a stream. 473 When the server cancels its response stream using 474 HTTP_REQUEST_CANCELLED, it indicates that no application processing 475 was performed. The client can treat requests cancelled by the server 476 as though they had never been sent at all, thereby allowing them to 477 be retried later on a new connection. Servers MUST NOT use the 478 HTTP_REQUEST_CANCELLED status for requests which were partially or 479 fully processed. 481 Note: In this context, "processed" means that some data from the 482 stream was passed to some higher layer of software that might have 483 taken some action as a result. 485 If a stream is cancelled after receiving a complete response, the 486 client MAY ignore the cancellation and use the response. However, if 487 a stream is cancelled after receiving a partial response, the 488 response SHOULD NOT be used. Automatically retrying such requests is 489 not possible, unless this is otherwise permitted (e.g., idempotent 490 actions like GET, PUT, or DELETE). 492 3.2. Request Prioritization 494 HTTP/QUIC uses a priority scheme similar to that described in 495 [RFC7540], Section 5.3. In this priority scheme, a given stream can 496 be designated as dependent upon another request, which expresses the 497 preference that the latter stream (the "parent" request) be allocated 498 resources before the former stream (the "dependent" request). Taken 499 together, the dependencies across all requests in a connection form a 500 dependency tree. The structure of the dependency tree changes as 501 PRIORITY frames add, remove, or change the dependency links between 502 requests. 504 The PRIORITY frame Section 4.2.4 identifies a prioritized element. 505 The elements which can be prioritized are: 507 o Requests, identified by the ID of the request stream 509 o Pushes, identified by the Push ID of the promised resource 510 (Section 4.2.7) 512 o Placeholders, identified by a Placeholder ID 514 An element can depend on another element or on the root of the tree. 515 A reference to an element which is no longer in the tree is treated 516 as a reference to the root of the tree. 518 Only a client can send PRIORITY frames. A server MUST NOT send a 519 PRIORITY frame. 521 3.2.1. Placeholders 523 In HTTP/2, certain implementations used closed or unused streams as 524 placeholders in describing the relative priority of requests. 525 However, this created confusion as servers could not reliably 526 identify which elements of the priority tree could safely be 527 discarded. Clients could potentially reference closed streams long 528 after the server had discarded state, leading to disparate views of 529 the prioritization the client had attempted to express. 531 In HTTP/QUIC, a number of placeholders are explicitly permitted by 532 the server using the "SETTINGS_NUM_PLACEHOLDERS" setting. Because 533 the server commits to maintain these IDs in the tree, clients can use 534 them with confidence that the server will not have discarded the 535 state. 537 Placeholders are identified by an ID between zero and one less than 538 the number of placeholders the server has permitted. 540 3.2.2. Priority Tree Maintenance 542 Servers can aggressively prune inactive regions from the priority 543 tree, because placeholders will be used to "root" any persistent 544 structure of the tree which the client cares about retaining. For 545 prioritization purposes, a node in the tree is considered "inactive" 546 when the corresponding stream has been closed for at least two round- 547 trip times (using any reasonable estimate available on the server). 548 This delay helps mitigate race conditions where the server has pruned 549 a node the client believed was still active and used as a Stream 550 Dependency. 552 Specifically, the server MAY at any time: 554 o Identify and discard branches of the tree containing only inactive 555 nodes (i.e. a node with only other inactive nodes as descendants, 556 along with those descendants) 558 o Identify and condense interior regions of the tree containing only 559 inactive nodes, allocating weight appropriately 561 x x x 562 | | | 563 P P P 564 / \ | | 565 I I ==> I ==> A 566 / \ | | 567 A I A A 568 | | 569 A A 571 Figure 1: Example of Priority Tree Pruning 573 In the example in Figure 1, "P" represents a Placeholder, "A" 574 represents an active node, and "I" represents an inactive node. In 575 the first step, the server discards two inactive branches (each a 576 single node). In the second step, the server condenses an interior 577 inactive node. Note that these transformations will result in no 578 change in the resources allocated to a particular active stream. 580 Clients SHOULD assume the server is actively performing such pruning 581 and SHOULD NOT declare a dependency on a stream it knows to have been 582 closed. 584 3.3. Unidirectional Streams 586 Unidirectional streams, in either direction, are used for a range of 587 purposes. The purpose is indicated by a stream type, which is sent 588 as a single octet header at the start of the stream. The format and 589 structure of data that follows this header is determined by the 590 stream type. 592 0 1 2 3 4 5 6 7 593 +-+-+-+-+-+-+-+-+ 594 |Stream Type (8)| 595 +-+-+-+-+-+-+-+-+ 597 Figure 2: Unidirectional Stream Header 599 Some stream types are reserved (Section 3.3.1). Two stream types are 600 defined in this document: control streams (Section 3.3.2) and push 601 streams (Section 3.3.3). Other stream types can be defined by 602 extensions to HTTP/QUIC. 604 If the stream header indicates a stream type which is not supported 605 by the recipient, the remainder of the stream cannot be consumed as 606 the semantics are unknown. Recipients of unknown stream types MAY 607 trigger a QUIC STOP_SENDING frame with an error code of 608 HTTP_UNKNOWN_STREAM_TYPE, but MUST NOT consider such streams to be an 609 error of any kind. 611 Implementations MAY send stream types before knowing whether the peer 612 supports them. However, stream types which could modify the state or 613 semantics of existing protocol components, including QPACK or other 614 extensions, MUST NOT be sent until the peer is known to support them. 616 3.3.1. Reserved Stream Types 618 Stream types of the format "0x1f * N" are reserved to exercise the 619 requirement that unknown types be ignored. These streams have no 620 semantic meaning, and can be sent when application-layer padding is 621 desired. They MAY also be sent on connections where no request data 622 is currently being transferred. Endpoints MUST NOT consider these 623 streams to have any meaning upon receipt. 625 The payload and length of the stream are selected in any manner the 626 implementation chooses. 628 3.3.2. Control Streams 630 The control stream is indicated by a stream type of "0x43" (ASCII 631 'C'). Data on this stream consists of HTTP/QUIC frames, as defined 632 in Section 4.2. 634 Each side MUST initiate a single control stream at the beginning of 635 the connection and send its SETTINGS frame as the first frame on this 636 stream. Only one control stream per peer is permitted; receipt of a 637 second stream which claims to be a control stream MUST be treated as 638 a connection error of type HTTP_WRONG_STREAM_COUNT. If the control 639 stream is closed at any point, this MUST be treated as a connection 640 error of type HTTP_CLOSED_CRITICAL_STREAM. 642 A pair of unidirectional streams is used rather than a single 643 bidirectional stream. This allows either peer to send data as soon 644 they are able. Depending on whether 0-RTT is enabled on the 645 connection, either client or server might be able to send stream data 646 first after the cryptographic handshake completes. 648 3.3.3. Server Push 650 HTTP/QUIC server push is similar to what is described in HTTP/2 651 [RFC7540], but uses different mechanisms. 653 The PUSH_PROMISE frame (Section 4.2.7) is sent on the client- 654 initiated bidirectional stream that carried the request that 655 generated the push. This allows the server push to be associated 656 with a request. Ordering of a PUSH_PROMISE in relation to certain 657 parts of the response is important (see Section 8.2.1 of [RFC7540]). 659 The PUSH_PROMISE frame does not reference a stream; it contains a 660 Push ID that uniquely identifies a server push. This allows a server 661 to fulfill promises in the order that best suits its needs. The same 662 Push ID can be used in multiple PUSH_PROMISE frames (see 663 Section 4.2.7). When a server later fulfills a promise, the server 664 push response is conveyed on a push stream. 666 A push stream is indicated by a stream type of "0x50" (ASCII 'P'), 667 followed by the Push ID of the promise that it fulfills, encoded as a 668 variable-length integer. The remaining data on this stream consists 669 of HTTP/QUIC frames, as defined in Section 4.2, and carries the 670 response side of an HTTP message exchange as described in 671 Section 3.1. The request headers of the exchange are carried by a 672 PUSH_PROMISE frame (see Section 4.2.7) on the request stream which 673 generated the push. Promised requests MUST conform to the 674 requirements in Section 8.2 of [RFC7540]. 676 Only servers can push; if a server receives a client-initiated push 677 stream, this MUST be treated as a stream error of type 678 HTTP_WRONG_STREAM_DIRECTION. 680 0 1 2 3 681 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 682 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 683 |Stream Type (8)| Push ID (i) ... 684 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 686 Figure 3: Push Stream Header 688 Server push is only enabled on a connection when a client sends a 689 MAX_PUSH_ID frame (see Section 4.2.9). A server cannot use server 690 push until it receives a MAX_PUSH_ID frame. A client sends 691 additional MAX_PUSH_ID frames to control the number of pushes that a 692 server can promise. A server SHOULD use Push IDs sequentially, 693 starting at 0. A client MUST treat receipt of a push stream with a 694 Push ID that is greater than the maximum Push ID as a connection 695 error of type HTTP_PUSH_LIMIT_EXCEEDED. 697 Each Push ID MUST only be used once in a push stream header. If a 698 push stream header includes a Push ID that was used in another push 699 stream header, the client MUST treat this as a connection error of 700 type HTTP_DUPLICATE_PUSH. 702 If a promised server push is not needed by the client, the client 703 SHOULD send a CANCEL_PUSH frame. If the push stream is already open, 704 a QUIC STOP_SENDING frame with an appropriate error code can be used 705 instead (e.g., HTTP_PUSH_REFUSED, HTTP_PUSH_ALREADY_IN_CACHE; see 706 Section 6). This asks the server not to transfer the data and 707 indicates that it will be discarded upon receipt. 709 4. HTTP Framing Layer 711 Frames are used on the control stream, request streams, and push 712 streams. This section describes HTTP framing in QUIC and highlights 713 some differences from HTTP/2 framing. For more detail on differences 714 from HTTP/2, see Section 8.2. 716 4.1. Frame Layout 718 All frames have the following format: 720 0 1 2 3 721 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 722 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 723 | Length (i) ... 724 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 725 | Type (8) | Frame Payload (*) ... 726 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 728 Figure 4: HTTP/QUIC frame format 730 A frame includes the following fields: 732 Length: A variable-length integer that describes the length of the 733 Frame Payload. This length does not include the frame header. 735 Type: An 8-bit type for the frame. 737 Frame Payload: A payload, the semantics of which are determined by 738 the Type field. 740 4.2. Frame Definitions 742 4.2.1. Reserved Frame Types 744 Frame types of the format "0xb + (0x1f * N)" are reserved to exercise 745 the requirement that unknown types be ignored. These frames have no 746 semantic meaning, and can be sent when application-layer padding is 747 desired. They MAY also be sent on connections where no request data 748 is currently being transferred. Endpoints MUST NOT consider these 749 frames to have any meaning upon receipt. 751 The payload and length of the frames are selected in any manner the 752 implementation chooses. 754 4.2.2. DATA 756 DATA frames (type=0x0) convey arbitrary, variable-length sequences of 757 octets associated with an HTTP request or response payload. 759 DATA frames MUST be associated with an HTTP request or response. If 760 a DATA frame is received on either control stream, the recipient MUST 761 respond with a connection error (Section 6) of type 762 HTTP_WRONG_STREAM. 764 0 1 2 3 765 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 766 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 767 | Payload (*) ... 768 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 770 Figure 5: DATA frame payload 772 DATA frames MUST contain a non-zero-length payload. If a DATA frame 773 is received with a payload length of zero, the recipient MUST respond 774 with a stream error (Section 6) of type HTTP_MALFORMED_FRAME. 776 4.2.3. HEADERS 778 The HEADERS frame (type=0x1) is used to carry a header block, 779 compressed using QPACK. See [QPACK] for more details. 781 0 1 2 3 782 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 783 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 784 | Header Block (*) ... 785 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 787 Figure 6: HEADERS frame payload 789 HEADERS frames can only be sent on request / push streams. 791 4.2.4. PRIORITY 793 The PRIORITY (type=0x02) frame specifies the sender-advised priority 794 of a stream and is substantially different in format from [RFC7540]. 795 In order to ensure that prioritization is processed in a consistent 796 order, PRIORITY frames MUST be sent on the control stream. A 797 PRIORITY frame sent on any other stream MUST be treated as a 798 HTTP_WRONG_STREAM error. 800 The format has been modified to accommodate not being sent on a 801 request stream, to allow for identification of server pushes, and the 802 larger stream ID space of QUIC. The semantics of the Stream 803 Dependency, Weight, and E flag are otherwise the same as in HTTP/2. 805 0 1 2 3 806 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 807 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 808 |PT |DT |Empty|E| 809 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 810 | Prioritized Element ID (i) ... 811 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 812 | Element Dependency ID (i) ... 813 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 814 | Weight (8) | 815 +-+-+-+-+-+-+-+-+ 817 Figure 7: PRIORITY frame payload 819 The PRIORITY frame payload has the following fields: 821 Prioritized Type: A two-bit field indicating the type of element 822 being prioritized. 824 Dependency Type: A two-bit field indicating the type of element 825 being depended on. 827 Empty: A three-bit field which MUST be zero when sent and MUST be 828 ignored on receipt. 830 Exclusive: A flag which indicates that the stream dependency is 831 exclusive (see [RFC7540], Section 5.3). 833 Prioritized Element ID: A variable-length integer that identifies 834 the element being prioritized. Depending on the value of 835 Prioritized Type, this contains the Stream ID of a request stream, 836 the Push ID of a promised resource, or a Placeholder ID of a 837 placeholder. 839 Element Dependency ID: A variable-length integer that identifies the 840 element on which a dependency is being expressed. Depending on 841 the value of Dependency Type, this contains the Stream ID of a 842 request stream, the Push ID of a promised resource, or a 843 Placeholder ID of a placeholder. For details of dependencies, see 844 Section 3.2 and [RFC7540], Section 5.3. 846 Weight: An unsigned 8-bit integer representing a priority weight for 847 the stream (see [RFC7540], Section 5.3). Add one to the value to 848 obtain a weight between 1 and 256. 850 A PRIORITY frame identifies an element to prioritize, and an element 851 upon which it depends. A Prioritized ID or Dependency ID identifies 852 a client-initiated request using the corresponding stream ID, a 853 server push using a Push ID (see Section 4.2.7), or a placeholder 854 using a Placeholder ID (see Section 3.2.1). 856 The values for the Prioritized Element Type and Element Dependency 857 Type imply the interpretation of the associated Element ID fields. 859 +-----------+------------------+---------------------+ 860 | Type Bits | Type Description | Element ID Contents | 861 +-----------+------------------+---------------------+ 862 | 00 | Request stream | Stream ID | 863 | | | | 864 | 01 | Push stream | Push ID | 865 | | | | 866 | 10 | Placeholder | Placeholder ID | 867 | | | | 868 | 11 | Root of the tree | Ignored | 869 +-----------+------------------+---------------------+ 871 Note that the root of the tree cannot be referenced using a Stream ID 872 of 0, as in [RFC7540]; QUIC stream 0 carries a valid HTTP request. 873 The root of the tree cannot be reprioritized. A PRIORITY frame that 874 prioritizes the root of the tree MUST be treated as a connection 875 error of type HTTP_MALFORMED_FRAME. 877 When a PRIORITY frame claims to reference a request, the associated 878 ID MUST identify a client-initiated bidirectional stream. A server 879 MUST treat receipt of PRIORITY frame with a Stream ID of any other 880 type as a connection error of type HTTP_MALFORMED_FRAME. 882 A PRIORITY frame that references a non-existent Push ID or a 883 Placeholder ID greater than the server's limit MUST be treated as a 884 HTTP_MALFORMED_FRAME error. 886 A PRIORITY frame MUST contain only the identified fields. A PRIORITY 887 frame that contains more or fewer fields, or a PRIORITY frame that 888 includes a truncated integer encoding MUST be treated as a connection 889 error of type HTTP_MALFORMED_FRAME. 891 4.2.5. CANCEL_PUSH 893 The CANCEL_PUSH frame (type=0x3) is used to request cancellation of 894 server push prior to the push stream being created. The CANCEL_PUSH 895 frame identifies a server push request by Push ID (see Section 4.2.7) 896 using a variable-length integer. 898 When a server receives this frame, it aborts sending the response for 899 the identified server push. If the server has not yet started to 900 send the server push, it can use the receipt of a CANCEL_PUSH frame 901 to avoid opening a stream. If the push stream has been opened by the 902 server, the server SHOULD sent a QUIC RST_STREAM frame on those 903 streams and cease transmission of the response. 905 A server can send this frame to indicate that it won't be sending a 906 response prior to creation of a push stream. Once the push stream 907 has been created, sending CANCEL_PUSH has no effect on the state of 908 the push stream. A QUIC RST_STREAM frame SHOULD be used instead to 909 cancel transmission of the server push response. 911 A CANCEL_PUSH frame is sent on the control stream. Sending a 912 CANCEL_PUSH frame on a stream other than the control stream MUST be 913 treated as a stream error of type HTTP_WRONG_STREAM. 915 0 1 2 3 916 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 917 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 918 | Push ID (i) ... 919 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 921 Figure 8: CANCEL_PUSH frame payload 923 The CANCEL_PUSH frame carries a Push ID encoded as a variable-length 924 integer. The Push ID identifies the server push that is being 925 cancelled (see Section 4.2.7). 927 If the client receives a CANCEL_PUSH frame, that frame might identify 928 a Push ID that has not yet been mentioned by a PUSH_PROMISE frame. 930 An endpoint MUST treat a CANCEL_PUSH frame which does not contain 931 exactly one properly-formatted variable-length integer as a 932 connection error of type HTTP_MALFORMED_FRAME. 934 4.2.6. SETTINGS 936 The SETTINGS frame (type=0x4) conveys configuration parameters that 937 affect how endpoints communicate, such as preferences and constraints 938 on peer behavior, and is different from [RFC7540]. Individually, a 939 SETTINGS parameter can also be referred to as a "setting". 941 SETTINGS parameters are not negotiated; they describe characteristics 942 of the sending peer, which can be used by the receiving peer. 943 However, a negotiation can be implied by the use of SETTINGS - a peer 944 uses SETTINGS to advertise a set of supported values. The recipient 945 can then choose which entries from this list are also acceptable and 946 proceed with the value it has chosen. (This choice could be 947 announced in a field of an extension frame, or in its own value in 948 SETTINGS.) 949 Different values for the same parameter can be advertised by each 950 peer. For example, a client might be willing to consume very large 951 response headers, while servers are more cautious about request size. 953 Parameters MUST NOT occur more than once. A receiver MAY treat the 954 presence of the same parameter more than once as a connection error 955 of type HTTP_MALFORMED_FRAME. 957 The payload of a SETTINGS frame consists of zero or more parameters, 958 each consisting of an unsigned 16-bit setting identifier and a 959 length-prefixed binary value. 961 0 1 2 3 962 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 963 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 964 | Identifier (16) | Length (i) ... 965 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 966 | Contents (?) ... 967 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 969 Figure 9: SETTINGS value format 971 A zero-length content indicates that the setting value is a Boolean 972 and true. False is indicated by the absence of the setting. 974 Non-zero-length values MUST be compared against the remaining length 975 of the SETTINGS frame. Any value which purports to cross the end of 976 the frame MUST cause the SETTINGS frame to be considered malformed 977 and trigger a connection error of type HTTP_MALFORMED_FRAME. 979 An implementation MUST ignore the contents for any SETTINGS 980 identifier it does not understand. 982 SETTINGS frames always apply to a connection, never a single stream. 983 A SETTINGS frame MUST be sent as the first frame of either control 984 stream (see Section 3) by each peer, and MUST NOT be sent 985 subsequently or on any other stream. If an endpoint receives an 986 SETTINGS frame on a different stream, the endpoint MUST respond with 987 a connection error of type HTTP_WRONG_STREAM. If an endpoint 988 receives a second SETTINGS frame, the endpoint MUST respond with a 989 connection error of type HTTP_MALFORMED_FRAME. 991 The SETTINGS frame affects connection state. A badly formed or 992 incomplete SETTINGS frame MUST be treated as a connection error 993 (Section 6) of type HTTP_MALFORMED_FRAME. 995 4.2.6.1. Integer encoding 997 Settings which are integers use the QUIC variable-length integer 998 encoding. 1000 4.2.6.2. Defined SETTINGS Parameters 1002 The following settings are defined in HTTP/QUIC: 1004 SETTINGS_NUM_PLACEHOLDERS (0x3): An integer with a maximum value of 1005 2^16 - 1. The value SHOULD be non-zero. The default value is 16. 1007 SETTINGS_MAX_HEADER_LIST_SIZE (0x6): An integer with a maximum value 1008 of 2^30 - 1. The default value is unlimited. 1010 Settings values of the format "0x?a?a" are reserved to exercise the 1011 requirement that unknown parameters be ignored. Such settings have 1012 no defined meaning. Endpoints SHOULD include at least one such 1013 setting in their SETTINGS frame. Endpoints MUST NOT consider such 1014 settings to have any meaning upon receipt. 1016 Because the setting has no defined meaning, the value of the setting 1017 can be any value the implementation selects. 1019 Additional settings MAY be defined by extensions to HTTP/QUIC. 1021 4.2.6.3. Initial SETTINGS Values 1023 When a 0-RTT QUIC connection is being used, the client's initial 1024 requests will be sent before the arrival of the server's SETTINGS 1025 frame. Clients MUST store the settings the server provided in the 1026 session being resumed and MUST comply with stored settings until the 1027 server's current settings are received. Remembered settings apply to 1028 the new connection until the server's SETTINGS frame is received. 1030 A server can remember the settings that it advertised, or store an 1031 integrity-protected copy of the values in the ticket and recover the 1032 information when accepting 0-RTT data. A server uses the HTTP/QUIC 1033 settings values in determining whether to accept 0-RTT data. 1035 A server MAY accept 0-RTT and subsequently provide different settings 1036 in its SETTINGS frame. If 0-RTT data is accepted by the server, its 1037 SETTINGS frame MUST NOT reduce any limits or alter any values that 1038 might be violated by the client with its 0-RTT data. 1040 When a 1-RTT QUIC connection is being used, the client MUST NOT send 1041 requests prior to receiving and processing the server's SETTINGS 1042 frame. 1044 4.2.7. PUSH_PROMISE 1046 The PUSH_PROMISE frame (type=0x05) is used to carry a request header 1047 set from server to client, as in HTTP/2. 1049 0 1 2 3 1050 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 1051 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1052 | Push ID (i) ... 1053 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1054 | Header Block (*) ... 1055 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1057 Figure 10: PUSH_PROMISE frame payload 1059 The payload consists of: 1061 Push ID: A variable-length integer that identifies the server push 1062 request. A push ID is used in push stream header (Section 3.3.3), 1063 CANCEL_PUSH frames (Section 4.2.5), and PRIORITY frames 1064 (Section 4.2.4). 1066 Header Block: QPACK-compressed request headers for the promised 1067 response. See [QPACK] for more details. 1069 A server MUST NOT use a Push ID that is larger than the client has 1070 provided in a MAX_PUSH_ID frame (Section 4.2.9). A client MUST treat 1071 receipt of a PUSH_PROMISE that contains a larger Push ID than the 1072 client has advertised as a connection error of type 1073 HTTP_MALFORMED_FRAME. 1075 A server MAY use the same Push ID in multiple PUSH_PROMISE frames. 1076 This allows the server to use the same server push in response to 1077 multiple concurrent requests. Referencing the same server push 1078 ensures that a PUSH_PROMISE can be made in relation to every response 1079 in which server push might be needed without duplicating pushes. 1081 A server that uses the same Push ID in multiple PUSH_PROMISE frames 1082 MUST include the same header fields each time. The octets of the 1083 header block MAY be different due to differing encoding, but the 1084 header fields and their values MUST be identical. Note that ordering 1085 of header fields is significant. A client MUST treat receipt of a 1086 PUSH_PROMISE with conflicting header field values for the same Push 1087 ID as a connection error of type HTTP_MALFORMED_FRAME. 1089 Allowing duplicate references to the same Push ID is primarily to 1090 reduce duplication caused by concurrent requests. A server SHOULD 1091 avoid reusing a Push ID over a long period. Clients are likely to 1092 consume server push responses and not retain them for reuse over 1093 time. Clients that see a PUSH_PROMISE that uses a Push ID that they 1094 have since consumed and discarded are forced to ignore the 1095 PUSH_PROMISE. 1097 4.2.8. GOAWAY 1099 The GOAWAY frame (type=0x7) is used to initiate graceful shutdown of 1100 a connection by a server. GOAWAY allows a server to stop accepting 1101 new requests while still finishing processing of previously received 1102 requests. This enables administrative actions, like server 1103 maintenance. GOAWAY by itself does not close a connection. 1105 0 1 2 3 1106 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 1107 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1108 | Stream ID (i) ... 1109 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1111 Figure 11: GOAWAY frame payload 1113 The GOAWAY frame carries a QUIC Stream ID for a client-initiated 1114 bidirectional stream encoded as a variable-length integer. A client 1115 MUST treat receipt of a GOAWAY frame containing a Stream ID of any 1116 other type as a connection error of type HTTP_MALFORMED_FRAME. 1118 Clients do not need to send GOAWAY to initiate a graceful shutdown; 1119 they simply stop making new requests. A server MUST treat receipt of 1120 a GOAWAY frame as a connection error (Section 6) of type 1121 HTTP_UNEXPECTED_GOAWAY. 1123 The GOAWAY frame applies to the connection, not a specific stream. 1124 An endpoint MUST treat a GOAWAY frame on a stream other than the 1125 control stream as a connection error (Section 6) of type 1126 HTTP_WRONG_STREAM. 1128 New client requests might already have been sent before the client 1129 receives the server's GOAWAY frame. The GOAWAY frame contains the 1130 Stream ID of the last client-initiated request that was or might be 1131 processed in this connection, which enables client and server to 1132 agree on which requests were accepted prior to the connection 1133 shutdown. This identifier MAY be lower than the stream limit 1134 identified by a QUIC MAX_STREAM_ID frame, and MAY be zero if no 1135 requests were processed. Servers SHOULD NOT increase the 1136 MAX_STREAM_ID limit after sending a GOAWAY frame. 1138 Once sent, the server MUST cancel requests sent on streams with an 1139 identifier higher than the included last Stream ID. Clients MUST NOT 1140 send new requests on the connection after receiving GOAWAY, although 1141 requests might already be in transit. A new connection can be 1142 established for new requests. 1144 If the client has sent requests on streams with a higher Stream ID 1145 than indicated in the GOAWAY frame, those requests are considered 1146 cancelled (Section 3.1.3). Clients SHOULD reset any streams above 1147 this ID with the error code HTTP_REQUEST_CANCELLED. Servers MAY also 1148 cancel requests on streams below the indicated ID if these requests 1149 were not processed. 1151 Requests on Stream IDs less than or equal to the Stream ID in the 1152 GOAWAY frame might have been processed; their status cannot be known 1153 until they are completed successfully, reset individually, or the 1154 connection terminates. 1156 Servers SHOULD send a GOAWAY frame when the closing of a connection 1157 is known in advance, even if the advance notice is small, so that the 1158 remote peer can know whether a stream has been partially processed or 1159 not. For example, if an HTTP client sends a POST at the same time 1160 that a server closes a QUIC connection, the client cannot know if the 1161 server started to process that POST request if the server does not 1162 send a GOAWAY frame to indicate what streams it might have acted on. 1164 For unexpected closures caused by error conditions, a QUIC 1165 APPLICATION_CLOSE frame MUST be used. However, a GOAWAY MAY be sent 1166 first to provide additional detail to clients and to allow the client 1167 to retry requests. Including the GOAWAY frame in the same packet as 1168 the QUIC APPLICATION_CLOSE frame improves the chances of the frame 1169 being received by clients. 1171 If a connection terminates without a GOAWAY frame, the last Stream ID 1172 is effectively the highest possible Stream ID (as determined by 1173 QUIC's MAX_STREAM_ID). 1175 An endpoint MAY send multiple GOAWAY frames if circumstances change. 1176 For instance, an endpoint that sends GOAWAY without an error code 1177 during graceful shutdown could subsequently encounter an error 1178 condition. The last stream identifier from the last GOAWAY frame 1179 received indicates which streams could have been acted upon. A 1180 server MUST NOT increase the value they send in the last Stream ID, 1181 since clients might already have retried unprocessed requests on 1182 another connection. 1184 A client that is unable to retry requests loses all requests that are 1185 in flight when the server closes the connection. A server that is 1186 attempting to gracefully shut down a connection SHOULD send an 1187 initial GOAWAY frame with the last Stream ID set to the current value 1188 of QUIC's MAX_STREAM_ID and SHOULD NOT increase the MAX_STREAM_ID 1189 thereafter. This signals to the client that a shutdown is imminent 1190 and that initiating further requests is prohibited. After allowing 1191 time for any in-flight requests (at least one round-trip time), the 1192 server MAY send another GOAWAY frame with an updated last Stream ID. 1193 This ensures that a connection can be cleanly shut down without 1194 losing requests. 1196 Once all requests on streams at or below the identified stream number 1197 have been completed or cancelled, and all promised server push 1198 responses associated with those requests have been completed or 1199 cancelled, the connection can be closed using an Immediate Close (see 1200 [QUIC-TRANSPORT]). An endpoint that completes a graceful shutdown 1201 SHOULD use the QUIC APPLICATION_CLOSE frame with the HTTP_NO_ERROR 1202 code. 1204 4.2.9. MAX_PUSH_ID 1206 The MAX_PUSH_ID frame (type=0xD) is used by clients to control the 1207 number of server pushes that the server can initiate. This sets the 1208 maximum value for a Push ID that the server can use in a PUSH_PROMISE 1209 frame. Consequently, this also limits the number of push streams 1210 that the server can initiate in addition to the limit set by the QUIC 1211 MAX_STREAM_ID frame. 1213 The MAX_PUSH_ID frame is always sent on a control stream. Receipt of 1214 a MAX_PUSH_ID frame on any other stream MUST be treated as a 1215 connection error of type HTTP_WRONG_STREAM. 1217 A server MUST NOT send a MAX_PUSH_ID frame. A client MUST treat the 1218 receipt of a MAX_PUSH_ID frame as a connection error of type 1219 HTTP_MALFORMED_FRAME. 1221 The maximum Push ID is unset when a connection is created, meaning 1222 that a server cannot push until it receives a MAX_PUSH_ID frame. A 1223 client that wishes to manage the number of promised server pushes can 1224 increase the maximum Push ID by sending a MAX_PUSH_ID frame as the 1225 server fulfills or cancels server pushes. 1227 0 1 2 3 1228 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 1229 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1230 | Push ID (i) ... 1231 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1233 Figure 12: MAX_PUSH_ID frame payload 1235 The MAX_PUSH_ID frame carries a single variable-length integer that 1236 identifies the maximum value for a Push ID that the server can use 1237 (see Section 4.2.7). A MAX_PUSH_ID frame cannot reduce the maximum 1238 Push ID; receipt of a MAX_PUSH_ID that contains a smaller value than 1239 previously received MUST be treated as a connection error of type 1240 HTTP_MALFORMED_FRAME. 1242 A server MUST treat a MAX_PUSH_ID frame payload that does not contain 1243 a single variable-length integer as a connection error of type 1244 HTTP_MALFORMED_FRAME. 1246 5. Connection Management 1248 QUIC connections are persistent. All of the considerations in 1249 Section 9.1 of [RFC7540] apply to the management of QUIC connections. 1251 HTTP clients are expected to use QUIC PING frames to keep connections 1252 open. Servers SHOULD NOT use PING frames to keep a connection open. 1253 A client SHOULD NOT use PING frames for this purpose unless there are 1254 responses outstanding for requests or server pushes. If the client 1255 is not expecting a response from the server, allowing an idle 1256 connection to time out (based on the idle_timeout transport 1257 parameter) is preferred over expending effort maintaining a 1258 connection that might not be needed. A gateway MAY use PING to 1259 maintain connections in anticipation of need rather than incur the 1260 latency cost of connection establishment to servers. 1262 6. Error Handling 1264 QUIC allows the application to abruptly terminate (reset) individual 1265 streams or the entire connection when an error is encountered. These 1266 are referred to as "stream errors" or "connection errors" and are 1267 described in more detail in [QUIC-TRANSPORT]. 1269 This section describes HTTP/QUIC-specific error codes which can be 1270 used to express the cause of a connection or stream error. 1272 6.1. HTTP/QUIC Error Codes 1274 The following error codes are defined for use in QUIC RST_STREAM, 1275 STOP_SENDING, and APPLICATION_CLOSE frames when using HTTP/QUIC. 1277 STOPPING (0x00): This value is reserved by the transport to be used 1278 in response to QUIC STOP_SENDING frames. 1280 HTTP_NO_ERROR (0x01): No error. This is used when the connection or 1281 stream needs to be closed, but there is no error to signal. 1283 HTTP_PUSH_REFUSED (0x02): The server has attempted to push content 1284 which the client will not accept on this connection. 1286 HTTP_INTERNAL_ERROR (0x03): An internal error has occurred in the 1287 HTTP stack. 1289 HTTP_PUSH_ALREADY_IN_CACHE (0x04): The server has attempted to push 1290 content which the client has cached. 1292 HTTP_REQUEST_CANCELLED (0x05): The client no longer needs the 1293 requested data. 1295 HTTP_INCOMPLETE_REQUEST (0x06): The client's stream terminated 1296 without containing a fully-formed request. 1298 HTTP_CONNECT_ERROR (0x07): The connection established in response to 1299 a CONNECT request was reset or abnormally closed. 1301 HTTP_EXCESSIVE_LOAD (0x08): The endpoint detected that its peer is 1302 exhibiting a behavior that might be generating excessive load. 1304 HTTP_VERSION_FALLBACK (0x09): The requested operation cannot be 1305 served over HTTP/QUIC. The peer should retry over HTTP/2. 1307 HTTP_WRONG_STREAM (0x0A): A frame was received on a stream where it 1308 is not permitted. 1310 HTTP_PUSH_LIMIT_EXCEEDED (0x0B): A Push ID greater than the current 1311 maximum Push ID was referenced. 1313 HTTP_DUPLICATE_PUSH (0x0C): A Push ID was referenced in two 1314 different stream headers. 1316 HTTP_UNKNOWN_STREAM_TYPE (0x0D): A unidirectional stream header 1317 contained an unknown stream type. 1319 HTTP_WRONG_STREAM_COUNT (0x0E): A unidirectional stream type was 1320 used more times than is permitted by that type. 1322 HTTP_CLOSED_CRITICAL_STREAM (0x0F): A stream required by the 1323 connection was closed or reset. 1325 HTTP_WRONG_STREAM_DIRECTION (0x0010): A unidirectional stream type 1326 was used by a peer which is not permitted to do so. 1328 HTTP_EARLY_RESPONSE (0x0011): The remainder of the client's request 1329 is not needed to produce a response. For use in STOP_SENDING 1330 only. 1332 HTTP_GENERAL_PROTOCOL_ERROR (0x00FF): Peer violated protocol 1333 requirements in a way which doesn't match a more specific error 1334 code, or endpoint declines to use the more specific error code. 1336 HTTP_MALFORMED_FRAME (0x01XX): An error in a specific frame type. 1337 The frame type is included as the last octet of the error code. 1338 For example, an error in a MAX_PUSH_ID frame would be indicated 1339 with the code (0x10D). 1341 7. Extensions to HTTP/QUIC 1343 HTTP/QUIC permits extension of the protocol. Within the limitations 1344 described in this section, protocol extensions can be used to provide 1345 additional services or alter any aspect of the protocol. Extensions 1346 are effective only within the scope of a single HTTP/QUIC connection. 1348 This applies to the protocol elements defined in this document. This 1349 does not affect the existing options for extending HTTP, such as 1350 defining new methods, status codes, or header fields. 1352 Extensions are permitted to use new frame types (Section 4.2), new 1353 settings (Section 4.2.6.2), new error codes (Section 6), or new 1354 unidirectional stream types (Section 3.3). Registries are 1355 established for managing these extension points: frame types 1356 (Section 10.3), settings (Section 10.4), error codes (Section 10.5), 1357 and stream types (Section 10.6). 1359 Implementations MUST ignore unknown or unsupported values in all 1360 extensible protocol elements. Implementations MUST discard frames 1361 and unidirectional streams that have unknown or unsupported types. 1362 This means that any of these extension points can be safely used by 1363 extensions without prior arrangement or negotiation. 1365 Extensions that could change the semantics of existing protocol 1366 components MUST be negotiated before being used. For example, an 1367 extension that changes the layout of the HEADERS frame cannot be used 1368 until the peer has given a positive signal that this is acceptable. 1369 In this case, it could also be necessary to coordinate when the 1370 revised layout comes into effect. 1372 This document doesn't mandate a specific method for negotiating the 1373 use of an extension but notes that a setting (Section 4.2.6.2) could 1374 be used for that purpose. If both peers set a value that indicates 1375 willingness to use the extension, then the extension can be used. If 1376 a setting is used for extension negotiation, the default value MUST 1377 be defined in such a fashion that the extension is disabled if the 1378 setting is omitted. 1380 8. Considerations for Transitioning from HTTP/2 1382 HTTP/QUIC is strongly informed by HTTP/2, and bears many 1383 similarities. This section describes the approach taken to design 1384 HTTP/QUIC, points out important differences from HTTP/2, and 1385 describes how to map HTTP/2 extensions into HTTP/QUIC. 1387 HTTP/QUIC begins from the premise that HTTP/2 code reuse is a useful 1388 feature, but not a hard requirement. HTTP/QUIC departs from HTTP/2 1389 primarily where necessary to accommodate the differences in behavior 1390 between QUIC and TCP (lack of ordering, support for streams). We 1391 intend to avoid gratuitous changes which make it difficult or 1392 impossible to build extensions with the same semantics applicable to 1393 both protocols at once. 1395 These departures are noted in this section. 1397 8.1. Streams 1399 HTTP/QUIC permits use of a larger number of streams (2^62-1) than 1400 HTTP/2. The considerations about exhaustion of stream identifier 1401 space apply, though the space is significantly larger such that it is 1402 likely that other limits in QUIC are reached first, such as the limit 1403 on the connection flow control window. 1405 8.2. HTTP Frame Types 1407 Many framing concepts from HTTP/2 can be elided away on QUIC, because 1408 the transport deals with them. Because frames are already on a 1409 stream, they can omit the stream number. Because frames do not block 1410 multiplexing (QUIC's multiplexing occurs below this layer), the 1411 support for variable-maximum-length packets can be removed. Because 1412 stream termination is handled by QUIC, an END_STREAM flag is not 1413 required. This permits the removal of the Flags field from the 1414 generic frame layout. 1416 Frame payloads are largely drawn from [RFC7540]. However, QUIC 1417 includes many features (e.g. flow control) which are also present in 1418 HTTP/2. In these cases, the HTTP mapping does not re-implement them. 1419 As a result, several HTTP/2 frame types are not required in HTTP/ 1420 QUIC. Where an HTTP/2-defined frame is no longer used, the frame ID 1421 has been reserved in order to maximize portability between HTTP/2 and 1422 HTTP/QUIC implementations. However, even equivalent frames between 1423 the two mappings are not identical. 1425 Many of the differences arise from the fact that HTTP/2 provides an 1426 absolute ordering between frames across all streams, while QUIC 1427 provides this guarantee on each stream only. As a result, if a frame 1428 type makes assumptions that frames from different streams will still 1429 be received in the order sent, HTTP/QUIC will break them. 1431 For example, implicit in the HTTP/2 prioritization scheme is the 1432 notion of in-order delivery of priority changes (i.e., dependency 1433 tree mutations): since operations on the dependency tree such as 1434 reparenting a subtree are not commutative, both sender and receiver 1435 must apply them in the same order to ensure that both sides have a 1436 consistent view of the stream dependency tree. HTTP/2 specifies 1437 priority assignments in PRIORITY frames and (optionally) in HEADERS 1438 frames. To achieve in-order delivery of priority changes in HTTP/ 1439 QUIC, PRIORITY frames are sent on the control stream and the PRIORITY 1440 section is removed from the HEADERS frame. 1442 Likewise, HPACK was designed with the assumption of in-order 1443 delivery. A sequence of encoded header blocks must arrive (and be 1444 decoded) at an endpoint in the same order in which they were encoded. 1445 This ensures that the dynamic state at the two endpoints remains in 1446 sync. As a result, HTTP/QUIC uses a modified version of HPACK, 1447 described in [QPACK]. 1449 Frame type definitions in HTTP/QUIC often use the QUIC variable- 1450 length integer encoding. In particular, Stream IDs use this 1451 encoding, which allow for a larger range of possible values than the 1452 encoding used in HTTP/2. Some frames in HTTP/QUIC use an identifier 1453 rather than a Stream ID (e.g. Push IDs in PRIORITY frames). 1454 Redefinition of the encoding of extension frame types might be 1455 necessary if the encoding includes a Stream ID. 1457 Because the Flags field is not present in generic HTTP/QUIC frames, 1458 those frames which depend on the presence of flags need to allocate 1459 space for flags as part of their frame payload. 1461 Other than this issue, frame type HTTP/2 extensions are typically 1462 portable to QUIC simply by replacing Stream 0 in HTTP/2 with a 1463 control stream in HTTP/QUIC. HTTP/QUIC extensions will not assume 1464 ordering, but would not be harmed by ordering, and would be portable 1465 to HTTP/2 in the same manner. 1467 Below is a listing of how each HTTP/2 frame type is mapped: 1469 DATA (0x0): Padding is not defined in HTTP/QUIC frames. See 1470 Section 4.2.2. 1472 HEADERS (0x1): As described above, the PRIORITY region of HEADERS is 1473 not supported. A separate PRIORITY frame MUST be used. Padding 1474 is not defined in HTTP/QUIC frames. See Section 4.2.3. 1476 PRIORITY (0x2): As described above, the PRIORITY frame is sent on 1477 the control stream and can reference either a Stream ID or a Push 1478 ID. See Section 4.2.4. 1480 RST_STREAM (0x3): RST_STREAM frames do not exist, since QUIC 1481 provides stream lifecycle management. The same code point is used 1482 for the CANCEL_PUSH frame (Section 4.2.5). 1484 SETTINGS (0x4): SETTINGS frames are sent only at the beginning of 1485 the connection. See Section 4.2.6 and Section 8.3. 1487 PUSH_PROMISE (0x5): The PUSH_PROMISE does not reference a stream; 1488 instead the push stream references the PUSH_PROMISE frame using a 1489 Push ID. See Section 4.2.7. 1491 PING (0x6): PING frames do not exist, since QUIC provides equivalent 1492 functionality. 1494 GOAWAY (0x7): GOAWAY is sent only from server to client and does not 1495 contain an error code. See Section 4.2.8. 1497 WINDOW_UPDATE (0x8): WINDOW_UPDATE frames do not exist, since QUIC 1498 provides flow control. 1500 CONTINUATION (0x9): CONTINUATION frames do not exist; instead, 1501 larger HEADERS/PUSH_PROMISE frames than HTTP/2 are permitted, and 1502 HEADERS frames can be used in series. 1504 Frame types defined by extensions to HTTP/2 need to be separately 1505 registered for HTTP/QUIC if still applicable. The IDs of frames 1506 defined in [RFC7540] have been reserved for simplicity. See 1507 Section 10.3. 1509 8.3. HTTP/2 SETTINGS Parameters 1511 An important difference from HTTP/2 is that settings are sent once, 1512 at the beginning of the connection, and thereafter cannot change. 1513 This eliminates many corner cases around synchronization of changes. 1515 Some transport-level options that HTTP/2 specifies via the SETTINGS 1516 frame are superseded by QUIC transport parameters in HTTP/QUIC. The 1517 HTTP-level options that are retained in HTTP/QUIC have the same value 1518 as in HTTP/2. 1520 Below is a listing of how each HTTP/2 SETTINGS parameter is mapped: 1522 SETTINGS_HEADER_TABLE_SIZE: See Section 4.2.6.2. 1524 SETTINGS_ENABLE_PUSH: This is removed in favor of the MAX_PUSH_ID 1525 which provides a more granular control over server push. 1527 SETTINGS_MAX_CONCURRENT_STREAMS: QUIC controls the largest open 1528 Stream ID as part of its flow control logic. Specifying 1529 SETTINGS_MAX_CONCURRENT_STREAMS in the SETTINGS frame is an error. 1531 SETTINGS_INITIAL_WINDOW_SIZE: QUIC requires both stream and 1532 connection flow control window sizes to be specified in the 1533 initial transport handshake. Specifying 1534 SETTINGS_INITIAL_WINDOW_SIZE in the SETTINGS frame is an error. 1536 SETTINGS_MAX_FRAME_SIZE: This setting has no equivalent in HTTP/ 1537 QUIC. Specifying it in the SETTINGS frame is an error. 1539 SETTINGS_MAX_HEADER_LIST_SIZE: See Section 4.2.6.2. 1541 Settings need to be defined separately for HTTP/2 and HTTP/QUIC. The 1542 IDs of settings defined in [RFC7540] have been reserved for 1543 simplicity. See Section 10.4. 1545 8.4. HTTP/2 Error Codes 1547 QUIC has the same concepts of "stream" and "connection" errors that 1548 HTTP/2 provides. However, because the error code space is shared 1549 between multiple components, there is no direct portability of HTTP/2 1550 error codes. 1552 The HTTP/2 error codes defined in Section 7 of [RFC7540] map to the 1553 HTTP over QUIC error codes as follows: 1555 NO_ERROR (0x0): HTTP_NO_ERROR in Section 6.1. 1557 PROTOCOL_ERROR (0x1): No single mapping. See new 1558 HTTP_MALFORMED_FRAME error codes defined in Section 6.1. 1560 INTERNAL_ERROR (0x2): HTTP_INTERNAL_ERROR in Section 6.1. 1562 FLOW_CONTROL_ERROR (0x3): Not applicable, since QUIC handles flow 1563 control. Would provoke a QUIC_FLOW_CONTROL_RECEIVED_TOO_MUCH_DATA 1564 from the QUIC layer. 1566 SETTINGS_TIMEOUT (0x4): Not applicable, since no acknowledgement of 1567 SETTINGS is defined. 1569 STREAM_CLOSED (0x5): Not applicable, since QUIC handles stream 1570 management. Would provoke a QUIC_STREAM_DATA_AFTER_TERMINATION 1571 from the QUIC layer. 1573 FRAME_SIZE_ERROR (0x6): No single mapping. See new error codes 1574 defined in Section 6.1. 1576 REFUSED_STREAM (0x7): Not applicable, since QUIC handles stream 1577 management. Would provoke a QUIC_TOO_MANY_OPEN_STREAMS from the 1578 QUIC layer. 1580 CANCEL (0x8): HTTP_REQUEST_CANCELLED in Section 6.1. 1582 COMPRESSION_ERROR (0x9): HTTP_QPACK_DECOMPRESSION_FAILED in [QPACK]. 1584 CONNECT_ERROR (0xa): HTTP_CONNECT_ERROR in Section 6.1. 1586 ENHANCE_YOUR_CALM (0xb): HTTP_EXCESSIVE_LOAD in Section 6.1. 1588 INADEQUATE_SECURITY (0xc): Not applicable, since QUIC is assumed to 1589 provide sufficient security on all connections. 1591 HTTP_1_1_REQUIRED (0xd): HTTP_VERSION_FALLBACK in Section 6.1. 1593 Error codes need to be defined for HTTP/2 and HTTP/QUIC separately. 1594 See Section 10.5. 1596 9. Security Considerations 1598 The security considerations of HTTP over QUIC should be comparable to 1599 those of HTTP/2 with TLS. Note that where HTTP/2 employs PADDING 1600 frames to make a connection more resistant to traffic analysis, HTTP/ 1601 QUIC can rely on QUIC's own PADDING frames or employ the reserved 1602 frame and stream types discussed in Section 4.2.1 and Section 3.3.1. 1604 The modified SETTINGS format contains nested length elements, which 1605 could pose a security risk to an incautious implementer. A SETTINGS 1606 frame parser MUST ensure that the length of the frame exactly matches 1607 the length of the settings it contains. 1609 10. IANA Considerations 1611 10.1. Registration of HTTP/QUIC Identification String 1613 This document creates a new registration for the identification of 1614 HTTP/QUIC in the "Application Layer Protocol Negotiation (ALPN) 1615 Protocol IDs" registry established in [RFC7301]. 1617 The "hq" string identifies HTTP/QUIC: 1619 Protocol: HTTP over QUIC 1620 Identification Sequence: 0x68 0x71 ("hq") 1622 Specification: This document 1624 10.2. Registration of QUIC Version Hint Alt-Svc Parameter 1626 This document creates a new registration for version-negotiation 1627 hints in the "Hypertext Transfer Protocol (HTTP) Alt-Svc Parameter" 1628 registry established in [RFC7838]. 1630 Parameter: "quic" 1632 Specification: This document, Section 2.2.1 1634 10.3. Frame Types 1636 This document establishes a registry for HTTP/QUIC frame type codes. 1637 The "HTTP/QUIC Frame Type" registry manages an 8-bit space. The 1638 "HTTP/QUIC Frame Type" registry operates under either of the "IETF 1639 Review" or "IESG Approval" policies [RFC8126] for values from 0x00 up 1640 to and including 0xef, with values from 0xf0 up to and including 0xff 1641 being reserved for Experimental Use. 1643 While this registry is separate from the "HTTP/2 Frame Type" registry 1644 defined in [RFC7540], it is preferable that the assignments parallel 1645 each other. If an entry is present in only one registry, every 1646 effort SHOULD be made to avoid assigning the corresponding value to 1647 an unrelated operation. 1649 New entries in this registry require the following information: 1651 Frame Type: A name or label for the frame type. 1653 Code: The 8-bit code assigned to the frame type. 1655 Specification: A reference to a specification that includes a 1656 description of the frame layout and its semantics, including any 1657 parts of the frame that are conditionally present. 1659 The entries in the following table are registered by this document. 1661 +--------------+------+---------------+ 1662 | Frame Type | Code | Specification | 1663 +--------------+------+---------------+ 1664 | DATA | 0x0 | Section 4.2.2 | 1665 | | | | 1666 | HEADERS | 0x1 | Section 4.2.3 | 1667 | | | | 1668 | PRIORITY | 0x2 | Section 4.2.4 | 1669 | | | | 1670 | CANCEL_PUSH | 0x3 | Section 4.2.5 | 1671 | | | | 1672 | SETTINGS | 0x4 | Section 4.2.6 | 1673 | | | | 1674 | PUSH_PROMISE | 0x5 | Section 4.2.7 | 1675 | | | | 1676 | Reserved | 0x6 | N/A | 1677 | | | | 1678 | GOAWAY | 0x7 | Section 4.2.8 | 1679 | | | | 1680 | Reserved | 0x8 | N/A | 1681 | | | | 1682 | Reserved | 0x9 | N/A | 1683 | | | | 1684 | MAX_PUSH_ID | 0xD | Section 4.2.9 | 1685 +--------------+------+---------------+ 1687 Additionally, each code of the format "0xb + (0x1f * N)" for values 1688 of N in the range (0..7) (that is, "0xb", "0x2a", "0x49", "0x68", 1689 "0x87", "0xa6", "0xc5", and "0xe4"), the following values should be 1690 registered: 1692 Frame Type: Reserved - GREASE 1694 Specification: Section 4.2.1 1696 10.4. Settings Parameters 1698 This document establishes a registry for HTTP/QUIC settings. The 1699 "HTTP/QUIC Settings" registry manages a 16-bit space. The "HTTP/QUIC 1700 Settings" registry operates under the "Expert Review" policy 1701 [RFC8126] for values in the range from 0x0000 to 0xefff, with values 1702 between and 0xf000 and 0xffff being reserved for Experimental Use. 1703 The designated experts are the same as those for the "HTTP/2 1704 Settings" registry defined in [RFC7540]. 1706 While this registry is separate from the "HTTP/2 Settings" registry 1707 defined in [RFC7540], it is preferable that the assignments parallel 1708 each other. If an entry is present in only one registry, every 1709 effort SHOULD be made to avoid assigning the corresponding value to 1710 an unrelated operation. 1712 New registrations are advised to provide the following information: 1714 Name: A symbolic name for the setting. Specifying a setting name is 1715 optional. 1717 Code: The 16-bit code assigned to the setting. 1719 Specification: An optional reference to a specification that 1720 describes the use of the setting. 1722 The entries in the following table are registered by this document. 1724 +----------------------+------+-----------------+ 1725 | Setting Name | Code | Specification | 1726 +----------------------+------+-----------------+ 1727 | Reserved | 0x2 | N/A | 1728 | | | | 1729 | NUM_PLACEHOLDERS | 0x3 | Section 4.2.6.2 | 1730 | | | | 1731 | Reserved | 0x4 | N/A | 1732 | | | | 1733 | Reserved | 0x5 | N/A | 1734 | | | | 1735 | MAX_HEADER_LIST_SIZE | 0x6 | Section 4.2.6.2 | 1736 +----------------------+------+-----------------+ 1738 Additionally, each code of the format "0x?a?a" where each "?" is any 1739 four bits (that is, "0x0a0a", "0x0a1a", etc. through "0xfafa"), the 1740 following values should be registered: 1742 Name: Reserved - GREASE 1744 Specification: Section 4.2.6.2 1746 10.5. Error Codes 1748 This document establishes a registry for HTTP/QUIC error codes. The 1749 "HTTP/QUIC Error Code" registry manages a 16-bit space. The "HTTP/ 1750 QUIC Error Code" registry operates under the "Expert Review" policy 1751 [RFC8126]. 1753 Registrations for error codes are required to include a description 1754 of the error code. An expert reviewer is advised to examine new 1755 registrations for possible duplication with existing error codes. 1756 Use of existing registrations is to be encouraged, but not mandated. 1758 New registrations are advised to provide the following information: 1760 Name: A name for the error code. Specifying an error code name is 1761 optional. 1763 Code: The 16-bit error code value. 1765 Description: A brief description of the error code semantics, longer 1766 if no detailed specification is provided. 1768 Specification: An optional reference for a specification that 1769 defines the error code. 1771 The entries in the following table are registered by this document. 1773 +-------------------------+-------+---------------+-----------------+ 1774 | Name | Code | Description | Specification | 1775 +-------------------------+-------+---------------+-----------------+ 1776 | STOPPING | 0x000 | Reserved by | [QUIC-TRANSPORT | 1777 | | 0 | QUIC | ] | 1778 | | | | | 1779 | HTTP_NO_ERROR | 0x000 | No error | Section 6.1 | 1780 | | 1 | | | 1781 | | | | | 1782 | HTTP_PUSH_REFUSED | 0x000 | Client | Section 6.1 | 1783 | | 2 | refused | | 1784 | | | pushed | | 1785 | | | content | | 1786 | | | | | 1787 | HTTP_INTERNAL_ERROR | 0x000 | Internal | Section 6.1 | 1788 | | 3 | error | | 1789 | | | | | 1790 | HTTP_PUSH_ALREADY_IN_CA | 0x000 | Pushed | Section 6.1 | 1791 | CHE | 4 | content | | 1792 | | | already | | 1793 | | | cached | | 1794 | | | | | 1795 | HTTP_REQUEST_CANCELLED | 0x000 | Data no | Section 6.1 | 1796 | | 5 | longer needed | | 1797 | | | | | 1798 | HTTP_INCOMPLETE_REQUEST | 0x000 | Stream | Section 6.1 | 1799 | | 6 | terminated | | 1800 | | | early | | 1801 | | | | | 1802 | HTTP_CONNECT_ERROR | 0x000 | TCP reset or | Section 6.1 | 1803 | | 7 | error on | | 1804 | | | CONNECT | | 1805 | | | request | | 1806 | | | | | 1807 | HTTP_EXCESSIVE_LOAD | 0x000 | Peer | Section 6.1 | 1808 | | 8 | generating | | 1809 | | | excessive | | 1810 | | | load | | 1811 | | | | | 1812 | HTTP_VERSION_FALLBACK | 0x000 | Retry over | Section 6.1 | 1813 | | 9 | HTTP/2 | | 1814 | | | | | 1815 | HTTP_WRONG_STREAM | 0x000 | A frame was | Section 6.1 | 1816 | | A | sent on the | | 1817 | | | wrong stream | | 1818 | | | | | 1819 | HTTP_PUSH_LIMIT_EXCEEDE | 0x000 | Maximum Push | Section 6.1 | 1820 | D | B | ID exceeded | | 1821 | | | | | 1822 | HTTP_DUPLICATE_PUSH | 0x000 | Push ID was | Section 6.1 | 1823 | | C | fulfilled | | 1824 | | | multiple | | 1825 | | | times | | 1826 | | | | | 1827 | HTTP_UNKNOWN_STREAM_TYP | 0x000 | Unknown unidi | Section 6.1 | 1828 | E | D | rectional | | 1829 | | | stream type | | 1830 | | | | | 1831 | HTTP_WRONG_STREAM_COUNT | 0x000 | Too many unid | Section 6.1 | 1832 | | E | irectional | | 1833 | | | streams | | 1834 | | | | | 1835 | HTTP_CLOSED_CRITICAL_ST | 0x000 | Critical | Section 6.1 | 1836 | REAM | F | stream was | | 1837 | | | closed | | 1838 | | | | | 1839 | HTTP_WRONG_STREAM_DIREC | 0x001 | Unidirectiona | Section 6.1 | 1840 | TION | 0 | l stream in | | 1841 | | | wrong | | 1842 | | | direction | | 1843 | | | | | 1844 | HTTP_EARLY_RESPONSE | 0x001 | Remainder of | Section 6.1 | 1845 | | 1 | request not | | 1846 | | | needed | | 1847 | | | | | 1848 | HTTP_MALFORMED_FRAME | 0x01X | Error in | Section 6.1 | 1849 | | X | frame | | 1850 | | | formatting or | | 1851 | | | use | | 1852 +-------------------------+-------+---------------+-----------------+ 1854 10.6. Stream Types 1856 This document establishes a registry for HTTP/QUIC unidirectional 1857 stream types. The "HTTP/QUIC Stream Type" registry manages an 8-bit 1858 space. The "HTTP/QUIC Stream Type" registry operates under either of 1859 the "IETF Review" or "IESG Approval" policies [RFC8126] for values 1860 from 0x00 up to and including 0xef, with values from 0xf0 up to and 1861 including 0xff being reserved for Experimental Use. 1863 New entries in this registry require the following information: 1865 Stream Type: A name or label for the stream type. 1867 Code: The 8-bit code assigned to the stream type. 1869 Specification: A reference to a specification that includes a 1870 description of the stream type, including the layout semantics of 1871 its payload. 1873 Sender: Which endpoint on a connection may initiate a stream of this 1874 type. Values are "Client", "Server", or "Both". 1876 The entries in the following table are registered by this document. 1878 +----------------+------+---------------+--------+ 1879 | Stream Type | Code | Specification | Sender | 1880 +----------------+------+---------------+--------+ 1881 | Control Stream | 0x43 | Section 3.3.2 | Both | 1882 | | | | | 1883 | Push Stream | 0x50 | Section 3.3.3 | Server | 1884 +----------------+------+---------------+--------+ 1886 Additionally, for each code of the format "0x1f * N" for values of N 1887 in the range (0..8) (that is, "0x00", "0x1f", "0x3e", "0x5d", "0x7c", 1888 "0x9b", "0xba", "0xd9", "0xf8"), the following values should be 1889 registered: 1891 Stream Type: Reserved - GREASE 1893 Specification: Section 3.3.1 1895 Sender: Both 1897 11. References 1898 11.1. Normative References 1900 [QPACK] Krasic, C., Bishop, M., and A. Frindell, Ed., "QPACK: 1901 Header Compression for HTTP over QUIC", draft-ietf-quic- 1902 qpack-02 (work in progress), August 2018. 1904 [QUIC-TRANSPORT] 1905 Iyengar, J., Ed. and M. Thomson, Ed., "QUIC: A UDP-Based 1906 Multiplexed and Secure Transport", draft-ietf-quic- 1907 transport-13 (work in progress), August 2018. 1909 [RFC0793] Postel, J., "Transmission Control Protocol", STD 7, 1910 RFC 793, DOI 10.17487/RFC0793, September 1981, 1911 . 1913 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1914 Requirement Levels", BCP 14, RFC 2119, 1915 DOI 10.17487/RFC2119, March 1997, 1916 . 1918 [RFC5234] Crocker, D., Ed. and P. Overell, "Augmented BNF for Syntax 1919 Specifications: ABNF", STD 68, RFC 5234, 1920 DOI 10.17487/RFC5234, January 2008, 1921 . 1923 [RFC6066] Eastlake 3rd, D., "Transport Layer Security (TLS) 1924 Extensions: Extension Definitions", RFC 6066, 1925 DOI 10.17487/RFC6066, January 2011, 1926 . 1928 [RFC7230] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer 1929 Protocol (HTTP/1.1): Message Syntax and Routing", 1930 RFC 7230, DOI 10.17487/RFC7230, June 2014, 1931 . 1933 [RFC7231] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer 1934 Protocol (HTTP/1.1): Semantics and Content", RFC 7231, 1935 DOI 10.17487/RFC7231, June 2014, 1936 . 1938 [RFC7540] Belshe, M., Peon, R., and M. Thomson, Ed., "Hypertext 1939 Transfer Protocol Version 2 (HTTP/2)", RFC 7540, 1940 DOI 10.17487/RFC7540, May 2015, 1941 . 1943 [RFC7838] Nottingham, M., McManus, P., and J. Reschke, "HTTP 1944 Alternative Services", RFC 7838, DOI 10.17487/RFC7838, 1945 April 2016, . 1947 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 1948 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 1949 May 2017, . 1951 11.2. Informative References 1953 [RFC7301] Friedl, S., Popov, A., Langley, A., and E. Stephan, 1954 "Transport Layer Security (TLS) Application-Layer Protocol 1955 Negotiation Extension", RFC 7301, DOI 10.17487/RFC7301, 1956 July 2014, . 1958 [RFC8126] Cotton, M., Leiba, B., and T. Narten, "Guidelines for 1959 Writing an IANA Considerations Section in RFCs", BCP 26, 1960 RFC 8126, DOI 10.17487/RFC8126, June 2017, 1961 . 1963 11.3. URIs 1965 [1] https://mailarchive.ietf.org/arch/search/?email_list=quic 1967 [2] https://github.com/quicwg 1969 [3] https://github.com/quicwg/base-drafts/labels/-http 1971 [4] https://www.iana.org/assignments/message-headers 1973 Appendix A. Change Log 1975 *RFC Editor's Note:* Please remove this section prior to 1976 publication of a final version of this document. 1978 A.1. Since draft-ietf-quic-http-13 1980 o Reserved some frame types for grease (#1333, #1446) 1982 o Unknown unidirectional stream types are tolerated, not errors; 1983 some reserved for grease (#1490, #1525) 1985 o Require settings to be remembered for 0-RTT, prohibit reductions 1986 (#1541, #1641) 1988 o Specify behavior for truncated requests (#1596, #1643) 1990 A.2. Since draft-ietf-quic-http-12 1992 o TLS SNI extension isn't mandatory if an alternative method is used 1993 (#1459, #1462, #1466) 1995 o Removed flags from HTTP/QUIC frames (#1388, #1398) 1997 o Reserved frame types and settings for use in preserving 1998 extensibility (#1333, #1446) 2000 o Added general error code (#1391, #1397) 2002 o Unidirectional streams carry a type byte and are extensible 2003 (#910,#1359) 2005 o Priority mechanism now uses explicit placeholders to enable 2006 persistent structure in the tree (#441,#1421,#1422) 2008 A.3. Since draft-ietf-quic-http-11 2010 o Moved QPACK table updates and acknowledgments to dedicated streams 2011 (#1121, #1122, #1238) 2013 A.4. Since draft-ietf-quic-http-10 2015 o Settings need to be remembered when attempting and accepting 0-RTT 2016 (#1157, #1207) 2018 A.5. Since draft-ietf-quic-http-09 2020 o Selected QCRAM for header compression (#228, #1117) 2022 o The server_name TLS extension is now mandatory (#296, #495) 2024 o Specified handling of unsupported versions in Alt-Svc (#1093, 2025 #1097) 2027 A.6. Since draft-ietf-quic-http-08 2029 o Clarified connection coalescing rules (#940, #1024) 2031 A.7. Since draft-ietf-quic-http-07 2033 o Changes for integer encodings in QUIC (#595,#905) 2035 o Use unidirectional streams as appropriate (#515, #240, #281, #886) 2037 o Improvement to the description of GOAWAY (#604, #898) 2039 o Improve description of server push usage (#947, #950, #957) 2041 A.8. Since draft-ietf-quic-http-06 2043 o Track changes in QUIC error code usage (#485) 2045 A.9. Since draft-ietf-quic-http-05 2047 o Made push ID sequential, add MAX_PUSH_ID, remove 2048 SETTINGS_ENABLE_PUSH (#709) 2050 o Guidance about keep-alive and QUIC PINGs (#729) 2052 o Expanded text on GOAWAY and cancellation (#757) 2054 A.10. Since draft-ietf-quic-http-04 2056 o Cite RFC 5234 (#404) 2058 o Return to a single stream per request (#245,#557) 2060 o Use separate frame type and settings registries from HTTP/2 (#81) 2062 o SETTINGS_ENABLE_PUSH instead of SETTINGS_DISABLE_PUSH (#477) 2064 o Restored GOAWAY (#696) 2066 o Identify server push using Push ID rather than a stream ID 2067 (#702,#281) 2069 o DATA frames cannot be empty (#700) 2071 A.11. Since draft-ietf-quic-http-03 2073 None. 2075 A.12. Since draft-ietf-quic-http-02 2077 o Track changes in transport draft 2079 A.13. Since draft-ietf-quic-http-01 2081 o SETTINGS changes (#181): 2083 * SETTINGS can be sent only once at the start of a connection; no 2084 changes thereafter 2086 * SETTINGS_ACK removed 2088 * Settings can only occur in the SETTINGS frame a single time 2089 * Boolean format updated 2091 o Alt-Svc parameter changed from "v" to "quic"; format updated 2092 (#229) 2094 o Closing the connection control stream or any message control 2095 stream is a fatal error (#176) 2097 o HPACK Sequence counter can wrap (#173) 2099 o 0-RTT guidance added 2101 o Guide to differences from HTTP/2 and porting HTTP/2 extensions 2102 added (#127,#242) 2104 A.14. Since draft-ietf-quic-http-00 2106 o Changed "HTTP/2-over-QUIC" to "HTTP/QUIC" throughout (#11,#29) 2108 o Changed from using HTTP/2 framing within Stream 3 to new framing 2109 format and two-stream-per-request model (#71,#72,#73) 2111 o Adopted SETTINGS format from draft-bishop-httpbis-extended- 2112 settings-01 2114 o Reworked SETTINGS_ACK to account for indeterminate inter-stream 2115 order (#75) 2117 o Described CONNECT pseudo-method (#95) 2119 o Updated ALPN token and Alt-Svc guidance (#13,#87) 2121 o Application-layer-defined error codes (#19,#74) 2123 A.15. Since draft-shade-quic-http2-mapping-00 2125 o Adopted as base for draft-ietf-quic-http 2127 o Updated authors/editors list 2129 Acknowledgements 2131 The original authors of this specification were Robbie Shade and Mike 2132 Warres. 2134 A substantial portion of Mike's contribution was supported by 2135 Microsoft during his employment there. 2137 Author's Address 2139 Mike Bishop (editor) 2140 Akamai 2142 Email: mbishop@evequefou.be