idnits 2.17.1 draft-ietf-httpbis-http2-03.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 : ---------------------------------------------------------------------------- No issues found here. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year == Using lowercase 'not' together with uppercase 'MUST', 'SHALL', 'SHOULD', or 'RECOMMENDED' is not an accepted usage according to RFC 2119. Please use uppercase 'NOT' together with RFC 2119 keywords (if that is what you mean). Found 'MUST not' in this paragraph: o The Connection, Host, Keep-Alive, Proxy-Connection, and Transfer-Encoding header fields are no longer valid and MUST not be sent. == Using lowercase 'not' together with uppercase 'MUST', 'SHALL', 'SHOULD', or 'RECOMMENDED' is not an accepted usage according to RFC 2119. Please use uppercase 'NOT' together with RFC 2119 keywords (if that is what you mean). Found 'MUST not' in this paragraph: The Connection, Keep-Alive, Proxy-Connection, and Transfer-Encoding header fields are not valid and MUST not be sent. -- The document date (May 29, 2013) is 3984 days in the past. Is this intentional? Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) == Outdated reference: A later version (-26) exists of draft-ietf-httpbis-p1-messaging-22 == Outdated reference: A later version (-26) exists of draft-ietf-httpbis-p2-semantics-22 == Outdated reference: A later version (-26) exists of draft-ietf-httpbis-p4-conditional-22 == Outdated reference: A later version (-26) exists of draft-ietf-httpbis-p5-range-22 == Outdated reference: A later version (-26) exists of draft-ietf-httpbis-p6-cache-22 == Outdated reference: A later version (-26) exists of draft-ietf-httpbis-p7-auth-22 ** Obsolete normative reference: RFC 793 (Obsoleted by RFC 9293) ** Obsolete normative reference: RFC 2818 (Obsoleted by RFC 9110) ** Obsolete normative reference: RFC 5226 (Obsoleted by RFC 8126) ** Obsolete normative reference: RFC 5246 (Obsoleted by RFC 8446) == Outdated reference: A later version (-05) exists of draft-ietf-tls-applayerprotoneg-01 -- Obsolete informational reference (is this intentional?): RFC 1323 (Obsoleted by RFC 7323) Summary: 4 errors (**), 0 flaws (~~), 10 warnings (==), 2 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 HTTPbis Working Group M. Belshe 3 Internet-Draft Twist 4 Intended status: Standards Track R. Peon 5 Expires: November 30, 2013 Google, Inc 6 M. Thomson, Ed. 7 Microsoft 8 A. Melnikov, Ed. 9 Isode Ltd 10 May 29, 2013 12 Hypertext Transfer Protocol version 2.0 13 draft-ietf-httpbis-http2-03 15 Abstract 17 This specification describes an optimized expression of the syntax of 18 the Hypertext Transfer Protocol (HTTP). The HTTP/2.0 encapsulation 19 enables more efficient use of network resources and reduced 20 perception of latency by allowing header field compression and 21 multiple concurrent messages on the same connection. It also 22 introduces unsolicited push of representations from servers to 23 clients. 25 This document is an alternative to, but does not obsolete the 26 HTTP/1.1 message format or protocol. HTTP's existing semantics 27 remain unchanged. 29 Editorial Note (To be removed by RFC Editor) 31 Discussion of this draft takes place on the HTTPBIS working group 32 mailing list (ietf-http-wg@w3.org), which is archived at 33 . 35 Working Group information and related documents can be found at 36 (Wiki) and 37 (source code and issues 38 tracker). 40 The changes in this draft are summarized in Appendix A.1. 42 Status of This Memo 44 This Internet-Draft is submitted in full conformance with the 45 provisions of BCP 78 and BCP 79. 47 Internet-Drafts are working documents of the Internet Engineering 48 Task Force (IETF). Note that other groups may also distribute 49 working documents as Internet-Drafts. The list of current Internet- 50 Drafts is at http://datatracker.ietf.org/drafts/current/. 52 Internet-Drafts are draft documents valid for a maximum of six months 53 and may be updated, replaced, or obsoleted by other documents at any 54 time. It is inappropriate to use Internet-Drafts as reference 55 material or to cite them other than as "work in progress." 57 This Internet-Draft will expire on November 30, 2013. 59 Copyright Notice 61 Copyright (c) 2013 IETF Trust and the persons identified as the 62 document authors. All rights reserved. 64 This document is subject to BCP 78 and the IETF Trust's Legal 65 Provisions Relating to IETF Documents 66 (http://trustee.ietf.org/license-info) in effect on the date of 67 publication of this document. Please review these documents 68 carefully, as they describe your rights and restrictions with respect 69 to this document. Code Components extracted from this document must 70 include Simplified BSD License text as described in Section 4.e of 71 the Trust Legal Provisions and are provided without warranty as 72 described in the Simplified BSD License. 74 Table of Contents 76 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 5 77 1.1. Document Organization . . . . . . . . . . . . . . . . . . 5 78 1.2. Conventions and Terminology . . . . . . . . . . . . . . . 6 79 2. Starting HTTP/2.0 . . . . . . . . . . . . . . . . . . . . . . 6 80 2.1. HTTP/2.0 Version Identification . . . . . . . . . . . . . 7 81 2.2. Starting HTTP/2.0 for "http:" URIs . . . . . . . . . . . . 8 82 2.3. Starting HTTP/2.0 for "https:" URIs . . . . . . . . . . . 8 83 2.4. Starting HTTP/2.0 with Prior Knowledge . . . . . . . . . . 9 84 3. HTTP/2.0 Framing Layer . . . . . . . . . . . . . . . . . . . . 9 85 3.1. Connection . . . . . . . . . . . . . . . . . . . . . . . . 9 86 3.2. Connection Header . . . . . . . . . . . . . . . . . . . . 9 87 3.3. Framing . . . . . . . . . . . . . . . . . . . . . . . . . 10 88 3.3.1. Frame Header . . . . . . . . . . . . . . . . . . . . . 10 89 3.3.2. Frame Size . . . . . . . . . . . . . . . . . . . . . . 12 90 3.4. Streams . . . . . . . . . . . . . . . . . . . . . . . . . 12 91 3.4.1. Stream Creation . . . . . . . . . . . . . . . . . . . 13 92 3.4.2. Stream priority . . . . . . . . . . . . . . . . . . . 13 93 3.4.3. Stream half-close . . . . . . . . . . . . . . . . . . 14 94 3.4.4. Stream close . . . . . . . . . . . . . . . . . . . . . 14 95 3.5. Error Handling . . . . . . . . . . . . . . . . . . . . . . 15 96 3.5.1. Connection Error Handling . . . . . . . . . . . . . . 15 97 3.5.2. Stream Error Handling . . . . . . . . . . . . . . . . 16 98 3.5.3. Error Codes . . . . . . . . . . . . . . . . . . . . . 16 99 3.6. Stream Flow Control . . . . . . . . . . . . . . . . . . . 17 100 3.6.1. Flow Control Principles . . . . . . . . . . . . . . . 17 101 3.6.2. Appropriate Use of Flow Control . . . . . . . . . . . 18 102 3.7. Header Blocks . . . . . . . . . . . . . . . . . . . . . . 19 103 3.8. Frame Types . . . . . . . . . . . . . . . . . . . . . . . 19 104 3.8.1. DATA Frames . . . . . . . . . . . . . . . . . . . . . 20 105 3.8.2. HEADERS+PRIORITY . . . . . . . . . . . . . . . . . . . 20 106 3.8.3. RST_STREAM . . . . . . . . . . . . . . . . . . . . . . 21 107 3.8.4. SETTINGS . . . . . . . . . . . . . . . . . . . . . . . 21 108 3.8.5. PUSH_PROMISE . . . . . . . . . . . . . . . . . . . . . 25 109 3.8.6. PING . . . . . . . . . . . . . . . . . . . . . . . . . 26 110 3.8.7. GOAWAY . . . . . . . . . . . . . . . . . . . . . . . . 26 111 3.8.8. HEADERS . . . . . . . . . . . . . . . . . . . . . . . 28 112 3.8.9. WINDOW_UPDATE . . . . . . . . . . . . . . . . . . . . 29 113 4. HTTP Message Exchanges . . . . . . . . . . . . . . . . . . . . 32 114 4.1. Connection Management . . . . . . . . . . . . . . . . . . 32 115 4.2. HTTP Request/Response . . . . . . . . . . . . . . . . . . 33 116 4.2.1. HTTP Header Fields and HTTP/2.0 Headers . . . . . . . 33 117 4.2.2. Request . . . . . . . . . . . . . . . . . . . . . . . 33 118 4.2.3. Response . . . . . . . . . . . . . . . . . . . . . . . 34 119 4.3. Server Push Transactions . . . . . . . . . . . . . . . . . 35 120 4.3.1. Server implementation . . . . . . . . . . . . . . . . 36 121 4.3.2. Client implementation . . . . . . . . . . . . . . . . 37 122 5. Design Rationale and Notes . . . . . . . . . . . . . . . . . . 38 123 5.1. Separation of Framing Layer and Application Layer . . . . 38 124 5.2. Error handling - Framing Layer . . . . . . . . . . . . . . 39 125 5.3. One Connection per Domain . . . . . . . . . . . . . . . . 39 126 5.4. Fixed vs Variable Length Fields . . . . . . . . . . . . . 39 127 5.5. Server Push . . . . . . . . . . . . . . . . . . . . . . . 40 128 6. Security Considerations . . . . . . . . . . . . . . . . . . . 40 129 6.1. Server Authority and Same-Origin . . . . . . . . . . . . . 40 130 6.2. Cross-Protocol Attacks . . . . . . . . . . . . . . . . . . 40 131 6.3. Cacheability of Pushed Resources . . . . . . . . . . . . . 41 132 7. Privacy Considerations . . . . . . . . . . . . . . . . . . . . 41 133 7.1. Long Lived Connections . . . . . . . . . . . . . . . . . . 41 134 7.2. SETTINGS frame . . . . . . . . . . . . . . . . . . . . . . 41 135 8. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 42 136 8.1. Frame Type Registry . . . . . . . . . . . . . . . . . . . 42 137 8.2. Error Code Registry . . . . . . . . . . . . . . . . . . . 43 138 8.3. Settings Registry . . . . . . . . . . . . . . . . . . . . 43 139 9. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . 44 140 10. References . . . . . . . . . . . . . . . . . . . . . . . . . . 44 141 10.1. Normative References . . . . . . . . . . . . . . . . . . . 44 142 10.2. Informative References . . . . . . . . . . . . . . . . . . 45 143 Appendix A. Change Log (to be removed by RFC Editor before 144 publication) . . . . . . . . . . . . . . . . . . . . 46 146 A.1. Since draft-ietf-httpbis-http2-02 . . . . . . . . . . . . 46 147 A.2. Since draft-ietf-httpbis-http2-01 . . . . . . . . . . . . 46 148 A.3. Since draft-ietf-httpbis-http2-00 . . . . . . . . . . . . 47 149 A.4. Since draft-mbelshe-httpbis-spdy-00 . . . . . . . . . . . 47 151 1. Introduction 153 The Hypertext Transfer Protocol (HTTP) is a wildly successful 154 protocol. However, the HTTP/1.1 message encapsulation ([HTTP-p1], 155 Section 3) is optimized for implementation simplicity and 156 accessibility, not application performance. As such it has several 157 characteristics that have a negative overall effect on application 158 performance. 160 In particular, HTTP/1.0 only allows one request to be delivered at a 161 time on a given connection. HTTP/1.1 pipelining only partially 162 addressed request concurrency, and is not widely deployed. 163 Therefore, clients that need to make many requests (as is common on 164 the Web) typically use multiple connections to a server in order to 165 reduce perceived latency. 167 Furthermore, HTTP/1.1 header fields are often repetitive and verbose, 168 which, in addition to generating more or larger network packets, can 169 cause the small initial TCP congestion window to quickly fill. This 170 can result in excessive latency when multiple requests are made on a 171 single new TCP connection. 173 This document addresses these issues by defining an optimized mapping 174 of HTTP's semantics to an underlying connection. Specifically, it 175 allows interleaving of request and response messages on the same 176 connection and uses an efficient coding for HTTP header fields. It 177 also allows prioritization of requests, letting more important 178 requests complete more quickly, further improving perceived 179 performance. 181 The resulting protocol is designed to have be more friendly to the 182 network, because fewer TCP connections can be used, in comparison to 183 HTTP/1.x. This means less competition with other flows, and longer- 184 lived connections, which in turn leads to better utilization of 185 available network capacity. 187 Finally, this encapsulation also enables more scalable processing of 188 messages through use of binary message framing. 190 1.1. Document Organization 192 The HTTP/2.0 Specification is split into three parts: starting 193 HTTP/2.0 (Section 2), which covers how a HTTP/2.0 connection is 194 initiated; a framing layer (Section 3), which multiplexes a single 195 TCP connection into independent frames of various types; and an HTTP 196 layer (Section 4), which specifies the mechanism for expressing HTTP 197 interactions using the framing layer. While some of the framing 198 layer concepts are isolated from HTTP, building a generic framing 199 layer has not been a goal. The framing layer is tailored to the 200 needs of the HTTP protocol and server push. 202 1.2. Conventions and Terminology 204 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 205 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 206 document are to be interpreted as described in RFC 2119 [RFC2119]. 208 All numeric values are in network byte order. Values are unsigned 209 unless otherwise indicated. Literal values are provided in decimal 210 or hexadecimal as appropriate. Hexadecimal literals are prefixed 211 with "0x" to distinguish them from decimal literals. 213 The following terms are used: 215 client: The endpoint initiating the HTTP connection. 217 connection: A transport-level connection between two endpoints. 219 endpoint: Either the client or server of the connection. 221 frame: The smallest unit of communication within an HTTP/2.0 222 connection, consisting of a header and a variable-length sequence 223 of bytes structured according to the frame type. 225 peer: An endpoint. When discussing a particular endpoint, "peer" 226 refers to the endpoint that is remote to the primary subject of 227 discussion. 229 receiver: An endpoint that is receiving frames. 231 sender: An endpoint that is transmitting frames. 233 server: The endpoint which did not initiate the HTTP connection. 235 connection error: An error on the HTTP/2.0 connection. 237 stream: A bi-directional flow of frames across a virtual channel 238 within the HTTP/2.0 connection. 240 stream error: An error on the individual HTTP/2.0 stream. 242 2. Starting HTTP/2.0 244 HTTP/2.0 uses the same "http:" and "https:" URI schemes used by 245 HTTP/1.1. As a result, implementations processing requests for 246 target resource URIs like "http://example.org/foo" or 247 "https://example.com/bar" are required to first discover whether the 248 upstream server (the immediate peer to which the client wishes to 249 establish a connection) supports HTTP/2.0. 251 The means by which support for HTTP/2.0 is determined is different 252 for "http" and "https" URIs. Discovery for "https:" URIs is 253 described in Section 2.3. Discovery for "http" URIs is described 254 here. 256 2.1. HTTP/2.0 Version Identification 258 The protocol defined in this document is identified using the string 259 "HTTP/2.0". This identification is used in the HTTP/1.1 Upgrade 260 header field, in the TLS application layer protocol negotiation 261 extension [TLSALPN] field and other places where protocol 262 identification is required. 264 Negotiating "HTTP/2.0" implies the use of the transport, security, 265 framing and message semantics described in this document. 267 [[anchor3: Editor's Note: please remove the following text prior to 268 the publication of a final version of this document.]] 270 Only implementations of the final, published RFC can identify 271 themselves as "HTTP/2.0". Until such an RFC exists, implementations 272 MUST NOT identify themselves using "HTTP/2.0". 274 Examples and text throughout the rest of this document use "HTTP/2.0" 275 as a matter of editorial convenience only. Implementations of draft 276 versions MUST NOT identify using this string. 278 Implementations of draft versions of the protocol MUST add the string 279 "-draft-" and the corresponding draft number to the identifier before 280 the separator ('/'). For example, draft-ietf-httpbis-http2-03 is 281 identified using the string "HTTP-draft-03/2.0". 283 Non-compatible experiments that are based on these draft versions 284 MUST instead replace the string "draft" with a different identifier. 285 For example, an experimental implementation of packet mood-based 286 encoding based on draft-ietf-httpbis-http2-07 might identify itself 287 as "HTTP-emo-07/2.0". Note that any label MUST conform to the 288 "token" syntax defined in Section 3.2.6 of [HTTP-p1]. Experimenters 289 are encouraged to coordinate their experiments on the 290 ietf-http-wg@w3.org mailing list. 292 2.2. Starting HTTP/2.0 for "http:" URIs 294 A client that makes a request to an "http:" URI without prior 295 knowledge about support for HTTP/2.0 uses the HTTP Upgrade mechanism 296 (Section 6.7 of [HTTP-p1]). The client makes an HTTP/1.1 request 297 that includes an Upgrade header field identifying HTTP/2.0. 299 For example: 301 GET /default.htm HTTP/1.1 302 Host: server.example.com 303 Connection: Upgrade 304 Upgrade: HTTP/2.0 306 A server that does not support HTTP/2.0 can respond to the request as 307 though the Upgrade header field were absent: 309 HTTP/1.1 200 OK 310 Content-length: 243 311 Content-type: text/html 312 ... 314 A server that supports HTTP/2.0 can accept the upgrade with a 101 315 (Switching Protocols) status code. After the empty line that 316 terminates the 101 response, the server can begin sending HTTP/2.0 317 frames. These frames MUST include a response to the request that 318 initiated the Upgrade. 320 HTTP/1.1 101 Switching Protocols 321 Connection: Upgrade 322 Upgrade: HTTP/2.0 324 [ HTTP/2.0 connection ... 326 The first HTTP/2.0 frame sent by the server is a SETTINGS frame 327 (Section 3.8.4). Upon receiving the 101 response, the client sends a 328 connection header (Section 3.2), which includes a SETTINGS frame. 330 2.3. Starting HTTP/2.0 for "https:" URIs 332 A client that makes a request to an "https:" URI without prior 333 knowledge about support for HTTP/2.0 uses TLS [RFC5246] with the 334 application layer protocol negotiation extension [TLSALPN]. 336 Once TLS negotiation is complete, both the client and the server send 337 a connection header (Section 3.2). 339 2.4. Starting HTTP/2.0 with Prior Knowledge 341 A client can learn that a particular server supports HTTP/2.0 by 342 other means. A client MAY immediately send HTTP/2.0 frames to a 343 server that is known to support HTTP/2.0. This only affects the 344 resolution of "http:" URIs, servers supporting HTTP/2.0 are required 345 to support protocol negotiation in TLS [TLSALPN] for "https:" URIs. 347 Prior support for HTTP/2.0 is not a strong signal that a given server 348 will support HTTP/2.0 for future connections. It is possible for 349 server configurations to change or for configurations to differ 350 between instances in clustered server. Interception proxies (a.k.a. 351 "transparent" proxies) are another source of variability. 353 3. HTTP/2.0 Framing Layer 355 3.1. Connection 357 The HTTP/2.0 connection is an Application Level protocol running on 358 top of a TCP connection ([RFC0793]). The client is the TCP 359 connection initiator. 361 HTTP/2.0 connections are persistent. That is, for best performance, 362 it is expected a clients will not close connections until it is 363 determined that no further communication with a server is necessary 364 (for example, when a user navigates away from a particular web page), 365 or until the server closes the connection. 367 Servers are encouraged to maintain open connections for as long as 368 possible, but are permitted to terminate idle connections if 369 necessary. When either endpoint chooses to close the transport-level 370 TCP connection, the terminating endpoint MUST first send a GOAWAY 371 (Section 3.8.7) frame so that both endpoints can reliably determine 372 whether previously sent frames have been processed and gracefully 373 complete or terminate any necessary remaining tasks. 375 3.2. Connection Header 377 Upon establishment of a TCP connection and determination that 378 HTTP/2.0 will be used by both peers to communicate, each endpoint 379 MUST send a connection header as a final confirmation and to 380 establish the default parameters for the HTTP/2.0 connection. 382 The client connection header is a sequence of 24 octets (in hex 383 notation) 385 464f4f202a20485454502f322e300d0a0d0a42410d0a0d0a 386 (the string "FOO * HTTP/2.0\r\n\r\nBA\r\n\r\n") followed by a 387 SETTINGS frame (Section 3.8.4). The client sends the client 388 connection header immediately upon receipt of a 101 Switching 389 Protocols response (indicating a successful upgrade), or after 390 receiving a TLS Finished message from the server. If starting an 391 HTTP/2.0 connection with prior knowledge of server support for the 392 protocol, the client connection header is sent upon connection 393 establishment. 395 The client connection header is selected so that a large 396 proportion of HTTP/1.1 or HTTP/1.0 servers and intermediaries do 397 not attempt to process further frames. Note that this does not 398 address the concerns raised in [TALKING]. 400 The server connection header consists of just a SETTINGS frame 401 (Section 3.8.4) that MUST be the first frame the server sends in the 402 HTTP/2.0 connection. 404 To avoid unnecessary latency, clients are permitted to send 405 additional frames to the server immediately after sending the client 406 connection header, without waiting to receive the server connection 407 header. It is important to note, however, that the server connection 408 header SETTINGS frame might include parameters that necessarily alter 409 how a client is expected to communicate with the server. Upon 410 receiving the SETTINGS frame, the client is expected to honor any 411 parameters established. 413 Clients and servers MUST terminate the TCP connection if either peer 414 does not begin with a valid connection header. A GOAWAY frame 415 (Section 3.8.7) MAY be omitted if it is clear that the peer is not 416 using HTTP/2.0. 418 3.3. Framing 420 Once the HTTP/2.0 connection is established, clients and servers can 421 begin exchanging frames. 423 3.3.1. Frame Header 425 HTTP/2.0 frames share a common base format consisting of an 8-byte 426 header followed by 0 to 65535 bytes of data. 428 0 1 2 3 429 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 430 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 431 | Length (16) | Type (8) | Flags (8) | 432 +-+-------------+---------------+-------------------------------+ 433 |R| Stream Identifier (31) | 434 +-+-------------------------------------------------------------+ 435 | Frame Data (0...) ... 436 +---------------------------------------------------------------+ 438 Frame Header 440 The fields of the frame header are defined as: 442 Length: The length of the frame data expressed as an unsigned 16-bit 443 integer. The 8 bytes of the frame header are not included in this 444 value. 446 Type: The 8-bit type of the frame. The frame type determines how 447 the remainder of the frame header and data are interpreted. 448 Implementations MUST ignore unsupported and unrecognized frame 449 types. 451 Flags: An 8-bit field reserved for frame-type specific boolean 452 flags. 454 The least significant bit (0x1) - the FINAL bit - is defined for 455 all frame types as an indication that this frame is the last the 456 endpoint will send for the identified stream. Setting this flag 457 causes the stream to enter the half-closed state (Section 3.4.3). 458 Implementations MUST process the FINAL bit for all frames whose 459 stream identifier field is not 0x0. The FINAL bit MUST NOT be set 460 on frames that use a stream identifier of 0. 462 The remaining flags can be assigned semantics specific to the 463 indicated frame type. Flags that have no defined semantics for a 464 particular frame type MUST be ignored, and MUST be left unset (0) 465 when sending. 467 R: A reserved 1-bit field. The semantics of this bit are undefined 468 and the bit MUST remain unset (0) when sending and MUST be ignored 469 when receiving. 471 Stream Identifier: A 31-bit stream identifier (see Section 3.4.1). 472 A value 0 is reserved for frames that are associated with the 473 connection as a whole as opposed to an individual stream. 475 The structure and content of the remaining frame data is dependent 476 entirely on the frame type. 478 3.3.2. Frame Size 480 Implementations with limited resources might not be capable of 481 processing large frame sizes. Such implementations MAY choose to 482 place additional limits on the maximum frame size. However, all 483 implementations MUST be capable of receiving and processing frames 484 containing at least 8192 octets of data. [[anchor6: Ed. Question: 485 Does this minimum include the 8-byte header or just the frame data?]] 487 An implementation MUST terminate a stream immediately if it is unable 488 to process a frame due it's size. This is done by sending an 489 RST_STREAM frame (Section 3.8.3) containing the FRAME_TOO_LARGE error 490 code. 492 [[anchor7: : Need a 493 way to signal the maximum frame size; no way to RST_STREAM on non- 494 stream-related frames.]] 496 3.4. Streams 498 A "stream" is an independent, bi-directional sequence of frames 499 exchanged between the client and server within an HTTP/2.0 500 connection. Streams have several important characteristics: 502 o Streams can be established and used unilaterally or shared by 503 either the client or server. 505 o Streams can be rejected or cancelled by either endpoint. 507 o Multiple types of frames can be sent by either endpoint within a 508 single stream. 510 o The order in which frames are sent within a stream is significant. 511 Recipients are required to process frames in the order they are 512 received. 514 o Streams optionally carry a set of name-value header pairs that are 515 expressed within the headers block of HEADERS+PRIORITY, HEADERS, 516 or PUSH_PROMISE frames. 518 o A single HTTP/2.0 connection can contain multiple concurrently 519 active streams, with either endpoint interleaving frames from 520 multiple streams. 522 3.4.1. Stream Creation 524 There is no coordination or shared action between the client and 525 server required to create a stream. Rather, new streams are 526 established by sending a frame whose stream identifier field 527 references a previously unused stream identifier. 529 All streams are identified by an unsigned 31-bit integer. Streams 530 initiated by a client use odd numbered stream identifiers; those 531 initiated by the server use even numbered stream identifiers. A 532 stream identifier of zero MUST NOT be used to establish a new stream. 534 The identifier of a newly established stream MUST be numerically 535 greater than all previously established streams from that endpoint 536 within the HTTP/2.0 connection, unless the identifier has been 537 reserved using a PUSH_PROMISE (Section 3.8.5) frame. An endpoint 538 that receives an unexpected stream identifier MUST respond with a 539 connection error (Section 3.5.1) of type PROTOCOL_ERROR. 541 A peer can limit the total number of concurrently active streams 542 using the SETTINGS_MAX_CONCURRENT_STREAMS parameters within a 543 SETTINGS frame. The maximum concurrent streams setting is specific 544 to each endpoint and applies only to the peer. That is, clients 545 specify the maximum number of concurrent streams the server can 546 initiate, and servers specify the maximum number of concurrent 547 streams the client can initiate. Peer endpoints MUST NOT exceed this 548 limit. All concurrently active streams initiated by an endpoint, 549 including streams that are half-open (Section 3.4.3) in any 550 direction, count toward that endpoint's limit. 552 Stream identifiers cannot be reused within a connection. Long-lived 553 connections can cause an endpoint to exhaust the available range of 554 stream identifiers. A client that is unable to establish a new 555 stream identifier can establish a new connection for new streams. 557 Either endpoint can request the early termination of an unwanted 558 stream by sending an RST_STREAM frame (Section 3.5.2) with an error 559 code of either REFUSED_STREAM (if no frames have been processed) or 560 CANCEL (if at least one frame has been processed). Such termination 561 might not take effect immediately as the peer might have sent 562 additional frames on the stream prior to receiving the termination 563 request. 565 3.4.2. Stream priority 567 The endpoint establishing a new stream can assign a priority for the 568 stream. Priority is represented as an unsigned 31-bit integer. 0 569 represents the highest priority and 2^31-1 represents the lowest 570 priority. 572 The purpose of this value is to allow the initiating endpoint to 573 request that frames for the stream be processed with higher priority 574 relative to any other concurrently active streams. That is, if an 575 endpoint receives interleaved frames for multiple streams, the 576 endpoint ought to make a best-effort attempt at processing frames for 577 higher priority streams before processing those for lower priority 578 streams. 580 Explicitly setting the priority for a stream does not guarantee any 581 particular processing order for the stream relative to any other 582 stream. Nor is there is any mechanism provided by which the 583 initiator of a stream can force or require a receiving endpoint to 584 process frames from one stream before processing frames from another. 586 3.4.3. Stream half-close 588 When an endpoint sends a frame for a stream with the FINAL flag set, 589 the stream is considered to be half-closed for that endpoint. 590 Subsequent frames MUST NOT be sent by that endpoint for the half 591 closed stream for the remaining duration of the HTTP/2.0 connection. 592 When both endpoints have sent frames with the FINAL flag set, the 593 stream is considered to be fully closed. 595 If an endpoint receives additional frames for a stream that was 596 previously half-closed by the sending peer, the recipient MUST 597 respond with a stream error (Section 3.5.2) of type STREAM_CLOSED. 599 An endpoint that has not yet half-closed a stream by sending the 600 FINAL flag can continue sending frames on the stream. 602 It is not necessary for an endpoint to half-close a stream for which 603 it has not sent any frames. This allows endpoints to use fully 604 unidirectional streams that do not require explicit action or 605 acknowledgement from the receiver. 607 3.4.4. Stream close 609 Streams can be terminated in the following ways: 611 Normal termination: Normal stream termination occurs when both 612 client and server have half-closed the stream by sending a frame 613 containing a FINAL flag (Section 3.3.1). 615 Half-close on unidirectional stream: A stream that only has frames 616 sent in one direction can be tentatively considered to be closed 617 once a frame containing a FINAL flag is sent. The active sender 618 on the stream MUST be prepared to receive frames after closing the 619 stream. 621 Abrupt termination: Either peer can send a RST_STREAM control frame 622 at any time to terminate an active stream. RST_STREAM contains an 623 error code to indicate the reason for termination. A RST_STREAM 624 indicates that the sender will transmit no further data on the 625 stream and that the receiver is advised to cease transmission on 626 it. 628 The sender of a RST_STREAM frame MUST allow for frames that have 629 already been sent by the peer prior to the RST_STREAM being 630 processed. If in-transit frames alter connection state, these 631 frames cannot be safely discarded. See Stream Error Handling 632 (Section 3.5.2) for more details. 634 TCP connection teardown: If the TCP connection is torn down while 635 un-closed streams exist, then the endpoint MUST assume that the 636 stream was abnormally interrupted and may be incomplete. 638 3.5. Error Handling 640 HTTP/2.0 framing permits two classes of error: 642 o An error condition that renders the entire connection unusable is 643 a connection error. 645 o An error in an individual stream is a stream error. 647 3.5.1. Connection Error Handling 649 A connection error is any error which prevents further processing of 650 the framing layer or which corrupts any connection state. 652 An endpoint that encounters a connection error MUST first send a 653 GOAWAY (Section 3.8.7) frame with the stream identifier of the last 654 stream that it successfully received from its peer. The GOAWAY frame 655 includes an error code that indicates why the connection is 656 terminating. After sending the GOAWAY frame, the endpoint MUST close 657 the TCP connection. 659 It is possible that the GOAWAY will not be reliably received by the 660 receiving endpoint. In the event of a connection error, GOAWAY only 661 provides a best-effort attempt to communicate with the peer about why 662 the connection is being terminated. 664 An endpoint can end a connection at any time. In particular, an 665 endpoint MAY choose to treat a stream error as a connection error if 666 the error is recurrent. Endpoints SHOULD send a GOAWAY frame when 667 ending a connection, as long as circumstances permit it. 669 3.5.2. Stream Error Handling 671 A stream error is an error related to a specific stream identifier 672 that does not affect processing of other streams at the framing 673 layer. 675 An endpoint that detects a stream error sends a RST_STREAM 676 (Section 3.8.3) frame that contains the stream identifier of the 677 stream where the error occurred. The RST_STREAM frame includes an 678 error code that indicates the type of error. 680 A RST_STREAM is the last frame that an endpoint can send on a stream. 681 The peer that sends the RST_STREAM frame MUST be prepared to receive 682 any frames that were sent or enqueued for sending by the remote peer. 683 These frames can be ignored, except where they modify connection 684 state (such as the state maintained for header compression 685 (Section 3.7)). 687 Normally, an endpoint SHOULD NOT send more than one RST_STREAM frame 688 for any stream. However, an endpoint MAY send additional RST_STREAM 689 frames if it receives frames on a closed stream after more than a 690 round trip time. This behavior is permitted to deal with misbehaving 691 implementations. 693 An endpoint MUST NOT send a RST_STREAM in response to an RST_STREAM 694 frame, to avoid looping. 696 3.5.3. Error Codes 698 Error codes are 32-bit fields that are used in RST_STREAM and GOAWAY 699 frames to convey the reasons for the stream or connection error. 701 Error codes share a common code space. Some error codes only apply 702 to specific conditions and have no defined semantics in certain frame 703 types. 705 The following error codes are defined: 707 NO_ERROR (0): The associated condition is not as a result of an 708 error. For example, a GOAWAY might include this code to indicate 709 graceful shutdown of a connection. 711 PROTOCOL_ERROR (1): The endpoint detected an unspecific protocol 712 error. This error is for use when a more specific error code is 713 not available. 715 INTERNAL_ERROR (2): The endpoint encountered an unexpected internal 716 error. 718 FLOW_CONTROL_ERROR (3): The endpoint detected that its peer violated 719 the flow control protocol. 721 INVALID_STREAM (4): The endpoint received a frame for an inactive 722 stream. 724 STREAM_CLOSED (5): The endpoint received a frame after a stream was 725 half-closed. 727 FRAME_TOO_LARGE (6): The endpoint received a frame that was larger 728 than the maximum size that it supports. 730 REFUSED_STREAM (7): The endpoint is refusing the stream before 731 processing its payload. 733 CANCEL (8): Used by the creator of a stream to indicate that the 734 stream is no longer needed. 736 COMPRESSION_ERROR (9): The endpoint is unable to maintain the 737 compression context for the connection. 739 3.6. Stream Flow Control 741 Using streams for multiplexing introduces contention over use of the 742 TCP connection, resulting in blocked streams. A flow control scheme 743 ensures that streams on the same connection do not destructively 744 interfere with each other. 746 HTTP/2.0 provides for flow control through use of the WINDOW_UPDATE 747 (Section 3.8.9) frame type. 749 3.6.1. Flow Control Principles 751 Experience with TCP congestion control has shown that algorithms can 752 evolve over time to become more sophisticated without requiring 753 protocol changes. TCP congestion control and its evolution is 754 clearly different from HTTP/2.0 flow control, though the evolution of 755 TCP congestion control algorithms shows that a similar approach could 756 be feasible for HTTP/2.0 flow control. 758 HTTP/2.0 stream flow control aims to allow for future improvements to 759 flow control algorithms without requiring protocol changes. Flow 760 control in HTTP/2.0 has the following characteristics: 762 1. Flow control is hop-by-hop, not end-to-end. 764 2. Flow control is based on window update frames. Receivers 765 advertise how many octets they are prepared to receive on a 766 stream. This is a credit-based scheme. 768 3. Flow control is directional with overall control provided by the 769 receiver. A receiver MAY choose to set any window size that it 770 desires for each stream and for the entire connection. A sender 771 MUST respect flow control limits imposed by a receiver. Clients, 772 servers and intermediaries all independently advertise their flow 773 control preferences as a receiver and abide by the flow control 774 limits set by their peer when sending. 776 4. The initial value for the flow control window is 65536 bytes for 777 both new streams and the overall connection. 779 5. The frame type determines whether flow control applies to a 780 frame. Of the frames specified in this document, only data 781 frames are subject to flow control; all other frame types do not 782 consume space in the advertised flow control window. This 783 ensures that important control frames are not blocked by flow 784 control. 786 6. Flow control can be disabled by a receiver. A receiver can 787 choose to either disable flow control for a stream or connection 788 by declaring an infinite flow control limit. 790 7. HTTP/2.0 standardizes only the format of the window update frame 791 (Section 3.8.9). This does not stipulate how a receiver decides 792 when to send this frame or the value that it sends. Nor does it 793 specify how a sender chooses to send packets. Implementations 794 are able to select any algorithm that suits their needs. 796 Implementations are also responsible for managing how requests and 797 responses are sent based on priority; choosing how to avoid head of 798 line blocking for requests; and managing the creation of new streams. 799 Algorithm choices for these could interact with any flow control 800 algorithm. 802 3.6.2. Appropriate Use of Flow Control 804 Flow control is defined to protect endpoints (client, server or 805 intermediary) that are operating under resource constraints. For 806 example, a proxy needs to share memory between many connections, and 807 also might have a slow upstream connection and a fast downstream one. 808 Flow control addresses cases where the receiver is unable process 809 data on one stream, yet wants to continue to process other streams in 810 the same connection. 812 Deployments that do not require this capability SHOULD disable flow 813 control for data that is being received. Note that flow control 814 cannot be disabled for sending. Sending data is always subject to 815 the flow control window advertised by the receiver. 817 Deployments with constrained resources (for example, memory) MAY 818 employ flow control to limit the amount of memory a peer can consume. 819 Note, however, that this can lead to suboptimal use of available 820 network resources if flow control is enabled without knowledge of the 821 bandwidth-delay product (see [RFC1323]). 823 Even with full awareness of the current bandwidth-delay product, 824 implementation of flow control is difficult. However, it can ensure 825 that constrained resources are protected without any reduction in 826 connection utilization. 828 3.7. Header Blocks 830 The header block is found in the HEADERS, HEADERS+PRIORITY and 831 PUSH_PROMISE frames. The header block consists of a set of header 832 fields, which are name-value pairs. Headers are compressed using 833 black magic. 835 Compression of header fields is a work in progress, as is the format 836 of this block. 838 The contents of header blocks MUST be processed by the compression 839 context, even if stream has been reset or the frame is discarded. If 840 header blocks cannot be processed, the receiver MUST treat the 841 connection with a connection error (Section 3.5.1) of type 842 COMPRESSION_ERROR. 844 3.8. Frame Types 846 This specification defines a number of frame types, each identified 847 by a unique 8-bit type code. Each frame type serves a distinct 848 purpose either in the establishment and management of the connection 849 as a whole, or of individual streams. 851 The transmission of specific frame types can alter the state of a 852 connection. If endpoints fail to maintain a synchronized view of the 853 connection state, successful communication within the connection will 854 no longer be possible. Therefore, it is important that endpoints 855 have a shared comprehension of how the state is affected by the use 856 any given frame. Accordingly, while it is expected that new frame 857 types will be introduced by extensions to this protocol, only frames 858 defined by this document are permitted to alter the connection state. 860 3.8.1. DATA Frames 862 DATA frames (type=0x0) convey arbitrary, variable-length sequences of 863 octets associated with a stream. One or more DATA frames are used, 864 for instance, to carry HTTP request or response payloads. 866 The DATA frame does not define any type-specific flags. 868 DATA frames MUST be associated with a stream. If a DATA frame is 869 received whose stream identifier field is 0x0, the recipient MUST 870 respond with a connection error (Section 3.5.1) of type 871 PROTOCOL_ERROR. 873 3.8.2. HEADERS+PRIORITY 875 The HEADERS+PRIORITY frame (type=0x1) allows the sender to set header 876 fields and stream priority at the same time. 878 0 1 2 3 879 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 880 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 881 |X| Priority (31) | 882 +-+-------------------------------------------------------------+ 883 | Header Block (*) ... 884 +---------------------------------------------------------------+ 886 HEADERS+PRIORITY Frame Payload 888 The HEADERS+PRIORITY frame is identical to the HEADERS frame 889 (Section 3.8.8), preceded by a single reserved bit and a 31-bit 890 priority; see Section 3.4.2. 892 HEADERS+PRIORITY uses the same flags as the HEADERS frame, except 893 that a HEADERS+PRIORITY frame with a CONTINUES bit MUST be followed 894 by another HEADERS+PRIORITY frame. See HEADERS frame (Section 3.8.8) 895 for any flags. 897 HEADERS+PRIORITY frames MUST be associated with a stream. If a 898 HEADERS+PRIORITY frame is received whose stream identifier field is 899 0x0, the recipient MUST respond with a connection error 900 (Section 3.5.1) of type PROTOCOL_ERROR. 902 The HEADERS+PRIORITY frame modifies the connection state as defined 903 in Section 3.7. 905 3.8.3. RST_STREAM 907 The RST_STREAM frame (type=0x3) allows for abnormal termination of a 908 stream. When sent by the initiator of a stream, it indicates that 909 they wish to cancel the stream. When sent by the receiver of a 910 stream, it indicates that either the receiver is rejecting the 911 stream, requesting that the stream be cancelled or that an error 912 condition has occurred. 914 0 1 2 3 915 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 916 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 917 | Error Code (32) | 918 +---------------------------------------------------------------+ 920 RST_STREAM Frame Payload 922 The RST_STREAM frame contains a single unsigned, 32-bit integer 923 identifying the error code (Section 3.5.3). The error code indicates 924 why the stream is being terminated. 926 No type-flags are defined. 928 The RST_STREAM frame fully terminates the referenced stream and 929 causes it to enter the closed state. After receiving a RST_STREAM on 930 a stream, the receiver MUST NOT send additional frames for that 931 stream. However, after sending the RST_STREAM, the sending endpoint 932 MUST be prepared to receive and process additional frames sent on the 933 stream that might have been sent by the peer prior to the arrival of 934 the RST_STREAM. 936 RST_STREAM frames MUST be associated with a stream. If a RST_STREAM 937 frame is received whose stream identifier field is 0x0 the recipient 938 MUST respond with a connection error (Section 3.5.1) of type 939 PROTOCOL_ERROR. 941 3.8.4. SETTINGS 943 The SETTINGS frame (type=0x4) conveys configuration parameters that 944 affect how endpoints communicate. The parameters are either 945 constraints on peer behavior or preferences. 947 SETTINGS frames MUST be sent at the start of a connection, and MAY be 948 sent at any other time by either endpoint over the lifetime of the 949 connection. 951 Implementations MUST support all of the settings defined by this 952 specification and MAY support additional settings defined by 953 extensions. Unsupported or unrecognized settings MUST be ignored. 954 New settings MUST NOT be defined or implemented in a way that 955 requires endpoints to understand then in order to communicate 956 successfully. 958 A SETTINGS frame is not required to include every defined setting; 959 senders can include only those parameters for which it has accurate 960 values and a need to convey. When multiple parameters are sent, they 961 SHOULD be sent in order of numerically lowest ID to highest ID. A 962 single SETTINGS frame MUST NOT contain multiple values for the same 963 ID. If the receiver of a SETTINGS frame discovers multiple values 964 for the same ID, it MUST ignore all values for that ID except the 965 first one. 967 Over the lifetime of a connection, an endpoint MAY send multiple 968 SETTINGS frames containing previously unspecified parameters or new 969 values for parameters whose values have already been established. 970 Only the most recent value provided setting value applies. 972 The SETTINGS frame defines the following flag: 974 CLEAR_PERSISTED (0x2): Bit 2 being set indicates a request to clear 975 any previously persisted settings before processing the settings. 976 Clients MUST NOT set this flag. 978 SETTINGS frames always apply to a connection, never a single stream. 979 The stream identifier for a settings frame MUST be zero. If an 980 endpoint receives a SETTINGS frame whose stream identifier field is 981 anything other than 0x0, the endpoint MUST respond with a connection 982 error (Section 3.5.1) of type PROTOCOL_ERROR. 984 3.8.4.1. Setting Format 986 The payload of a SETTINGS frame consists of zero or more settings. 987 Each setting consists of an 8-bit flags field specifying per-item 988 instructions, an unsigned 24-bit setting identifier, and an unsigned 989 32-bit value. 991 0 1 2 3 992 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 993 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 994 |SettingFlags(8)| Setting Identifier (24) | 995 +---------------+-----------------------------------------------+ 996 | Value (32) | 997 +---------------------------------------------------------------+ 998 Setting Format 1000 Two flags are defined for the 8-bit flags field: 1002 PERSIST_VALUE (0x1): Bit 1 (the least significant bit) being set 1003 indicates a request from the server to the client to persist this 1004 setting. A client MUST NOT set this flag. 1006 PERSISTED (0x2): Bit 2 being set indicates that this setting is a 1007 persisted setting being returned by the client to the server. 1008 This also indicates that this setting is not a client setting, but 1009 a value previously set by the server. A server MUST NOT set this 1010 flag. 1012 3.8.4.2. Setting Persistence 1014 [[anchor12: Note that persistence of settings is under discussion in 1015 the WG and might be removed in a future version of this document.]] 1017 A server endpoint can request that configuration parameters sent to a 1018 client in a SETTINGS frame are to be persisted by the client across 1019 HTTP/2.0 connections and returned to the server in any new SETTINGS 1020 frame the client sends to the server in the current connection or any 1021 future connections. 1023 Persistence is requested on a per-setting basis by setting the 1024 PERSIST_VALUE flag (0x1). 1026 Client endpoints are not permitted to make such requests. Servers 1027 MUST ignore any attempt by clients to request that a server persist 1028 configuration parameters. 1030 Persistence of configuration parameters is done on a per-origin basis 1031 (see [RFC6454]). That is, when a client establishes a connection 1032 with a server, and the server requests that the client maintain 1033 persistent settings, the client SHOULD return the persisted settings 1034 on all future connections to the same origin, IP address and TCP 1035 port. 1037 Whenever the client sends a SETTINGS frame in the current connection, 1038 or establishes a new connection with the same origin, persisted 1039 configuration parameters are sent with the PERSISTED flag (0x2) set 1040 for each persisted parameter. 1042 Persisted settings accumulate until the server requests that all 1043 previously persisted settings are to be cleared by setting the 1044 CLEAR_PERSISTED (0x2) flag on the SETTINGS frame. 1046 For example, if the server sends IDs 1, 2, and 3 with the 1047 FLAG_SETTINGS_PERSIST_VALUE in a first SETTINGS frame, and then sends 1048 IDs 4 and 5 with the FLAG_SETTINGS_PERSIST_VALUE in a subsequent 1049 SETTINGS frame, the client will return values for all 5 settings (1, 1050 2, 3, 4, and 5 in this example) to the server. 1052 3.8.4.3. Defined Settings 1054 The following settings are defined: 1056 SETTINGS_UPLOAD_BANDWIDTH (1): indicates the sender's estimated 1057 upload bandwidth for this connection. The value is an the 1058 integral number of kilobytes per second that the sender predicts 1059 as an expected maximum upload channel capacity. 1061 SETTINGS_DOWNLOAD_BANDWIDTH (2): indicates the sender's estimated 1062 download bandwidth for this connection. The value is an integral 1063 number of kilobytes per second that the sender predicts as an 1064 expected maximum download channel capacity. 1066 SETTINGS_ROUND_TRIP_TIME (3): indicates the sender's estimated 1067 round-trip-time for this connection. The round trip time is 1068 defined as the minimum amount of time to send a control frame from 1069 this client to the remote and receive a response. The value is 1070 represented in milliseconds. 1072 SETTINGS_MAX_CONCURRENT_STREAMS (4): indicates the maximum number of 1073 concurrent streams that the sender will allow. This limit is 1074 directional: it applies to the number of streams that the sender 1075 permits the receiver to create. By default there is no limit. It 1076 is recommended that this value be no smaller than 100, so as to 1077 not unnecessarily limit parallelism. 1079 SETTINGS_CURRENT_CWND (5): indicates the sender's current TCP CWND 1080 value. 1082 SETTINGS_DOWNLOAD_RETRANS_RATE (6): indicates the sender's 1083 retransmission rate (bytes retransmitted / total bytes 1084 transmitted). 1086 SETTINGS_INITIAL_WINDOW_SIZE (7): indicates the sender's initial 1087 stream window size (in bytes) for new streams. 1089 SETTINGS_FLOW_CONTROL_OPTIONS (10): indicates that streams directed 1090 to the sender will not be subject to flow control. The least 1091 significant bit (0x1) is set to indicate that new streams are not 1092 flow controlled. All other bits are reserved. 1094 This setting applies to all streams, including existing streams. 1096 These bits cannot be cleared once set, see Section 3.8.9.4. 1098 3.8.5. PUSH_PROMISE 1100 The PUSH_PROMISE frame (type=0x5) is used to notify the peer endpoint 1101 in advance of streams the sender intends to initiate. The 1102 PUSH_PROMISE frame includes the unsigned 31-bit identifier of the 1103 stream the endpoint plans to create along with a minimal set of 1104 headers that provide additional context for the stream. Section 4.3 1105 contains a thorough description of the use of PUSH_PROMISE frames. 1107 0 1 2 3 1108 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 1109 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1110 |X| Promised-Stream-ID (31) | 1111 +-+-------------------------------------------------------------+ 1112 | Header Block (*) ... 1113 +---------------------------------------------------------------+ 1115 PUSH_PROMISE Payload Format 1117 The payload of a PUSH_PROMISE includes a "Promised-Stream-ID". This 1118 unsigned 31-bit integer identifies the stream the endpoint intends to 1119 start sending frames for. The promised stream identifier MUST be a 1120 valid choice for the next stream sent by the sender (see new stream 1121 identifier (Section 3.4.1)). 1123 PUSH_PROMISE frames MUST be associated with an existing stream. If 1124 the stream identifier field specifies the value 0x0, a recipient MUST 1125 respond with a connection error (Section 3.5.1) of type 1126 PROTOCOL_ERROR. 1128 The state of promised streams is bound to the state of the original 1129 associated stream on which the PUSH_PROMISE frame were sent. If the 1130 originating stream state changes to fully closed, all associated 1131 promised streams fully close as well. [[anchor13: Ed. Note: We need 1132 clarification on this point. How synchronized are the lifecycles of 1133 streams and associated promised streams?]] 1135 PUSH_PROMISE uses the same flags as the HEADERS frame, except that a 1136 PUSH_PROMISE frame with a CONTINUES bit MUST be followed by another 1137 PUSH_PROMISE frame. See HEADERS frame (Section 3.8.8) for any flags. 1139 Promised streams are not required to be used in order promised. The 1140 PUSH_PROMISE only reserves stream identifiers for later use. 1142 Recipients of PUSH_PROMISE frames can choose to reject promised 1143 streams by returning a RST_STREAM referencing the promised stream 1144 identifier back to the sender of the PUSH_PROMISE. 1146 The PUSH_PROMISE frame modifies the connection state as defined in 1147 Section 3.7. 1149 3.8.6. PING 1151 The PING frame (type=0x6) is a mechanism for measuring a minimal 1152 round-trip time from the sender, as well as determining whether an 1153 idle connection is still functional. PING frames can be sent from 1154 any endpoint. 1156 PING frames consist of an arbitrary, variable-length sequence of 1157 octets. Receivers of a PING send a response PING frame with the PONG 1158 flag set and precisely the same sequence of octets back to the sender 1159 as soon as possible. 1161 Processing of PING frames SHOULD be performed with the highest 1162 priority if there are additional frames waiting to be processed. 1164 The PING frame defines one type-specific flag: 1166 PONG (0x2): Bit 2 being set indicates that this PING frame is a PING 1167 response. An endpoint MUST set this flag in PING responses. An 1168 endpoint MUST NOT respond to PING frames containing this flag. 1170 PING frames are not associated with any individual stream. If a PING 1171 frame is received with a stream identifier field value other than 1172 0x0, the recipient MUST respond with a connection error 1173 (Section 3.5.1) of type PROTOCOL_ERROR. 1175 3.8.7. GOAWAY 1177 The GOAWAY frame (type=0x7) informs the remote peer to stop creating 1178 streams on this connection. It can be sent from the client or the 1179 server. Once sent, the sender will ignore frames sent on new streams 1180 for the remainder of the connection. Receivers of a GOAWAY frame 1181 MUST NOT open additional streams on the connection, although a new 1182 connection can be established for new streams. The purpose of this 1183 frame is to allow an endpoint to gracefully stop accepting new 1184 streams (perhaps for a reboot or maintenance), while still finishing 1185 processing of previously established streams. 1187 There is an inherent race condition between an endpoint starting new 1188 streams and the remote sending a GOAWAY frame. To deal with this 1189 case, the GOAWAY contains the stream identifier of the last stream 1190 which was processed on the sending endpoint in this connection. If 1191 the receiver of the GOAWAY used streams that are newer than the 1192 indicated stream identifier, they were not processed by the sender 1193 and the receiver may treat the streams as though they had never been 1194 created at all (hence the receiver may want to re-create the streams 1195 later on a new connection). 1197 Endpoints should always send a GOAWAY frame before closing a 1198 connection so that the remote can know whether a stream has been 1199 partially processed or not. (For example, if an HTTP client sends a 1200 POST at the same time that a server closes a connection, the client 1201 cannot know if the server started to process that POST request if the 1202 server does not send a GOAWAY frame to indicate where it stopped 1203 working). 1205 After sending a GOAWAY frame, the sender can ignore frames for new 1206 streams. 1208 [[anchor14: Issue: connection state that is established by those 1209 "ignored" frames cannot be ignored without the state in the two peers 1210 becoming unsynchronized.]] 1212 0 1 2 3 1213 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 1214 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1215 |X| Last-Stream-ID (31) | 1216 +-+-------------------------------------------------------------+ 1217 | Error Code (32) | 1218 +---------------------------------------------------------------+ 1220 GOAWAY Payload Format 1222 The GOAWAY frame does not define any type-specific flags. 1224 The GOAWAY frame applies to the connection, not a specific stream. 1225 The stream identifier MUST be zero. 1227 The last stream identifier in the GOAWAY frame contains the highest 1228 numbered stream identifier for which the sender of the GOAWAY frame 1229 has received frames on and might have taken some action on. All 1230 streams up to and including the identified stream might have been 1231 processed in some way. The last stream identifier is set to 0 if no 1232 streams were processed. 1234 Note: In this case, "processed" means that some data from the 1235 stream was passed to some higher layer of software that might have 1236 taken some action as a result. 1238 On streams with lower or equal numbered identifiers that do not close 1239 completely prior to the connection being closed, re-attempting 1240 requests, transactions, or any protocol activity is not possible 1241 (with the exception of idempotent actions like HTTP GET, PUT, or 1242 DELETE). Any protocol activity that uses higher numbered streams can 1243 be safely retried using a new connection. 1245 Activity on streams numbered lower or equal to the last stream 1246 identifier might still complete successfully. The sender of a GOAWAY 1247 frame gracefully shut down a connection by sending a GOAWAY frame, 1248 maintaining the connection in an open state until all in-progress 1249 streams complete. 1251 The last stream ID MUST be 0 if no streams were acted upon. 1253 The GOAWAY frame also contains a 32-bit error code (Section 3.5.3) 1254 that contains the reason for closing the connection. 1256 3.8.8. HEADERS 1258 The HEADERS frame (type=0x8) provides header fields for a stream. 1259 Any number of HEADERS frames can may be sent on an existing stream at 1260 any time. 1262 Additional type-specific flags for the HEADERS frame are: 1264 CONTINUES (0x2): The CONTINUES bit indicates that this frame does 1265 not contain the entire payload necessary to provide a complete set 1266 of headers. 1268 The payload for a complete set of headers is provided by a 1269 sequence of HEADERS frames, terminated by a HEADERS frame without 1270 the CONTINUES bit. Once the sequence terminates, the payload of 1271 all HEADERS frames are concatenated and interpreted as a single 1272 block. 1274 A HEADERS frame that includes a CONTINUES bit MUST be followed by 1275 a HEADERS frame for the same stream. A receiver MUST treat the 1276 receipt of any other type of frame or a frame on a different 1277 stream as a connection error (Section 3.5.1) of type 1278 PROTOCOL_ERROR. 1280 The payload of a HEADERS frame contains a Headers Block 1281 (Section 3.7). 1283 The HEADERS frame is associated with an existing stream. If a 1284 HEADERS frame is received with a stream identifier of 0x0, the 1285 recipient MUST respond with a stream error (Section 3.5.2) of type 1286 PROTOCOL_ERROR. 1288 The HEADERS frame changes the connection state as defined in 1289 Section 3.7. 1291 3.8.9. WINDOW_UPDATE 1293 The WINDOW_UPDATE frame (type=0x9) is used to implement flow control. 1295 Flow control operates at two levels: on each individual stream and on 1296 the entire connection. 1298 Both types of flow control are hop by hop; that is, only between the 1299 two endpoints. Intermediaries do not forward WINDOW_UPDATE frames 1300 between dependent connections. However, throttling of data transfer 1301 by any receiver can indirectly cause the propagation of flow control 1302 information toward the original sender. 1304 Flow control only applies to frames that are identified as being 1305 subject to flow control. Of the frame types defined in this 1306 document, this includes only DATA frame. Frames that are exempt from 1307 flow control MUST be accepted and processed, unless the receiver is 1308 unable to assign resources to handling the frame. A receiver MAY 1309 respond with a stream error (Section 3.5.2) or connection error 1310 (Section 3.5.1) of type FLOW_CONTROL_ERROR if it is unable accept a 1311 frame. 1313 The following additional flags are defined for the WINDOW_UPDATE 1314 frame: 1316 END_FLOW_CONTROL (0x2): Bit 2 being set indicates that flow control 1317 for the identified stream or connection has been ended; subsequent 1318 frames do not need to be flow controlled. 1320 The WINDOW_UPDATE frame can be specific to a stream or to the entire 1321 connection. In the former case, the frame's stream identifier 1322 indicates the affected stream; in the latter, the value "0" indicates 1323 that the entire connection is the subject of the frame. 1325 The payload of a WINDOW_UPDATE frame is a 32-bit value indicating the 1326 additional number of bytes that the sender can transmit in addition 1327 to the existing flow control window. The legal range for this field 1328 is 1 to 2^31 - 1 (0x7fffffff) bytes; the most significant bit of this 1329 value is reserved. 1331 3.8.9.1. The Flow Control Window 1333 Flow control in HTTP/2.0 is implemented using a window kept by each 1334 sender on every stream. The flow control window is a simple integer 1335 value that indicates how many bytes of data the sender is permitted 1336 to transmit; as such, its size is a measure of the buffering 1337 capability of the receiver. 1339 Two flow control windows are applicable; the stream flow control 1340 window and the connection flow control window. The sender MUST NOT 1341 send a flow controlled frame with a length that exceeds the space 1342 available in either of the flow control windows advertised by the 1343 receiver. Frames with zero length with the FINAL flag set (for 1344 example, an empty data frame) MAY be sent if there is no available 1345 space in either flow control window. 1347 For flow control calculations, the 8 byte frame header is not 1348 counted. 1350 After sending a flow controlled frame, the sender reduces the space 1351 available in both windows by the length of the transmitted frame. 1353 The receiver of a frame sends a WINDOW_UPDATE frame as it consumes 1354 data and frees up space in flow control windows. Separate 1355 WINDOW_UPDATE frames are sent for the stream and connection level 1356 flow control windows. 1358 A sender that receives a WINDOW_UPDATE frame updates the 1359 corresponding window by the amount specified in the frame. 1361 A sender MUST NOT allow a flow control window to exceed 2^31 - 1 1362 bytes. If a sender receives a WINDOW_UPDATE that causes a flow 1363 control window to exceed this maximum it MUST terminate either the 1364 stream or the connection, as appropriate. For streams, the sender 1365 sends a RST_STREAM with the error code of FLOW_CONTROL_ERROR code; 1366 for the connection, a GOAWAY frame with a FLOW_CONTROL_ERROR code. 1368 Flow controlled frames from the sender and WINDOW_UPDATE frames from 1369 the receiver are completely asynchronous with respect to each other. 1370 This property allows a receiver to aggressively update the window 1371 size kept by the sender to prevent streams from stalling. 1373 3.8.9.2. Initial Flow Control Window Size 1375 When a HTTP/2.0 connection is first established, new streams are 1376 created with an initial flow control window size of 65535 bytes. The 1377 connection flow control window is 65536 bytes. Both endpoints can 1378 adjust the initial window size for new streams by including a value 1379 for SETTINGS_INITIAL_WINDOW_SIZE in the SETTINGS frame that forms 1380 part of the connection header. 1382 Prior to receiving a SETTINGS frame that sets a value for 1383 SETTINGS_INITIAL_WINDOW_SIZE, a client can only use the default 1384 initial window size when sending flow controlled frames. Similarly, 1385 the connection flow control window is set to the default initial 1386 window size until a WINDOW_UPDATE frame is received. 1388 A SETTINGS frame can alter the initial flow control window size for 1389 all current streams. When the value of SETTINGS_INITIAL_WINDOW_SIZE 1390 changes, a receiver MUST adjust the size of all flow control windows 1391 that it maintains by the difference between the new value and the old 1392 value. 1394 A change to SETTINGS_INITIAL_WINDOW_SIZE could cause the available 1395 space in a flow control window to become negative. A sender MUST 1396 track the negative flow control window, and MUST NOT send new flow 1397 controlled frames until it receives WINDOW_UPDATE frames that cause 1398 the flow control window to become positive. 1400 For example, if the server sets the initial window size to be 16KB, 1401 and the client sends 64KB immediately on connection establishment, 1402 the client will recalculate the available flow control window to be 1403 -48KB on receipt of the SETTINGS frame. The client retains a 1404 negative flow control window until WINDOW_UPDATE frames restore the 1405 window to being positive, after which the client can resume sending. 1407 3.8.9.3. Reducing the Stream Window Size 1409 A receiver that wishes to use a smaller flow control window than the 1410 current size can send a new SETTINGS frame. However, the receiver 1411 MUST be prepared to receive data that exceeds this window size, since 1412 the sender might send data that exceeds the lower limit prior to 1413 processing the SETTINGS frame. 1415 A receiver has two options for handling streams that exceed flow 1416 control limits: 1418 1. The receiver can immediately send RST_STREAM with 1419 FLOW_CONTROL_ERROR error code for the affected streams. 1421 2. The receiver can accept the streams and tolerate the resulting 1422 head of line blocking, sending WINDOW_UPDATE frames as it 1423 consumes data. 1425 If a receiver decides to accept streams, both sides MUST recompute 1426 the available flow control window based on the initial window size 1427 sent in the SETTINGS. 1429 3.8.9.4. Ending Flow Control 1431 After a receiver reads in a frame that marks the end of a stream (for 1432 example, a data stream with a FINAL flag set), it MUST cease 1433 transmission of WINDOW_UPDATE frames for that stream. A sender is 1434 not obligated to maintain the available flow control window for 1435 streams that it is no longer sending on. 1437 Flow control can be disabled for all streams or the connection using 1438 the SETTINGS_FLOW_CONTROL_OPTIONS setting. An implementation that 1439 does not wish to perform flow control can use this in the initial 1440 SETTINGS exchange. 1442 Flow control can be disabled for an individual stream or the overall 1443 connection by sending a WINDOW_UPDATE with the END_FLOW_CONTROL flag 1444 set. The payload of a WINDOW_UPDATE frame that has the 1445 END_FLOW_CONTROL flag set is ignored. 1447 Flow control cannot be enabled again once disabled. Any attempt to 1448 re-enable flow control - by sending a WINDOW_UPDATE or by clearing 1449 the bits on the SETTINGS_FLOW_CONTROL_OPTIONS setting - MUST be 1450 rejected with a FLOW_CONTROL_ERROR error code. 1452 4. HTTP Message Exchanges 1454 HTTP/2.0 is intended to be as compatible as possible with current 1455 web-based applications. This means that, from the perspective of the 1456 server business logic or application API, the features of HTTP are 1457 unchanged. To achieve this, all of the application request and 1458 response header semantics are preserved, although the syntax of 1459 conveying those semantics has changed. Thus, the rules from HTTP/1.1 1460 ([HTTP-p1], [HTTP-p2], [HTTP-p4], [HTTP-p5], [HTTP-p6], and 1461 [HTTP-p7]) apply with the changes in the sections below. 1463 4.1. Connection Management 1465 Clients SHOULD NOT open more than one HTTP/2.0 connection to a given 1466 origin ([RFC6454]) concurrently. 1468 Note that it is possible for one HTTP/2.0 connection to be finishing 1469 (e.g. a GOAWAY frame has been sent, but not all streams have 1470 finished), while another HTTP/2.0 connection is starting. 1472 4.2. HTTP Request/Response 1474 4.2.1. HTTP Header Fields and HTTP/2.0 Headers 1476 At the application level, HTTP uses name-value pairs in its header 1477 fields. Because HTTP/2.0 merges the existing HTTP header fields with 1478 HTTP/2.0 headers, there is a possibility that some HTTP applications 1479 already use a particular header field name. To avoid any conflicts, 1480 all header fields introduced for layering HTTP over HTTP/2.0 are 1481 prefixed with ":". ":" is not a valid sequence in HTTP/1.* header 1482 field naming, preventing any possible conflict. 1484 4.2.2. Request 1486 The client initiates a request by sending a HEADERS+PRIORITY frame. 1487 Requests that do not contain a body MUST set the FINAL flag, 1488 indicating that the client intends to send no further data on this 1489 stream, unless the server intends to push resources (see 1490 Section 4.3). HEADERS+PRIORITY frame does not contain the FINAL flag 1491 for requests that contain a body. The body of a request follows as a 1492 series of DATA frames. The last DATA frame sets the FINAL flag to 1493 indicate the end of the body. 1495 The header fields included in the HEADERS+PRIORITY frame contain all 1496 of the HTTP header fields associated with an HTTP request. The 1497 definitions of these headers are largely unchanged relative to 1498 HTTP/1.1, with a few notable exceptions: 1500 o The HTTP/1.1 request-line has been split into two separate header 1501 fields named :method and :path, whose values specify the HTTP 1502 method for the request and the request-target, respectively. The 1503 HTTP-version component of the request-line is removed entirely 1504 from the headers. 1506 o The host and optional port portions of the request URI (see 1507 [RFC3986], Section 3.2), is specified using the new :host header 1508 field. [[anchor21: Ed. Note: it needs to be clarified whether or 1509 not this replaces the existing HTTP/1.1 Host header.]] 1511 o A new :scheme header field has been added to specify the scheme 1512 portion of the request-target (e.g. "https") 1514 o All header field names MUST be lowercased, and the definitions of 1515 all header field names defined by HTTP/1.1 are updated to be all 1516 lowercase. 1518 o The Connection, Host, Keep-Alive, Proxy-Connection, and Transfer- 1519 Encoding header fields are no longer valid and MUST not be sent. 1521 All HTTP Requests MUST include the ":method", ":path", ":host", and 1522 ":scheme" header fields. 1524 Header fields whose names begin with ":" (whether defined in this 1525 document or future extensions to this document) MUST appear before 1526 any other header fields. 1528 If a client sends a HEADERS+PRIORITY frame that omits a mandatory 1529 header, the server MUST reply with a HTTP 400 Bad Request reply. 1530 [[anchor22: Ed: why PROTOCOL_ERROR on missing ":status" in the 1531 response, but HTTP 400 here?]] 1533 If a server receives a request where the sum of the data frame 1534 payload lengths does not equal the size of the Content-Length header 1535 field, the server MUST return a 400 (Bad Request) error. 1537 Although POSTs are inherently chunked, POST requests SHOULD also be 1538 accompanied by a Content-Length header field. First, it informs the 1539 server of how much data to expect, which the server can use to track 1540 overall progress and provide appropriate user feedback. More 1541 importantly, some HTTP server implementations fail to correctly 1542 process requests that omit the Content-Length header field. Many 1543 existing clients send a Content-Length header field, and some server 1544 implementations have come to depend upon its presence. 1546 A client provides priority in requests as a hint to the server. A 1547 server SHOULD attempt to provide responses to higher priority 1548 requests before lower priority requests. A server could send lower 1549 priority responses during periods that higher priority responses are 1550 unavailable to ensure better utilization of a connection. 1552 If the server receives a data frame prior to a HEADERS+PRIORITY frame 1553 the server MUST treat this as a stream error (Section 3.5.2) of type 1554 PROTOCOL_ERROR. 1556 4.2.3. Response 1558 The server responds to a client request using the same stream 1559 identifier that was used by the request. An HTTP response begins 1560 with a HEADERS frame. An HTTP response body consists of a series of 1561 DATA frames. The last data frame contains a FINAL flag to indicate 1562 the end of the response. A response that contains no body (such as a 1563 204 or 304 response) consists only of a HEADERS frame that contains 1564 the FINAL flag to indicate no further data will be sent on the 1565 stream. 1567 The response status line is unfolded into name-value pairs like 1568 other HTTP header fields and must be present: 1570 ":status": The HTTP response status code (e.g. "200" or "200 OK") 1572 All header field names starting with ":" (whether defined in this 1573 document or future extensions to this document) MUST appear before 1574 any other header fields. 1576 All header field names MUST be all lowercase. 1578 The Connection, Keep-Alive, Proxy-Connection, and Transfer- 1579 Encoding header fields are not valid and MUST not be sent. 1581 Responses MAY be accompanied by a Content-Length header field for 1582 advisory purposes. This allows clients to learn the full size of 1583 an entity prior to receiving all the data frames. This can help 1584 in, for example, reporting progress. 1586 If a client receives a response where the sum of the data frame 1587 payload length does not equal the size of the Content-Length 1588 header field, the client MUST ignore the content length header 1589 field. [[anchor23: Ed: See 1590 .]] 1592 If a client receives a response with an absent or duplicated status 1593 header, the client MUST treat this as a stream error (Section 3.5.2) 1594 of type PROTOCOL_ERROR. 1596 If the client receives a data frame prior to a HEADERS frame the 1597 client MUST treat this as a stream error (Section 3.5.2) of type 1598 PROTOCOL_ERROR. 1600 Clients MUST support gzip compression. Regardless of the value of 1601 the Accept-Encoding header field, a server MAY send responses with 1602 gzip or deflate encoding. A compressed response MUST still bear an 1603 appropriate Content-Encoding header field. 1605 4.3. Server Push Transactions 1607 HTTP/2.0 enables a server to send multiple replies to a client for a 1608 single request. The rationale for this feature is that sometimes a 1609 server knows that it will need to send multiple resources in response 1610 to a single request. Without server push features, the client must 1611 first download the primary resource, then discover the secondary 1612 resource(s), and request them. 1614 Server push is an optional feature. The 1615 SETTINGS_MAX_CONCURRENT_STREAMS setting from the client limits the 1616 number of resources that can be concurrently pushed by a server. 1617 Server push can be disabled by clients that do not wish to receive 1618 pushed resources by advertising a SETTINGS_MAX_CONCURRENT_STREAMS 1619 SETTING (Section 3.8.4) of zero. This prevents servers from creating 1620 the streams necessary to push resources. 1622 Clients receiving a pushed response MUST validate that the server is 1623 authorized to push the resource using the same-origin policy 1624 ([RFC6454], Section 3). For example, a HTTP/2.0 connection to 1625 "example.com" is generally [[anchor24: Ed: weaselly use of 1626 "generally", needs better definition]] not permitted to push a 1627 response for "www.example.org". 1629 A client that accepts pushed resources caches those resources as 1630 though they were responses to GET requests. 1632 Pushing of resources avoids the round-trip delay, but also creates a 1633 potential race where a server can be pushing content which a client 1634 is in the process of requesting. The PUSH_PROMISE frame reduces the 1635 chances of this condition occurring, while retaining the performance 1636 benefit. 1638 Pushed responses are associated with a request at the HTTP/2.0 1639 framing layer. The PUSH_PROMISE is sent on the stream for the 1640 associated request, which allows a receiver to correlate the pushed 1641 resource with a request. The pushed stream inherits all of the 1642 request header fields from the associated stream with the exception 1643 of resource identification header fields (":host", ":scheme", and 1644 ":path"), which are provided as part of the PUSH_PROMISE frame. 1646 Pushed resources always have an associated ":method" of "GET". A 1647 cache MUST store these inherited and implied request header fields 1648 with the cached resource. 1650 4.3.1. Server implementation 1652 A server pushes resources in association with a request from the 1653 client. Prior to closing the response stream, the server sends a 1654 PUSH_PROMISE for each resource that it intends to push. The 1655 PUSH_PROMISE includes header fields that allow the client to identify 1656 the resource (":scheme", ":host", and ":path"). 1658 A server can push multiple resources in response to a request, but 1659 all pushed resources MUST be promised on the response stream for the 1660 associated request. A server cannot send a PUSH_PROMISE on a new 1661 stream or a half-closed stream. 1663 The server SHOULD include any header fields in a PUSH_PROMISE that 1664 would allow a cache to determine if the resource is already cached 1665 (see [HTTP-p6], Section 4). 1667 After sending a PUSH_PROMISE, the server commences transmission of a 1668 pushed resource. A pushed resource uses a server-initiated stream. 1669 The server sends frames on this stream in the same order as an HTTP 1670 response (Section 4.2.3): a HEADERS frame followed by DATA frames. 1672 Many uses of server push are to send content that a client is likely 1673 to discover a need for based on the content of a response 1674 representation. To minimize the chances that a client will make a 1675 request for resources that are being pushed - causing duplicate 1676 copies of a resource to be sent by the server - a PUSH_PROMISE frame 1677 SHOULD be sent prior to any content in the response representation 1678 that might allow a client to discover the pushed resource and request 1679 it. 1681 The server MUST only push resources that could have been returned 1682 from a GET request. 1684 Note: A server does not need to have all response header fields 1685 available at the time it issues a PUSH_PROMISE frame. All remaining 1686 header fields are included in the HEADERS frame. The HEADERS frame 1687 MUST NOT duplicate header fields from the PUSH_PROMISE frames. 1689 4.3.2. Client implementation 1691 When fetching a resource the client has 3 possibilities: 1693 1. the resource is not being pushed 1695 2. the resource is being pushed, but the data has not yet arrived 1697 3. the resource is being pushed, and the data has started to arrive 1699 A client SHOULD NOT issue GET requests for a resource that has been 1700 promised. A client is instead advised to wait for the pushed 1701 resource to arrive. 1703 When a client receives a PUSH_PROMISE frame from the server without a 1704 the ":host", ":scheme", and ":path" header fields, it MUST treat this 1705 as a stream error (Section 3.5.2) of type PROTOCOL_ERROR. 1707 To cancel individual server push streams, the client can issue a 1708 stream error (Section 3.5.2) of type CANCEL. After receiving a 1709 PUSH_PROMISE frame, the client is able to cancel the pushed resource 1710 before receiving any frames on the promised stream. The server 1711 ceases transmission of the pushed resource; if the server has not 1712 commenced transmission, it does not start. 1714 To cancel all server push streams related to a request, the client 1715 may issue a stream error (Section 3.5.2) of type CANCEL on the 1716 associated-stream-id. By cancelling that stream, the server MUST 1717 immediately stop sending frames for any streams with 1718 in-association-to for the original stream. [[anchor27: Ed: Triggering 1719 side-effects on stream reset is going to be problematic for the 1720 framing layer. Purely from a design perspective, it's a layering 1721 violation. More practically speaking, the base request stream might 1722 already be removed. Special handling logic would be required.]] 1724 A client can choose to time out pushed streams if the server does not 1725 provide the resource in a timely fashion. A stream error 1726 (Section 3.5.2) of type CANCEL can be used to stop a timed out push. 1728 If the server sends a HEADERS frame containing header fields that 1729 duplicate values on a previous HEADERS or PUSH_PROMISE frames on the 1730 same stream, the client MUST treat this as a stream error 1731 (Section 3.5.2) of type PROTOCOL_ERROR. 1733 If the server sends a HEADERS frame after sending a data frame for 1734 the same stream, the client MAY ignore the HEADERS frame. Ignoring 1735 the HEADERS frame after a data frame prevents handling of HTTP's 1736 trailing header fields (Section 4.1.1 of [HTTP-p1]). 1738 5. Design Rationale and Notes 1740 Authors' notes: The notes in this section have no bearing on the 1741 HTTP/2.0 protocol as specified within this document, and none of 1742 these notes should be considered authoritative about how the protocol 1743 works. However, these notes may prove useful in future debates about 1744 how to resolve protocol ambiguities or how to evolve the protocol 1745 going forward. They may be removed before the final draft. 1747 5.1. Separation of Framing Layer and Application Layer 1749 Readers may note that this specification sometimes blends the framing 1750 layer (Section 3) with requirements of a specific application - HTTP 1751 (Section 4). This is reflected in the request/response nature of the 1752 streams and the definition of the HEADERS which are very similar to 1753 HTTP, and other areas as well. 1755 This blending is intentional - the primary goal of this protocol is 1756 to create a low-latency protocol for use with HTTP. Isolating the 1757 two layers is convenient for description of the protocol and how it 1758 relates to existing HTTP implementations. However, the ability to 1759 reuse the HTTP/2.0 framing layer is a non goal. 1761 5.2. Error handling - Framing Layer 1763 Error handling at the HTTP/2.0 layer splits errors into two groups: 1764 Those that affect an individual HTTP/2.0 stream, and those that do 1765 not. 1767 When an error is confined to a single stream, but general framing is 1768 intact, HTTP/2.0 attempts to use the RST_STREAM as a mechanism to 1769 invalidate the stream but move forward without aborting the 1770 connection altogether. 1772 For errors occurring outside of a single stream context, HTTP/2.0 1773 assumes the entire connection is hosed. In this case, the endpoint 1774 detecting the error should initiate a connection close. 1776 5.3. One Connection per Domain 1778 HTTP/2.0 attempts to use fewer connections than other protocols have 1779 traditionally used. The rationale for this behavior is because it is 1780 very difficult to provide a consistent level of service (e.g. TCP 1781 slow-start), prioritization, or optimal compression when the client 1782 is connecting to the server through multiple channels. 1784 Through lab measurements, we have seen consistent latency benefits by 1785 using fewer connections from the client. The overall number of 1786 packets sent by HTTP/2.0 can be as much as 40% less than HTTP. 1787 Handling large numbers of concurrent connections on the server also 1788 does become a scalability problem, and HTTP/2.0 reduces this load. 1790 The use of multiple connections is not without benefit, however. 1791 Because HTTP/2.0 multiplexes multiple, independent streams onto a 1792 single stream, it creates a potential for head-of-line blocking 1793 problems at the transport level. In tests so far, the negative 1794 effects of head-of-line blocking (especially in the presence of 1795 packet loss) is outweighed by the benefits of compression and 1796 prioritization. 1798 5.4. Fixed vs Variable Length Fields 1800 HTTP/2.0 favors use of fixed length 32bit fields in cases where 1801 smaller, variable length encodings could have been used. To some, 1802 this seems like a tragic waste of bandwidth. HTTP/2.0 chooses the 1803 simple encoding for speed and simplicity. 1805 The goal of HTTP/2.0 is to reduce latency on the network. The 1806 overhead of HTTP/2.0 frames is generally quite low. Each data frame 1807 is only an 8 byte overhead for a 1452 byte payload (~0.6%). At the 1808 time of this writing, bandwidth is already plentiful, and there is a 1809 strong trend indicating that bandwidth will continue to increase. 1810 With an average worldwide bandwidth of 1Mbps, and assuming that a 1811 variable length encoding could reduce the overhead by 50%, the 1812 latency saved by using a variable length encoding would be less than 1813 100 nanoseconds. More interesting are the effects when the larger 1814 encodings force a packet boundary, in which case a round-trip could 1815 be induced. However, by addressing other aspects of HTTP/2.0 and TCP 1816 interactions, we believe this is completely mitigated. 1818 5.5. Server Push 1820 A subtle but important point is that server push streams must be 1821 declared before the associated stream is closed. The reason for this 1822 is so that proxies have a lifetime for which they can discard 1823 information about previous streams. If a pushed stream could 1824 associate itself with an already-closed stream, then endpoints would 1825 not have a specific lifecycle for when they could disavow knowledge 1826 of the streams which went before. 1828 6. Security Considerations 1830 6.1. Server Authority and Same-Origin 1832 This specification uses the same-origin policy ([RFC6454], Section 3) 1833 to determine whether an origin server is permitted to provide 1834 content. 1836 A server that is contacted using TLS is authenticated based on the 1837 certificate that it offers in the TLS handshake (see [RFC2818], 1838 Section 3). A server is considered authoritative for an "https:" 1839 resource if it has been successfully authenticated for the domain 1840 part of the origin of the resource that it is providing. 1842 A server is considered authoritative for an "http:" resource if the 1843 connection is established to a resolved IP address for the domain in 1844 the origin of the resource. 1846 A client MUST NOT use, in any way, resources provided by a server 1847 that is not authoritative for those resources. 1849 6.2. Cross-Protocol Attacks 1851 When using TLS, we believe that HTTP/2.0 introduces no new cross- 1852 protocol attacks. TLS encrypts the contents of all transmission 1853 (except the handshake itself), making it difficult for attackers to 1854 control the data which could be used in a cross-protocol attack. 1856 [[anchor37: Issue: This is no longer true]] 1858 6.3. Cacheability of Pushed Resources 1860 Pushed resources are synthesized responses without an explicit 1861 request; the request for a pushed resource is synthesized from the 1862 request that triggered the push, plus resource identification 1863 information provided by the server. Request header fields are 1864 necessary for HTTP cache control validations (such as the Vary header 1865 field) to work. For this reason, caches MUST inherit request header 1866 fields from the associated stream for the push. This includes the 1867 Cookie header field. 1869 Caching resources that are pushed is possible, based on the guidance 1870 provided by the origin server in the Cache-Control header field. 1871 However, this can cause issues if a single server hosts more than one 1872 tenant. For example, a server might offer multiple users each a 1873 small portion of its URI space. 1875 Where multiple tenants share space on the same server, that server 1876 MUST ensure that tenants are not able to push representations of 1877 resources that they do not have authority over. Failure to enforce 1878 this would allow a tenant to provide a representation that would be 1879 served out of cache, overriding the actual representation that the 1880 authoritative tenant provides. 1882 Pushed resources for which an origin server is not authoritative are 1883 never cached or used. 1885 7. Privacy Considerations 1887 7.1. Long Lived Connections 1889 HTTP/2.0 aims to keep connections open longer between clients and 1890 servers in order to reduce the latency when a user makes a request. 1891 The maintenance of these connections over time could be used to 1892 expose private information. For example, a user using a browser 1893 hours after the previous user stopped using that browser may be able 1894 to learn about what the previous user was doing. This is a problem 1895 with HTTP in its current form as well, however the short lived 1896 connections make it less of a risk. 1898 7.2. SETTINGS frame 1900 The HTTP/2.0 SETTINGS frame allows servers to store out-of-band 1901 transmitted information about the communication between client and 1902 server on the client. Although this is intended only to be used to 1903 reduce latency, renegade servers could use it as a mechanism to store 1904 identifying information about the client in future requests. 1906 Clients implementing privacy modes can disable client-persisted 1907 SETTINGS storage. 1909 Clients MUST clear persisted SETTINGS information when clearing the 1910 cookies. 1912 8. IANA Considerations 1914 This document establishes registries for frame types, error codes and 1915 settings. 1917 8.1. Frame Type Registry 1919 This document establishes a registry for HTTP/2.0 frame types. The 1920 "HTTP/2.0 Frame Type" registry operates under the "IETF Review" 1921 policy [RFC5226]. 1923 Frame types are an 8-bit value. When reviewing new frame type 1924 registrations, special attention is advised for any frame type- 1925 specific flags that are defined. Frame flags can interact with 1926 existing flags and could prevent the creation of globally applicable 1927 flags. 1929 Initial values for the "HTTP/2.0 Frame Type" registry are shown in 1930 Table 1. 1932 +------------+------------------+---------------------+ 1933 | Frame Type | Name | Flags | 1934 +------------+------------------+---------------------+ 1935 | 0 | DATA | - | 1936 | 1 | HEADERS+PRIORITY | - | 1937 | 3 | RST_STREAM | - | 1938 | 4 | SETTINGS | CLEAR_PERSISTED(2) | 1939 | 5 | PUSH_PROMISE | - | 1940 | 6 | PING | PONG(2) | 1941 | 7 | GOAWAY | - | 1942 | 8 | HEADERS | - | 1943 | 9 | WINDOW_UPDATE | END_FLOW_CONTROL(2) | 1944 +------------+------------------+---------------------+ 1946 Table 1 1948 8.2. Error Code Registry 1950 This document establishes a registry for HTTP/2.0 error codes. The 1951 "HTTP/2.0 Error Code" registry manages a 32-bit space. The "HTTP/2.0 1952 Error Code" registry operates under the "Expert Review" policy 1953 [RFC5226]. 1955 Registrations for error codes are required to include a description 1956 of the error code. An expert reviewer is advised to examine new 1957 registrations for possible duplication with existing error codes. 1958 Use of existing registrations is to be encouraged, but not mandated. 1960 New registrations are advised to provide the following information: 1962 Error Code: The 32-bit error code value. 1964 Name: A name for the error code. Specifying an error code name is 1965 optional. 1967 Description: A description of the conditions where the error code is 1968 applicable. 1970 Specification: An optional reference for a specification that 1971 defines the error code. 1973 An initial set of error code registrations can be found in 1974 Section 3.5.3. 1976 8.3. Settings Registry 1978 This document establishes a registry for HTTP/2.0 settings. The 1979 "HTTP/2.0 Settings" registry manages a 24-bit space. The "HTTP/2.0 1980 Settings" registry operates under the "Expert Review" policy 1981 [RFC5226]. 1983 Registrations for settings are required to include a description of 1984 the setting. An expert reviewer is advised to examine new 1985 registrations for possible duplication with existing settings. Use 1986 of existing registrations is to be encouraged, but not mandated. 1988 New registrations are advised to provide the following information: 1990 Setting: The 24-bit setting value. 1992 Name: A name for the setting. Specifying a name is optional. 1994 Flags: Any setting-specific flags that apply, including their value 1995 and semantics. 1997 Description: A description of the setting. This might include the 1998 range of values, any applicable units and how to act upon a value 1999 when it is provided. 2001 Specification: An optional reference for a specification that 2002 defines the setting. 2004 An initial set of settings registrations can be found in 2005 Section 3.8.4.3. 2007 9. Acknowledgements 2009 This document includes substantial input from the following 2010 individuals: 2012 o Adam Langley, Wan-Teh Chang, Jim Morrison, Mark Nottingham, Alyssa 2013 Wilk, Costin Manolache, William Chan, Vitaliy Lvin, Joe Chan, Adam 2014 Barth, Ryan Hamilton, Gavin Peters, Kent Alstad, Kevin Lindsay, 2015 Paul Amer, Fan Yang, Jonathan Leighton (SPDY contributors). 2017 o Gabriel Montenegro and Willy Tarreau (Upgrade mechanism) 2019 o William Chan, Salvatore Loreto, Osama Mazahir, Gabriel Montenegro, 2020 Jitu Padhye, Roberto Peon, Rob Trace (Flow control) 2022 o Mark Nottingham, Julian Reschke, James Snell (Editorial) 2024 10. References 2026 10.1. Normative References 2028 [HTTP-p1] Fielding, R. and J. Reschke, "Hypertext Transfer Protocol 2029 (HTTP/1.1): Message Syntax and Routing", 2030 draft-ietf-httpbis-p1-messaging-22 (work in progress), 2031 February 2013. 2033 [HTTP-p2] Fielding, R. and J. Reschke, "Hypertext Transfer Protocol 2034 (HTTP/1.1): Semantics and Content", 2035 draft-ietf-httpbis-p2-semantics-22 (work in progress), 2036 February 2013. 2038 [HTTP-p4] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer 2039 Protocol (HTTP/1.1): Conditional Requests", 2040 draft-ietf-httpbis-p4-conditional-22 (work in progress), 2041 February 2013. 2043 [HTTP-p5] Fielding, R., Ed., Lafon, Y., Ed., and J. Reschke, Ed., 2044 "Hypertext Transfer Protocol (HTTP/1.1): Range Requests", 2045 draft-ietf-httpbis-p5-range-22 (work in progress), 2046 February 2013. 2048 [HTTP-p6] Fielding, R., Ed., Nottingham, M., Ed., and J. Reschke, 2049 Ed., "Hypertext Transfer Protocol (HTTP/1.1): Caching", 2050 draft-ietf-httpbis-p6-cache-22 (work in progress), 2051 February 2013. 2053 [HTTP-p7] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer 2054 Protocol (HTTP/1.1): Authentication", 2055 draft-ietf-httpbis-p7-auth-22 (work in progress), 2056 February 2013. 2058 [RFC0793] Postel, J., "Transmission Control Protocol", STD 7, 2059 RFC 793, September 1981. 2061 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 2062 Requirement Levels", BCP 14, RFC 2119, March 1997. 2064 [RFC2818] Rescorla, E., "HTTP Over TLS", RFC 2818, May 2000. 2066 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 2067 Resource Identifier (URI): Generic Syntax", STD 66, 2068 RFC 3986, January 2005. 2070 [RFC5226] Narten, T. and H. Alvestrand, "Guidelines for Writing an 2071 IANA Considerations Section in RFCs", BCP 26, RFC 5226, 2072 May 2008. 2074 [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security 2075 (TLS) Protocol Version 1.2", RFC 5246, August 2008. 2077 [RFC6454] Barth, A., "The Web Origin Concept", RFC 6454, 2078 December 2011. 2080 [TLSALPN] Friedl, S., Popov, A., Langley, A., and E. Stephan, 2081 "Transport Layer Security (TLS) Application Layer Protocol 2082 Negotiation Extension", draft-ietf-tls-applayerprotoneg-01 2083 (work in progress), April 2013. 2085 10.2. Informative References 2087 [RFC1323] Jacobson, V., Braden, B., and D. Borman, "TCP Extensions 2088 for High Performance", RFC 1323, May 1992. 2090 [TALKING] Huang, L-S., Chen, E., Barth, A., Rescorla, E., and C. 2092 Jackson, "Talking to Yourself for Fun and Profit", 2011, 2093 . 2095 Appendix A. Change Log (to be removed by RFC Editor before publication) 2097 A.1. Since draft-ietf-httpbis-http2-02 2099 Added continuations to frames carrying header blocks. 2101 Replaced use of "session" with "connection" to avoid confusion with 2102 other HTTP stateful concepts, like cookies. 2104 Removed "message". 2106 Switched to TLS ALPN from NPN. 2108 Editorial changes. 2110 A.2. Since draft-ietf-httpbis-http2-01 2112 Added IANA considerations section for frame types, error codes and 2113 settings. 2115 Removed data frame compression. 2117 Added PUSH_PROMISE. 2119 Added globally applicable flags to framing. 2121 Removed zlib-based header compression mechanism. 2123 Updated references. 2125 Clarified stream identifier reuse. 2127 Removed CREDENTIALS frame and associated mechanisms. 2129 Added advice against naive implementation of flow control. 2131 Added session header section. 2133 Restructured frame header. Removed distinction between data and 2134 control frames. 2136 Altered flow control properties to include session-level limits. 2138 Added note on cacheability of pushed resources and multiple tenant 2139 servers. 2141 Changed protocol label form based on discussions. 2143 A.3. Since draft-ietf-httpbis-http2-00 2145 Changed title throughout. 2147 Removed section on Incompatibilities with SPDY draft#2. 2149 Changed INTERNAL_ERROR on GOAWAY to have a value of 2 . 2152 Replaced abstract and introduction. 2154 Added section on starting HTTP/2.0, including upgrade mechanism. 2156 Removed unused references. 2158 Added flow control principles (Section 3.6.1) based on . 2161 A.4. Since draft-mbelshe-httpbis-spdy-00 2163 Adopted as base for draft-ietf-httpbis-http2. 2165 Updated authors/editors list. 2167 Added status note. 2169 Authors' Addresses 2171 Mike Belshe 2172 Twist 2174 EMail: mbelshe@chromium.org 2176 Roberto Peon 2177 Google, Inc 2179 EMail: fenix@google.com 2180 Martin Thomson (editor) 2181 Microsoft 2182 3210 Porter Drive 2183 Palo Alto 94304 2184 US 2186 EMail: martin.thomson@skype.net 2188 Alexey Melnikov (editor) 2189 Isode Ltd 2190 5 Castle Business Village 2191 36 Station Road 2192 Hampton, Middlesex TW12 2BX 2193 UK 2195 EMail: Alexey.Melnikov@isode.com