idnits 2.17.1 draft-ietf-httpbis-http2-06.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- No issues found here. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (August 21, 2013) is 3900 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 (-12) exists of draft-ietf-httpbis-header-compression-02 == Outdated reference: A later version (-26) exists of draft-ietf-httpbis-p1-messaging-23 == Outdated reference: A later version (-26) exists of draft-ietf-httpbis-p2-semantics-23 == Outdated reference: A later version (-26) exists of draft-ietf-httpbis-p4-conditional-23 == Outdated reference: A later version (-26) exists of draft-ietf-httpbis-p5-range-23 == Outdated reference: A later version (-26) exists of draft-ietf-httpbis-p6-cache-23 == Outdated reference: A later version (-26) exists of draft-ietf-httpbis-p7-auth-23 ** 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 4346 (ref. 'TLS11') (Obsoleted by RFC 5246) ** Obsolete normative reference: RFC 5246 (ref. 'TLS12') (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: 5 errors (**), 0 flaws (~~), 9 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: February 22, 2014 Google, Inc 6 M. Thomson, Ed. 7 Microsoft 8 A. Melnikov, Ed. 9 Isode Ltd 10 August 21, 2013 12 Hypertext Transfer Protocol version 2.0 13 draft-ietf-httpbis-http2-06 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 This version of the draft has been marked for implementation. 30 Interoperability testing will occur in the HTTP/2.0 interim in 31 Seatle, US, starting 2013-10-09. 33 Editorial Note (To be removed by RFC Editor) 35 Discussion of this draft takes place on the HTTPBIS working group 36 mailing list (ietf-http-wg@w3.org), which is archived at 37 . 39 Working Group information and related documents can be found at 40 (Wiki) and 41 (source code and issues 42 tracker). 44 The changes in this draft are summarized in Appendix A.1. 46 Status of This Memo 48 This Internet-Draft is submitted in full conformance with the 49 provisions of BCP 78 and BCP 79. 51 Internet-Drafts are working documents of the Internet Engineering 52 Task Force (IETF). Note that other groups may also distribute 53 working documents as Internet-Drafts. The list of current Internet- 54 Drafts is at http://datatracker.ietf.org/drafts/current/. 56 Internet-Drafts are draft documents valid for a maximum of six months 57 and may be updated, replaced, or obsoleted by other documents at any 58 time. It is inappropriate to use Internet-Drafts as reference 59 material or to cite them other than as "work in progress." 61 This Internet-Draft will expire on February 22, 2014. 63 Copyright Notice 65 Copyright (c) 2013 IETF Trust and the persons identified as the 66 document authors. All rights reserved. 68 This document is subject to BCP 78 and the IETF Trust's Legal 69 Provisions Relating to IETF Documents 70 (http://trustee.ietf.org/license-info) in effect on the date of 71 publication of this document. Please review these documents 72 carefully, as they describe your rights and restrictions with respect 73 to this document. Code Components extracted from this document must 74 include Simplified BSD License text as described in Section 4.e of 75 the Trust Legal Provisions and are provided without warranty as 76 described in the Simplified BSD License. 78 Table of Contents 80 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 5 81 1.1. Document Organization . . . . . . . . . . . . . . . . . . 5 82 1.2. Conventions and Terminology . . . . . . . . . . . . . . . 6 83 2. HTTP/2.0 Protocol Overview . . . . . . . . . . . . . . . . . . 6 84 2.1. HTTP Frames . . . . . . . . . . . . . . . . . . . . . . . 7 85 2.2. HTTP Multiplexing . . . . . . . . . . . . . . . . . . . . 7 86 2.3. HTTP Semantics . . . . . . . . . . . . . . . . . . . . . . 7 87 3. Starting HTTP/2.0 . . . . . . . . . . . . . . . . . . . . . . 7 88 3.1. HTTP/2.0 Version Identification . . . . . . . . . . . . . 8 89 3.2. Starting HTTP/2.0 for "http" URIs . . . . . . . . . . . . 8 90 3.2.1. HTTP2-Settings Header Field . . . . . . . . . . . . . 10 91 3.3. Starting HTTP/2.0 for "https" URIs . . . . . . . . . . . . 10 92 3.4. Starting HTTP/2.0 with Prior Knowledge . . . . . . . . . . 10 93 3.5. Connection Header . . . . . . . . . . . . . . . . . . . . 11 94 4. HTTP Frames . . . . . . . . . . . . . . . . . . . . . . . . . 12 95 4.1. Frame Format . . . . . . . . . . . . . . . . . . . . . . . 12 96 4.2. Frame Size . . . . . . . . . . . . . . . . . . . . . . . . 13 97 4.3. Header Compression and Decompression . . . . . . . . . . . 13 98 5. Streams and Multiplexing . . . . . . . . . . . . . . . . . . . 14 99 5.1. Stream States . . . . . . . . . . . . . . . . . . . . . . 14 100 5.1.1. Stream Identifiers . . . . . . . . . . . . . . . . . . 18 101 5.1.2. Stream Concurrency . . . . . . . . . . . . . . . . . . 19 102 5.2. Flow Control . . . . . . . . . . . . . . . . . . . . . . . 19 103 5.2.1. Flow Control Principles . . . . . . . . . . . . . . . 20 104 5.2.2. Appropriate Use of Flow Control . . . . . . . . . . . 21 105 5.3. Stream priority . . . . . . . . . . . . . . . . . . . . . 21 106 5.4. Error Handling . . . . . . . . . . . . . . . . . . . . . . 22 107 5.4.1. Connection Error Handling . . . . . . . . . . . . . . 22 108 5.4.2. Stream Error Handling . . . . . . . . . . . . . . . . 22 109 5.4.3. Connection Termination . . . . . . . . . . . . . . . . 23 110 6. Frame Definitions . . . . . . . . . . . . . . . . . . . . . . 23 111 6.1. DATA . . . . . . . . . . . . . . . . . . . . . . . . . . . 23 112 6.2. HEADERS . . . . . . . . . . . . . . . . . . . . . . . . . 24 113 6.3. PRIORITY . . . . . . . . . . . . . . . . . . . . . . . . . 25 114 6.4. RST_STREAM . . . . . . . . . . . . . . . . . . . . . . . . 26 115 6.5. SETTINGS . . . . . . . . . . . . . . . . . . . . . . . . . 27 116 6.5.1. Setting Format . . . . . . . . . . . . . . . . . . . . 27 117 6.5.2. Defined Settings . . . . . . . . . . . . . . . . . . . 28 118 6.6. PUSH_PROMISE . . . . . . . . . . . . . . . . . . . . . . . 28 119 6.7. PING . . . . . . . . . . . . . . . . . . . . . . . . . . . 30 120 6.8. GOAWAY . . . . . . . . . . . . . . . . . . . . . . . . . . 31 121 6.9. WINDOW_UPDATE . . . . . . . . . . . . . . . . . . . . . . 33 122 6.9.1. The Flow Control Window . . . . . . . . . . . . . . . 34 123 6.9.2. Initial Flow Control Window Size . . . . . . . . . . . 35 124 6.9.3. Reducing the Stream Window Size . . . . . . . . . . . 36 125 6.9.4. Ending Flow Control . . . . . . . . . . . . . . . . . 36 126 6.10. CONTINUATION . . . . . . . . . . . . . . . . . . . . . . . 37 127 7. Error Codes . . . . . . . . . . . . . . . . . . . . . . . . . 38 128 8. HTTP Message Exchanges . . . . . . . . . . . . . . . . . . . . 39 129 8.1. HTTP Request/Response Exchange . . . . . . . . . . . . . . 39 130 8.1.1. Examples . . . . . . . . . . . . . . . . . . . . . . . 40 131 8.1.2. HTTP Header Fields . . . . . . . . . . . . . . . . . . 42 132 8.1.3. Request Reliability Mechanisms in HTTP/2.0 . . . . . . 43 133 8.2. Server Push . . . . . . . . . . . . . . . . . . . . . . . 44 134 8.2.1. Push Requests . . . . . . . . . . . . . . . . . . . . 44 135 8.2.2. Push Responses . . . . . . . . . . . . . . . . . . . . 45 136 9. Additional HTTP Requirements/Considerations . . . . . . . . . 46 137 9.1. Connection Management . . . . . . . . . . . . . . . . . . 46 138 9.2. Use of TLS Features . . . . . . . . . . . . . . . . . . . 47 139 9.3. Frame Size Limits for HTTP . . . . . . . . . . . . . . . . 47 140 9.4. GZip Content-Encoding . . . . . . . . . . . . . . . . . . 47 141 10. Security Considerations . . . . . . . . . . . . . . . . . . . 48 142 10.1. Server Authority and Same-Origin . . . . . . . . . . . . . 48 143 10.2. Cross-Protocol Attacks . . . . . . . . . . . . . . . . . . 48 144 10.3. Cacheability of Pushed Resources . . . . . . . . . . . . . 48 146 11. Privacy Considerations . . . . . . . . . . . . . . . . . . . . 49 147 12. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 49 148 12.1. Frame Type Registry . . . . . . . . . . . . . . . . . . . 49 149 12.2. Error Code Registry . . . . . . . . . . . . . . . . . . . 50 150 12.3. Settings Registry . . . . . . . . . . . . . . . . . . . . 51 151 12.4. HTTP2-Settings Header Field Registration . . . . . . . . . 51 152 13. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . 52 153 14. References . . . . . . . . . . . . . . . . . . . . . . . . . . 52 154 14.1. Normative References . . . . . . . . . . . . . . . . . . . 52 155 14.2. Informative References . . . . . . . . . . . . . . . . . . 54 156 Appendix A. Change Log (to be removed by RFC Editor before 157 publication) . . . . . . . . . . . . . . . . . . . . 54 158 A.1. Since draft-ietf-httpbis-http2-05 . . . . . . . . . . . . 54 159 A.2. Since draft-ietf-httpbis-http2-04 . . . . . . . . . . . . 54 160 A.3. Since draft-ietf-httpbis-http2-03 . . . . . . . . . . . . 55 161 A.4. Since draft-ietf-httpbis-http2-02 . . . . . . . . . . . . 55 162 A.5. Since draft-ietf-httpbis-http2-01 . . . . . . . . . . . . 55 163 A.6. Since draft-ietf-httpbis-http2-00 . . . . . . . . . . . . 56 164 A.7. Since draft-mbelshe-httpbis-spdy-00 . . . . . . . . . . . 56 166 1. Introduction 168 The Hypertext Transfer Protocol (HTTP) is a wildly successful 169 protocol. However, the HTTP/1.1 message format ([HTTP-p1], Section 170 3) is optimized for implementation simplicity and accessibility, not 171 application performance. As such it has several characteristics that 172 have a negative overall effect on application performance. 174 In particular, HTTP/1.0 only allows one request to be delivered at a 175 time on a given connection. HTTP/1.1 pipelining only partially 176 addressed request concurrency, and is not widely deployed. 177 Therefore, clients that need to make many requests (as is common on 178 the Web) typically use multiple connections to a server in order to 179 reduce perceived latency. 181 Furthermore, HTTP/1.1 header fields are often repetitive and verbose, 182 which, in addition to generating more or larger network packets, can 183 cause the small initial TCP congestion window to quickly fill. This 184 can result in excessive latency when multiple requests are made on a 185 single new TCP connection. 187 This document addresses these issues by defining an optimized mapping 188 of HTTP's semantics to an underlying connection. Specifically, it 189 allows interleaving of request and response messages on the same 190 connection and uses an efficient coding for HTTP header fields. It 191 also allows prioritization of requests, letting more important 192 requests complete more quickly, further improving perceived 193 performance. 195 The resulting protocol is designed to be more friendly to the 196 network, because fewer TCP connections can be used, in comparison to 197 HTTP/1.x. This means less competition with other flows, and longer- 198 lived connections, which in turn leads to better utilization of 199 available network capacity. 201 Finally, this encapsulation also enables more scalable processing of 202 messages through use of binary message framing. 204 1.1. Document Organization 206 The HTTP/2.0 Specification is split into three parts: starting 207 HTTP/2.0 (Section 3), which covers how a HTTP/2.0 connection is 208 initiated; a framing layer (Section 4), which multiplexes a single 209 TCP connection into independent frames of various types; and an HTTP 210 layer (Section 8), which specifies the mechanism for expressing HTTP 211 interactions using the framing layer. While some of the framing 212 layer concepts are isolated from HTTP, building a generic framing 213 layer has not been a goal. The framing layer is tailored to the 214 needs of the HTTP protocol and server push. 216 1.2. Conventions and Terminology 218 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 219 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 220 document are to be interpreted as described in RFC 2119 [RFC2119]. 222 All numeric values are in network byte order. Values are unsigned 223 unless otherwise indicated. Literal values are provided in decimal 224 or hexadecimal as appropriate. Hexadecimal literals are prefixed 225 with "0x" to distinguish them from decimal literals. 227 The following terms are used: 229 client: The endpoint initiating the HTTP connection. 231 connection: A transport-level connection between two endpoints. 233 endpoint: Either the client or server of the connection. 235 frame: The smallest unit of communication within an HTTP/2.0 236 connection, consisting of a header and a variable-length sequence 237 of bytes structured according to the frame type. 239 peer: An endpoint. When discussing a particular endpoint, "peer" 240 refers to the endpoint that is remote to the primary subject of 241 discussion. 243 receiver: An endpoint that is receiving frames. 245 sender: An endpoint that is transmitting frames. 247 server: The endpoint which did not initiate the HTTP connection. 249 connection error: An error on the HTTP/2.0 connection. 251 stream: A bi-directional flow of frames across a virtual channel 252 within the HTTP/2.0 connection. 254 stream error: An error on the individual HTTP/2.0 stream. 256 2. HTTP/2.0 Protocol Overview 258 HTTP/2.0 provides an optimized transport for HTTP semantics. 260 An HTTP/2.0 connection is an application level protocol running on 261 top of a TCP connection ([RFC0793]). The client is the TCP 262 connection initiator. 264 This document describes the HTTP/2.0 protocol using a logical 265 structure that is formed of three parts: framing, streams, and 266 application mapping. This structure is provided primarily as an aid 267 to specification, implementations are free to diverge from this 268 structure as necessary. 270 2.1. HTTP Frames 272 HTTP/2.0 provides an efficient serialization of HTTP semantics. HTTP 273 requests and responses are encoded into length-prefixed frames (see 274 Section 4.1). 276 HTTP headers are compressed into a series of frames that contain 277 header block fragments (see Section 4.3). 279 2.2. HTTP Multiplexing 281 HTTP/2.0 provides the ability to multiplex multiple HTTP requests and 282 responses onto a single connection. Multiple requests or responses 283 can be sent concurrently on a connection using streams (Section 5). 284 In order to maintain independent streams, flow control and 285 prioritization are necessary. 287 2.3. HTTP Semantics 289 HTTP/2.0 defines how HTTP requests and responses are mapped to 290 streams (see Section 8.1) and introduces a new interaction model, 291 server push (Section 8.2). 293 3. Starting HTTP/2.0 295 HTTP/2.0 uses the same "http" and "https" URI schemes used by 296 HTTP/1.1. HTTP/2.0 shares the same default port numbers: 80 for 297 "http" URIs and 443 for "https" URIs. As a result, implementations 298 processing requests for target resource URIs like 299 "http://example.org/foo" or "https://example.com/bar" are required to 300 first discover whether the upstream server (the immediate peer to 301 which the client wishes to establish a connection) supports HTTP/2.0. 303 The means by which support for HTTP/2.0 is determined is different 304 for "http" and "https" URIs. Discovery for "http" URIs is described 305 in Section 3.2. Discovery for "https" URIs is described in 306 Section 3.3. 308 3.1. HTTP/2.0 Version Identification 310 The protocol defined in this document is identified using the string 311 "HTTP/2.0". This identification is used in the HTTP/1.1 Upgrade 312 header field, in the TLS application layer protocol negotiation 313 extension [TLSALPN] field, and other places where protocol 314 identification is required. 316 Negotiating "HTTP/2.0" implies the use of the transport, security, 317 framing and message semantics described in this document. 319 [[anchor6: Editor's Note: please remove the remainder of this section 320 prior to the publication of a final version of this document.]] 322 Only implementations of the final, published RFC can identify 323 themselves as "HTTP/2.0". Until such an RFC exists, implementations 324 MUST NOT identify themselves using "HTTP/2.0". 326 Examples and text throughout the rest of this document use "HTTP/2.0" 327 as a matter of editorial convenience only. Implementations of draft 328 versions MUST NOT identify using this string. The exception to this 329 rule is the string included in the connection header sent by clients 330 immediately after establishing an HTTP/2.0 connection (see 331 Section 3.5); this fixed length sequence of octets does not change. 333 Implementations of draft versions of the protocol MUST add the string 334 "-draft-" and the corresponding draft number to the identifier before 335 the separator ('/'). For example, draft-ietf-httpbis-http2-03 is 336 identified using the string "HTTP-draft-03/2.0". 338 Non-compatible experiments that are based on these draft versions 339 MUST instead replace the string "draft" with a different identifier. 340 For example, an experimental implementation of packet mood-based 341 encoding based on draft-ietf-httpbis-http2-07 might identify itself 342 as "HTTP-emo-07/2.0". Note that any label MUST conform to the 343 "token" syntax defined in Section 3.2.6 of [HTTP-p1]. Experimenters 344 are encouraged to coordinate their experiments on the 345 ietf-http-wg@w3.org mailing list. 347 3.2. Starting HTTP/2.0 for "http" URIs 349 A client that makes a request to an "http" URI without prior 350 knowledge about support for HTTP/2.0 uses the HTTP Upgrade mechanism 351 (Section 6.7 of [HTTP-p1]). The client makes an HTTP/1.1 request 352 that includes an Upgrade header field identifying HTTP/2.0. The 353 HTTP/1.1 request MUST include exactly one HTTP2-Settings 354 (Section 3.2.1) header field. 356 For example: 358 GET /default.htm HTTP/1.1 359 Host: server.example.com 360 Connection: Upgrade, HTTP2-Settings 361 Upgrade: HTTP/2.0 362 HTTP2-Settings: 364 Requests that contain a request entity body MUST be sent in their 365 entirety before the client can send HTTP/2.0 frames. This means that 366 a large request entity can block the use of the connection until it 367 is completely sent. 369 If concurrency of an initial request with subsequent requests is 370 important, a small request can be used to perform the upgrade to 371 HTTP/2.0, at the cost of an additional round trip. 373 A server that does not support HTTP/2.0 can respond to the request as 374 though the Upgrade header field were absent: 376 HTTP/1.1 200 OK 377 Content-length: 243 378 Content-type: text/html 380 ... 382 A server that supports HTTP/2.0 accepts the upgrade with a 101 383 (Switching Protocols) status code. After the empty line that 384 terminates the 101 response, the server can begin sending HTTP/2.0 385 frames. These frames MUST include a response to the request that 386 initiated the Upgrade. 388 HTTP/1.1 101 Switching Protocols 389 Connection: Upgrade 390 Upgrade: HTTP/2.0 392 [ HTTP/2.0 connection ... 394 The first HTTP/2.0 frame sent by the server is a SETTINGS frame 395 (Section 6.5). Upon receiving the 101 response, the client sends a 396 connection header (Section 3.5), which includes a SETTINGS frame. 398 The HTTP/1.1 request that is sent prior to upgrade is associated with 399 stream 1 and is assigned the highest possible priority. Stream 1 is 400 implicitly half closed from the client toward the server, since the 401 request is completed as an HTTP/1.1 request. After commencing the 402 HTTP/2.0 connection, stream 1 is used for the response. 404 3.2.1. HTTP2-Settings Header Field 406 A client that upgrades from HTTP/1.1 to HTTP/2.0 MUST include exactly 407 one "HTTP2-Settings" header field. The "HTTP2-Settings" header field 408 is a hop-by-hop header field that includes settings that govern the 409 HTTP/2.0 connection, provided in anticipation of the server accepting 410 the request to upgrade. A server MUST reject an attempt to upgrade 411 if this header is not present. 413 HTTP2-Settings = token68 415 The content of the "HTTP2-Settings" header field is the payload of a 416 SETTINGS frame (Section 6.5), encoded as a base64url string (that is, 417 the URL- and filename-safe Base64 encoding described in Section 5 of 418 [RFC4648], with any trailing '=' characters omitted). The ABNF 419 [RFC5234] production for "token68" is defined in Section 2.1 of 420 [HTTP-p7]. 422 The client MUST include values for the following settings 423 (Section 6.5.1): 425 o SETTINGS_MAX_CONCURRENT_STREAMS 427 o SETTINGS_INITIAL_WINDOW_SIZE 429 As a hop-by-hop header field, the "Connection" header field MUST 430 include a value of "HTTP2-Settings" in addition to "Upgrade" when 431 upgrading to HTTP/2.0. 433 A server decodes and interprets these values as it would any other 434 SETTINGS frame. Providing these values in the Upgrade request 435 ensures that the protocol does not require default values for the 436 above settings, and gives a client an opportunity to provide other 437 settings prior to receiving any frames from the server. 439 3.3. Starting HTTP/2.0 for "https" URIs 441 A client that makes a request to an "https" URI without prior 442 knowledge about support for HTTP/2.0 uses TLS [TLS12] with the 443 application layer protocol negotiation extension [TLSALPN]. 445 Once TLS negotiation is complete, both the client and the server send 446 a connection header (Section 3.5). 448 3.4. Starting HTTP/2.0 with Prior Knowledge 450 A client can learn that a particular server supports HTTP/2.0 by 451 other means. A client MAY immediately send HTTP/2.0 frames to a 452 server that is known to support HTTP/2.0, after the connection header 453 (Section 3.5). This only affects the resolution of "http" URIs; 454 servers supporting HTTP/2.0 are required to support protocol 455 negotiation in TLS [TLSALPN] for "https" URIs. 457 Prior support for HTTP/2.0 is not a strong signal that a given server 458 will support HTTP/2.0 for future connections. It is possible for 459 server configurations to change or for configurations to differ 460 between instances in clustered server. Interception proxies (a.k.a. 461 "transparent" proxies) are another source of variability. 463 3.5. Connection Header 465 Upon establishment of a TCP connection and determination that 466 HTTP/2.0 will be used by both peers, each endpoint MUST send a 467 connection header as a final confirmation and to establish the 468 initial settings for the HTTP/2.0 connection. 470 The client connection header is a sequence of 24 octets, which in hex 471 notation are: 473 505249202a20485454502f322e300d0a0d0a534d0d0a0d0a 475 (the string "PRI * HTTP/2.0\r\n\r\nSM\r\n\r\n") followed by a 476 SETTINGS frame (Section 6.5). The client sends the client connection 477 header immediately upon receipt of a 101 Switching Protocols response 478 (indicating a successful upgrade), or as the first application data 479 octets of a TLS connection. If starting an HTTP/2.0 connection with 480 prior knowledge of server support for the protocol, the client 481 connection header is sent upon connection establishment. 483 The client connection header is selected so that a large 484 proportion of HTTP/1.1 or HTTP/1.0 servers and intermediaries do 485 not attempt to process further frames. Note that this does not 486 address the concerns raised in [TALKING]. 488 The server connection header consists of just a SETTINGS frame 489 (Section 6.5) that MUST be the first frame the server sends in the 490 HTTP/2.0 connection. 492 To avoid unnecessary latency, clients are permitted to send 493 additional frames to the server immediately after sending the client 494 connection header, without waiting to receive the server connection 495 header. It is important to note, however, that the server connection 496 header SETTINGS frame might include parameters that necessarily alter 497 how a client is expected to communicate with the server. Upon 498 receiving the SETTINGS frame, the client is expected to honor any 499 parameters established. 501 Clients and servers MUST terminate the TCP connection if either peer 502 does not begin with a valid connection header. A GOAWAY frame 503 (Section 6.8) MAY be omitted if it is clear that the peer is not 504 using HTTP/2.0. 506 4. HTTP Frames 508 Once the HTTP/2.0 connection is established, endpoints can begin 509 exchanging frames. 511 4.1. Frame Format 513 All frames begin with an 8-octet header followed by a payload of 514 between 0 and 65,535 octets. 516 0 1 2 3 517 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 518 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 519 | Length (16) | Type (8) | Flags (8) | 520 +-+-------------+---------------+-------------------------------+ 521 |R| Stream Identifier (31) | 522 +-+-------------------------------------------------------------+ 523 | Frame Payload (0...) ... 524 +---------------------------------------------------------------+ 526 Frame Header 528 The fields of the frame header are defined as: 530 Length: The length of the frame payload expressed as an unsigned 16- 531 bit integer. The 8 octets of the frame header are not included in 532 this value. 534 Type: The 8-bit type of the frame. The frame type determines how 535 the remainder of the frame header and payload are interpreted. 536 Implementations MUST ignore frames of unsupported or unrecognized 537 types. 539 Flags: An 8-bit field reserved for frame-type specific boolean 540 flags. 542 Flags are assigned semantics specific to the indicated frame type. 543 Flags that have no defined semantics for a particular frame type 544 MUST be ignored, and MUST be left unset (0) when sending. 546 R: A reserved 1-bit field. The semantics of this bit are undefined 547 and the bit MUST remain unset (0) when sending and MUST be ignored 548 when receiving. 550 Stream Identifier: A 31-bit stream identifier (see Section 5.1.1). 551 A value 0 is reserved for frames that are associated with the 552 connection as a whole as opposed to an individual stream. 554 The structure and content of the frame payload is dependent entirely 555 on the frame type. 557 4.2. Frame Size 559 The maximum size of a frame payload varies by frame type and use. 560 For instance, the HTTP/2.0 usage limits frames to 2^16-1 (16,383) 561 octets (Section 9.3). All implementations SHOULD be capable of 562 receiving and minimally processing frames up to the maximum size. 564 Certain frame types, such as PING (see Section 6.7), impose 565 additional limits on the amount of payload data allowed. Likewise, 566 additional size limits can be set by specific application uses (see 567 Section 9). 569 If a frame size exceeds any defined limit, or is too small to contain 570 mandatory frame data, the endpoint MUST send a FRAME_TOO_LARGE error. 571 Frame size errors in frames that affect connection-level state MUST 572 be treated as a connection error (Section 5.4.1). 574 4.3. Header Compression and Decompression 576 A header in HTTP/2.0 is a name-value pair with one or more associated 577 values. They are used within HTTP request and response messages as 578 well as server push operations (see Section 8.2). 580 Header sets are logical collections of zero or more header fields 581 arranged at the application layer. When transmitted over a 582 connection, the header set is serialized into a header block using 583 HTTP Header Compression [COMPRESSION]. The serialized header block 584 is then divided into one or more octet sequences, called header block 585 fragments, and transmitted within the payload of HEADERS 586 (Section 6.2), PUSH_PROMISE (Section 6.6) or CONTINUATION 587 (Section 6.10) frames. The receiving endpoint reassembles the header 588 block by concatenating the individual fragments, then decompresses 589 the block to reconstruct the header set. 591 Header block fragments can only be sent as the payload of HEADERS, 592 PUSH_PROMISE or CONTINUATION frames. 594 A compressed and encoded header block is transmitted in a HEADERS or 595 PUSH_PROMISE frame, followed by zero or more CONTINUATION frames. If 596 the number of octets in the block is greater than the space remaining 597 in the frame, the block is divided into multiple fragments, which are 598 then transmitted in multiple frames. 600 Header blocks MUST be transmitted as a contiguous sequence of frames, 601 with no interleaved frames of any other type, or from any other 602 stream. The last frame in a sequence of HEADERS/CONTINUATION frames 603 MUST have the END_HEADERS flag set. The last frame in a sequence of 604 PUSH_PROMISE/CONTINUATION frames MUST have the END_PUSH_PROMISE/ 605 END_HEADERS flag set (respectively). 607 HEADERS, PUSH_PROMISE and CONTINUATION frames carry data that can 608 modify the compression context maintained by a receiver. An endpoint 609 receiving HEADERS, PUSH_PROMISE or CONTINUATION frames MUST 610 reassemble header blocks and perform decompression even if the frames 611 are to be discarded, which is likely to occur after a stream is 612 reset. A receiver MUST terminate the connection with a connection 613 error (Section 5.4.1) of type COMPRESSION_ERROR, if it does not 614 decompress a header block. 616 5. Streams and Multiplexing 618 A "stream" is an independent, bi-directional sequence of HEADERS and 619 DATA frames exchanged between the client and server within an 620 HTTP/2.0 connection. Streams have several important characteristics: 622 o A single HTTP/2.0 connection can contain multiple concurrently 623 active streams, with either endpoint interleaving frames from 624 multiple streams. 626 o Streams can be established and used unilaterally or shared by 627 either the client or server. 629 o Streams can be closed by either endpoint. 631 o The order in which frames are sent within a stream is significant. 632 Recipients process frames in the order they are received. 634 o Streams are identified by an integer. Stream identifiers are 635 assigned to streams by the endpoint that initiates a stream. 637 5.1. Stream States 639 The lifecycle of a stream is shown in Figure 1. 641 +--------+ 642 PP | | PP 643 ,--------| idle |--------. 644 / | | \ 645 v +--------+ v 646 +----------+ | +----------+ 647 | | | H | | 648 ,---| reserved | | | reserved |---. 649 | | (local) | v | (remote) | | 650 | +----------+ +--------+ +----------+ | 651 | | ES | | ES | | 652 | | H ,-------| open |-------. | H | 653 | | / | | \ | | 654 | v v +--------+ v v | 655 | +----------+ | +----------+ | 656 | | half | | | half | | 657 | | closed | | R | closed | | 658 | | (remote) | | | (local) | | 659 | +----------+ | +----------+ | 660 | | v | | 661 | | ES / R +--------+ ES / R | | 662 | `----------->| |<-----------' | 663 | R | closed | R | 664 `-------------------->| |<--------------------' 665 +--------+ 667 Figure 1: Stream States 669 Both endpoints have a subjective view of the state of a stream that 670 could be different when frames are in transit. Endpoints do not 671 coordinate the creation of streams, they are created unilaterally by 672 either endpoint. The negative consequences of a mismatch in states 673 are limited to the "closed" state after sending RST_STREAM, where 674 frames might be received for some time after closing. 676 Streams have the following states: 678 idle: 679 All streams start in the "idle" state. In this state, no frames 680 have been exchanged. 682 The following transitions are valid from this state: 684 * Sending or receiving a HEADERS frame causes the stream to 685 become "open". The stream identifier is selected as described 686 in Section 5.1.1. 688 * Sending a PUSH_PROMISE frame marks the associated stream for 689 later use. The stream state for the reserved stream 690 transitions to "reserved (local)". 692 * Receiving a PUSH_PROMISE frame marks the associated stream as 693 reserved by the remote peer. The state of the stream becomes 694 "reserved (remote)". 696 reserved (local): 697 A stream in the "reserved (local)" state is one that has been 698 promised by sending a PUSH_PROMISE frame. A PUSH_PROMISE frame 699 reserves an idle stream by associating the stream with an open 700 stream that was initiated by the remote peer (see Section 8.2). 702 In this state, only the following transitions are possible: 704 * The endpoint can send a HEADERS frame. This causes the stream 705 to open in a "half closed (remote)" state. 707 * Either endpoint can send a RST_STREAM frame to cause the stream 708 to become "closed". This also releases the stream reservation. 710 An endpoint MUST NOT send any other type of frame in this state. 711 Receiving any frame other than RST_STREAM or PRIORITY MUST be 712 treated as a connection error (Section 5.4.1) of type 713 PROTOCOL_ERROR. 715 reserved (remote): 716 A stream in the "reserved (remote)" state has been reserved by a 717 remote peer. 719 In this state, only the following transitions are possible: 721 * Receiving a HEADERS frame causes the stream to transition to 722 "half closed (local)". 724 * Either endpoint can send a RST_STREAM frame to cause the stream 725 to become "closed". This also releases the stream reservation. 727 Receiving any other type of frame MUST be treated as a stream 728 error (Section 5.4.2) of type PROTOCOL_ERROR. An endpoint MAY 729 send RST_STREAM or PRIORITY frames in this state to cancel or 730 reprioritize the reserved stream. 732 open: 733 The "open" state is where both peers can send frames of any type. 734 In this state, sending peers observe advertised stream level flow 735 control limits (Section 5.2). 737 From this state either endpoint can send a frame with a END_STREAM 738 flag set, which causes the stream to transition into one of the 739 "half closed" states: an endpoint sending a END_STREAM flag causes 740 the stream state to become "half closed (local)"; an endpoint 741 receiving a END_STREAM flag causes the stream state to become 742 "half closed (remote)". 744 Either endpoint can send a RST_STREAM frame from this state, 745 causing it to transition immediately to "closed". 747 half closed (local): 748 A stream that is "half closed (local)" cannot be used for sending 749 frames. 751 A stream transitions from this state to "closed" when a frame that 752 contains a END_STREAM flag is received, or when either peer sends 753 a RST_STREAM frame. 755 A receiver can ignore WINDOW_UPDATE or PRIORITY frames in this 756 state. These frame types might arrive for a short period after a 757 frame bearing the END_STREAM flag is sent. 759 half closed (remote): 760 A stream that is "half closed (remote)" is no longer being used by 761 the peer to send frames. In this state, an endpoint is no longer 762 obligated to maintain a receiver flow control window if it 763 performs flow control. 765 If an endpoint receives additional frames for a stream that is in 766 this state it MUST respond with a stream error (Section 5.4.2) of 767 type STREAM_CLOSED. 769 A stream can transition from this state to "closed" by sending a 770 frame that contains a END_STREAM flag, or when either peer sends a 771 RST_STREAM frame. 773 closed: 774 The "closed" state is the terminal state. 776 An endpoint MUST NOT send frames on a closed stream. An endpoint 777 that receives a frame after receiving a RST_STREAM or a frame 778 containing a END_STREAM flag on that stream MUST treat that as a 779 stream error (Section 5.4.2) of type STREAM_CLOSED. 781 WINDOW_UPDATE, PRIORITY, or RST_STREAM frames can be received in 782 this state for a short period after a a frame containing an 783 END_STREAM flag is sent. Until the remote peer receives and 784 processes the frame bearing the END_STREAM flag, it might send 785 frame of any of these types. Endpoints MUST ignore WINDOW_UPDATE, 786 PRIORITY, or RST_STREAM frames received in this state, though 787 endpoints MAY choose to treat frames that arrive a significant 788 time after sending END_STREAM as a connection error 789 (Section 5.4.1) of type PROTOCOL_ERROR. 791 If this state is reached as a result of sending a RST_STREAM 792 frame, the peer that receives the RST_STREAM might have already 793 sent - or enqueued for sending - frames on the stream that cannot 794 be withdrawn. An endpoint MUST ignore frames that it receives on 795 closed streams after it has sent a RST_STREAM frame. An endpoint 796 MAY choose to limit the period over which it ignores frames and 797 treat frames that arrive after this time as being in error. 799 Flow controlled frames (i.e., DATA) received after sending 800 RST_STREAM are counted toward the connection flow control window. 801 Even though these frames might be ignored, because they are sent 802 before the sender receives the RST_STREAM, the sender will 803 consider the frames to count against the flow control window. 805 An endpoint might receive a PUSH_PROMISE frame after it sends 806 RST_STREAM. PUSH_PROMISE causes a stream to become "reserved". 807 The RST_STREAM does not cancel any promised stream. Therefore, if 808 promised streams are not desired, a RST_STREAM can be used to 809 close any of those streams. 811 In the absence of more specific guidance elsewhere in this document, 812 implementations SHOULD treat the receipt of a message that is not 813 expressly permitted in the description of a state as a connection 814 error (Section 5.4.1) of type PROTOCOL_ERROR. 816 5.1.1. Stream Identifiers 818 Streams are identified with an unsigned 31-bit integer. Streams 819 initiated by a client MUST use odd-numbered stream identifiers; those 820 initiated by the server MUST use even-numbered stream identifiers. A 821 stream identifier of zero (0x0) is used for connection control 822 message; the stream identifier zero MUST NOT be used to establish a 823 new stream. 825 A stream identifier of one (0x1) is used to respond to the HTTP/1.1 826 request which was specified during Upgrade (see Section 3.2). After 827 the upgrade completes, stream 0x1 is "half closed (local)" to the 828 client. Therefore, stream 0x1 cannot be selected as a new stream 829 identifier by a client that upgrades from HTTP/1.1. 831 The identifier of a newly established stream MUST be numerically 832 greater than all streams that the initiating endpoint has opened or 833 reserved. This governs streams that are opened using a HEADERS frame 834 and streams that are reserved using PUSH_PROMISE. An endpoint that 835 receives an unexpected stream identifier MUST respond with a 836 connection error (Section 5.4.1) of type PROTOCOL_ERROR. 838 The first use of a new stream identifier implicitly closes all 839 streams in the "idle" state that might have been initiated by that 840 peer with a lower-valued stream identifier. For example, if a client 841 sends a HEADERS frame on stream 7 without ever sending a frame on 842 stream 5, then stream 5 transitions to the "closed" state when the 843 first frame for stream 7 is sent or received. 845 Stream identifiers cannot be reused. Long-lived connections can 846 result in endpoint exhausting the available range of stream 847 identifiers. A client that is unable to establish a new stream 848 identifier can establish a new connection for new streams. 850 5.1.2. Stream Concurrency 852 A peer can limit the number of concurrently active streams using the 853 SETTINGS_MAX_CONCURRENT_STREAMS parameters within a SETTINGS frame. 854 The maximum concurrent streams setting is specific to each endpoint 855 and applies only to the peer that receives the setting. That is, 856 clients specify the maximum number of concurrent streams the server 857 can initiate, and servers specify the maximum number of concurrent 858 streams the client can initiate. Endpoints MUST NOT exceed the limit 859 set by their peer. 861 Streams that are in the "open" state, or either of the "half closed" 862 states count toward the maximum number of streams that an endpoint is 863 permitted to open. Streams in any of these three states count toward 864 the limit advertised in the SETTINGS_MAX_CONCURRENT_STREAMS setting 865 (see Section 6.5.2). 867 Streams in either of the "reserved" states do not count as open, even 868 if a small amount of application state is retained to ensure that the 869 promised stream can be successfully used. 871 5.2. Flow Control 873 Using streams for multiplexing introduces contention over use of the 874 TCP connection, resulting in blocked streams. A flow control scheme 875 ensures that streams on the same connection do not destructively 876 interfere with each other. Flow control is used for both individual 877 streams and for the connection as a whole. 879 HTTP/2.0 provides for flow control through use of the WINDOW_UPDATE 880 frame type. 882 5.2.1. Flow Control Principles 884 HTTP/2.0 stream flow control aims to allow for future improvements to 885 flow control algorithms without requiring protocol changes. Flow 886 control in HTTP/2.0 has the following characteristics: 888 1. Flow control is hop-by-hop, not end-to-end. 890 2. Flow control is based on window update frames. Receivers 891 advertise how many bytes they are prepared to receive on a stream 892 and for the entire connection. This is a credit-based scheme. 894 3. Flow control is directional with overall control provided by the 895 receiver. A receiver MAY choose to set any window size that it 896 desires for each stream and for the entire connection. A sender 897 MUST respect flow control limits imposed by a receiver. Clients, 898 servers and intermediaries all independently advertise their flow 899 control preferences as a receiver and abide by the flow control 900 limits set by their peer when sending. 902 4. The initial value for the flow control window is 65535 bytes for 903 both new streams and the overall connection. 905 5. The frame type determines whether flow control applies to a 906 frame. Of the frames specified in this document, only DATA 907 frames are subject to flow control; all other frame types do not 908 consume space in the advertised flow control window. This 909 ensures that important control frames are not blocked by flow 910 control. 912 6. Flow control can be disabled by a receiver. A receiver can 913 choose to disable both forms of flow control by sending the 914 SETTINGS_FLOW_CONTROL_OPTIONS setting. See Ending Flow Control 915 (Section 6.9.4) for more details. 917 7. HTTP/2.0 standardizes only the format of the WINDOW_UPDATE frame 918 (Section 6.9). This does not stipulate how a receiver decides 919 when to send this frame or the value that it sends. Nor does it 920 specify how a sender chooses to send packets. Implementations 921 are able to select any algorithm that suits their needs. 923 Implementations are also responsible for managing how requests and 924 responses are sent based on priority; choosing how to avoid head of 925 line blocking for requests; and managing the creation of new streams. 926 Algorithm choices for these could interact with any flow control 927 algorithm. 929 5.2.2. Appropriate Use of Flow Control 931 Flow control is defined to protect endpoints that are operating under 932 resource constraints. For example, a proxy needs to share memory 933 between many connections, and also might have a slow upstream 934 connection and a fast downstream one. Flow control addresses cases 935 where the receiver is unable process data on one stream, yet wants to 936 continue to process other streams in the same connection. 938 Deployments that do not require this capability SHOULD disable flow 939 control for data that is being received. Note that flow control 940 cannot be disabled for sending. Sending data is always subject to 941 the flow control window advertised by the receiver. 943 Deployments with constrained resources (for example, memory) MAY 944 employ flow control to limit the amount of memory a peer can consume. 945 Note, however, that this can lead to suboptimal use of available 946 network resources if flow control is enabled without knowledge of the 947 bandwidth-delay product (see [RFC1323]). 949 Even with full awareness of the current bandwidth-delay product, 950 implementation of flow control can be difficult. When using flow 951 control, the receive MUST read from the TCP receive buffer in a 952 timely fashion. Failure to do so could lead to a deadlock when 953 critical frames, such as WINDOW_UPDATE, are not available to 954 HTTP/2.0. However, flow control can ensure that constrained 955 resources are protected without any reduction in connection 956 utilization. 958 5.3. Stream priority 960 The endpoint establishing a new stream can assign a priority for the 961 stream. Priority is represented as an unsigned 31-bit integer. 0 962 represents the highest priority and 2^31-1 represents the lowest 963 priority. 965 The purpose of this value is to allow an endpoint to express the 966 relative priority of a stream. An endpoint can use this information 967 to preferentially allocate resources to a stream. Within HTTP/2.0, 968 priority can be used to select streams for transmitting frames when 969 there is limited capacity for sending. For instance, an endpoint 970 might enqueue frames for all concurrently active streams. As 971 transmission capacity becomes available, frames from higher priority 972 streams might be sent before lower priority streams. 974 Explicitly setting the priority for a stream does not guarantee any 975 particular processing or transmision order for the stream relative to 976 any other stream. Nor is there any mechanism provided by which the 977 initiator of a stream can force or require a receiving endpoint to 978 process concurrent streams in a particular order. 980 Unless explicitly specified in the HEADERS frame (Section 6.2) during 981 stream creation, the default stream priority is 2^30. 983 Pushed streams (Section 8.2) have a lower priority than their 984 associated stream. The promised stream inherits the priority value 985 of the associated stream plus one, up to a maximum of 2^31-1. 987 5.4. Error Handling 989 HTTP/2.0 framing permits two classes of error: 991 o An error condition that renders the entire connection unusable is 992 a connection error. 994 o An error in an individual stream is a stream error. 996 A list of error codes is included in Section 7. 998 5.4.1. Connection Error Handling 1000 A connection error is any error which prevents further processing of 1001 the framing layer or which corrupts any connection state. 1003 An endpoint that encounters a connection error SHOULD first send a 1004 GOAWAY frame (Section 6.8) with the stream identifier of the last 1005 stream that it successfully received from its peer. The GOAWAY frame 1006 includes an error code that indicates why the connection is 1007 terminating. After sending the GOAWAY frame, the endpoint MUST close 1008 the TCP connection. 1010 It is possible that the GOAWAY will not be reliably received by the 1011 receiving endpoint. In the event of a connection error, GOAWAY only 1012 provides a best-effort attempt to communicate with the peer about why 1013 the connection is being terminated. 1015 An endpoint can end a connection at any time. In particular, an 1016 endpoint MAY choose to treat a stream error as a connection error. 1017 Endpoints SHOULD send a GOAWAY frame when ending a connection, as 1018 long as circumstances permit it. 1020 5.4.2. Stream Error Handling 1022 A stream error is an error related to a specific stream identifier 1023 that does not affect processing of other streams. 1025 An endpoint that detects a stream error sends a RST_STREAM frame 1026 (Section 6.4) that contains the stream identifier of the stream where 1027 the error occurred. The RST_STREAM frame includes an error code that 1028 indicates the type of error. 1030 A RST_STREAM is the last frame that an endpoint can send on a stream. 1031 The peer that sends the RST_STREAM frame MUST be prepared to receive 1032 any frames that were sent or enqueued for sending by the remote peer. 1033 These frames can be ignored, except where they modify connection 1034 state (such as the state maintained for header compression 1035 (Section 4.3)). 1037 Normally, an endpoint SHOULD NOT send more than one RST_STREAM frame 1038 for any stream. However, an endpoint MAY send additional RST_STREAM 1039 frames if it receives frames on a closed stream after more than a 1040 round trip time. This behavior is permitted to deal with misbehaving 1041 implementations. 1043 An endpoint MUST NOT send a RST_STREAM in response to an RST_STREAM 1044 frame, to avoid looping. 1046 5.4.3. Connection Termination 1048 If the TCP connection is torn down while streams remain in open or 1049 half closed states, then the endpoint MUST assume that the stream was 1050 abnormally interrupted and could be incomplete. 1052 6. Frame Definitions 1054 This specification defines a number of frame types, each identified 1055 by a unique 8-bit type code. Each frame type serves a distinct 1056 purpose either in the establishment and management of the connection 1057 as a whole, or of individual streams. 1059 The transmission of specific frame types can alter the state of a 1060 connection. If endpoints fail to maintain a synchronized view of the 1061 connection state, successful communication within the connection will 1062 no longer be possible. Therefore, it is important that endpoints 1063 have a shared comprehension of how the state is affected by the use 1064 any given frame. Accordingly, while it is expected that new frame 1065 types will be introduced by extensions to this protocol, only frames 1066 defined by this document are permitted to alter the connection state. 1068 6.1. DATA 1070 DATA frames (type=0x0) convey arbitrary, variable-length sequences of 1071 octets associated with a stream. One or more DATA frames are used, 1072 for instance, to carry HTTP request or response payloads. 1074 The DATA frame defines the following flags: 1076 END_STREAM (0x1): Bit 1 being set indicates that this frame is the 1077 last that the endpoint will send for the identified stream. 1078 Setting this flag causes the stream to enter a "half closed" or 1079 "closed" state (Section 5.1). 1081 RESERVED (0x2): Bit 2 is reserved for future use. 1083 DATA frames MUST be associated with a stream. If a DATA frame is 1084 received whose stream identifier field is 0x0, the recipient MUST 1085 respond with a connection error (Section 5.4.1) of type 1086 PROTOCOL_ERROR. 1088 DATA frames are subject to flow control and can only be sent when a 1089 stream is in the "open" or "half closed (remote)" states. 1091 6.2. HEADERS 1093 The HEADERS frame (type=0x1) carries name-value pairs. It is used to 1094 open a stream (Section 5.1). HEADERS frames can be sent on a stream 1095 in the "open" or "half closed (remote)" states. 1097 0 1 2 3 1098 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 1099 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1100 |X| Priority (31) | 1101 +-+-------------------------------------------------------------+ 1102 | Header Block Fragment (*) ... 1103 +---------------------------------------------------------------+ 1105 HEADERS Frame Payload 1107 The HEADERS frame defines the following flags: 1109 END_STREAM (0x1): Bit 1 being set indicates that this frame is the 1110 last that the endpoint will send for the identified stream. 1111 Setting this flag causes the stream to enter a "half closed" state 1112 (Section 5.1). 1114 RESERVED (0x2): Bit 2 is reserved for future use. 1116 END_HEADERS (0x4): The END_HEADERS bit indicates that this frame 1117 ends the sequence of header block fragments necessary to provide a 1118 complete set of headers. 1120 The payload for a complete header block is provided by a sequence 1121 of that starts with a HEADERS frame, followed by zero or more 1122 CONTINUATION frames. The sequence is terminated by a frame with 1123 the END_HEADERS flag set. Once the sequence terminates, the 1124 payload of all HEADERS and CONTINUATION frames are concatenated 1125 and interpreted as a single block. 1127 A HEADERS frame without the END_HEADERS flag set MUST be followed 1128 by a CONTINUATION frame for the same stream. A receiver MUST 1129 treat the receipt of any other type of frame or a frame on a 1130 different stream as a connection error (Section 5.4.1) of type 1131 PROTOCOL_ERROR. 1133 PRIORITY (0x8): Bit 4 being set indicates that the first four octets 1134 of this frame contain a single reserved bit and a 31-bit priority; 1135 see Section 5.3. If this bit is not set, the four bytes do not 1136 appear and the frame only contains a header block fragment. 1138 The payload of a HEADERS frame contains a header block fragment 1139 (Section 4.3). A header block that does not fit within a HEADERS 1140 frame is continued in a CONTINUATION frame (Section 6.10). 1142 HEADERS frames MUST be associated with a stream. If a HEADERS frame 1143 is received whose stream identifier field is 0x0, the recipient MUST 1144 respond with a connection error (Section 5.4.1) of type 1145 PROTOCOL_ERROR. 1147 The HEADERS frame changes the connection state as described in 1148 Section 4.3. 1150 6.3. PRIORITY 1152 The PRIORITY frame (type=0x2) specifies the sender-advised priority 1153 of a stream. It can be sent at any time for an existing stream. 1154 This enables reprioritisation of existing streams. 1156 0 1 2 3 1157 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 1158 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1159 |X| Priority (31) | 1160 +-+-------------------------------------------------------------+ 1162 PRIORITY Frame Payload 1164 The payload of a PRIORITY frame contains a single reserved bit and a 1165 31-bit priority. 1167 The PRIORITY frame does not define any flags. 1169 The PRIORITY frame is associated with an existing stream. If a 1170 PRIORITY frame is received with a stream identifier of 0x0, the 1171 recipient MUST respond with a connection error (Section 5.4.1) of 1172 type PROTOCOL_ERROR. 1174 The PRIORITY frame can be sent on a stream in any of the "reserved 1175 (remote)", "open", "half-closed (local)", or "half closed (remote)" 1176 states, though it cannot be sent between consecutive frames that 1177 comprise a single header block (Section 4.3). Note that this frame 1178 could arrive after processing or frame sending has completed, which 1179 would cause it to have no effect. For a stream that is in the "half 1180 closed (remote)" state, this frame can only affect processing of the 1181 stream and not frame transmission. 1183 6.4. RST_STREAM 1185 The RST_STREAM frame (type=0x3) allows for abnormal termination of a 1186 stream. When sent by the initiator of a stream, it indicates that 1187 they wish to cancel the stream or that an error condition has 1188 occurred. When sent by the receiver of a stream, it indicates that 1189 either the receiver is rejecting the stream, requesting that the 1190 stream be cancelled or that an error condition has occurred. 1192 0 1 2 3 1193 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 1194 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1195 | Error Code (32) | 1196 +---------------------------------------------------------------+ 1198 RST_STREAM Frame Payload 1200 The RST_STREAM frame contains a single unsigned, 32-bit integer 1201 identifying the error code (Section 7). The error code indicates why 1202 the stream is being terminated. 1204 The RST_STREAM frame does not define any flags. 1206 The RST_STREAM frame fully terminates the referenced stream and 1207 causes it to enter the closed state. After receiving a RST_STREAM on 1208 a stream, the receiver MUST NOT send additional frames for that 1209 stream. However, after sending the RST_STREAM, the sending endpoint 1210 MUST be prepared to receive and process additional frames sent on the 1211 stream that might have been sent by the peer prior to the arrival of 1212 the RST_STREAM. 1214 RST_STREAM frames MUST be associated with a stream. If a RST_STREAM 1215 frame is received with a stream identifier of 0x0, the recipient MUST 1216 treat this as a connection error (Section 5.4.1) of type 1217 PROTOCOL_ERROR. 1219 RST_STREAM frames MUST NOT be sent for a stream in the "idle" state. 1220 If a RST_STREAM frame identifying an idle stream is received, the 1221 recipient MUST treat this as a connection error (Section 5.4.1) of 1222 type PROTOCOL_ERROR. 1224 6.5. SETTINGS 1226 The SETTINGS frame (type=0x4) conveys configuration parameters that 1227 affect how endpoints communicate. The parameters are either 1228 constraints on peer behavior or preferences. 1230 SETTINGS frames MUST be sent at the start of a connection, and MAY be 1231 sent at any other time by either endpoint over the lifetime of the 1232 connection. 1234 Implementations MUST support all of the settings defined by this 1235 specification and MAY support additional settings defined by 1236 extensions. Unsupported or unrecognized settings MUST be ignored. 1237 New settings MUST NOT be defined or implemented in a way that 1238 requires endpoints to understand them in order to communicate 1239 successfully. 1241 Each setting in a SETTINGS frame replaces the existing value for that 1242 setting. Settings are processed in the order in which they appear, 1243 and a receiver of a SETTINGS frame does not need to maintain any 1244 state other than the current value of settings. Therefore, the value 1245 of a setting is the last value that is seen by a receiver. This 1246 permits the inclusion of the same settings multiple times in the same 1247 SETTINGS frame, though doing so does nothing other than waste 1248 connection capacity. 1250 The SETTINGS frame does not define any flags. 1252 SETTINGS frames always apply to a connection, never a single stream. 1253 The stream identifier for a settings frame MUST be zero. If an 1254 endpoint receives a SETTINGS frame whose stream identifier field is 1255 anything other than 0x0, the endpoint MUST respond with a connection 1256 error (Section 5.4.1) of type PROTOCOL_ERROR. 1258 The SETTINGS frame affects connection state. A badly formed or 1259 incomplete SETTINGS frame MUST be treated as a connection error 1260 (Section 5.4.1) of type PROTOCOL_ERROR. 1262 6.5.1. Setting Format 1264 The payload of a SETTINGS frame consists of zero or more settings. 1265 Each setting consists of an 8-bit reserved field, an unsigned 24-bit 1266 setting identifier, and an unsigned 32-bit value. 1268 0 1 2 3 1269 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 1270 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1271 | Reserved (8) | Setting Identifier (24) | 1272 +---------------+-----------------------------------------------+ 1273 | Value (32) | 1274 +---------------------------------------------------------------+ 1276 Setting Format 1278 6.5.2. Defined Settings 1280 The following settings are defined: 1282 SETTINGS_MAX_CONCURRENT_STREAMS (4): indicates the maximum number of 1283 concurrent streams that the sender will allow. This limit is 1284 directional: it applies to the number of streams that the sender 1285 permits the receiver to create. By default there is no limit. It 1286 is recommended that this value be no smaller than 100, so as to 1287 not unnecessarily limit parallelism. 1289 SETTINGS_INITIAL_WINDOW_SIZE (7): indicates the sender's initial 1290 window size (in bytes) for stream level flow control. 1292 This settings affects the window size of all streams, including 1293 existing streams, see Section 6.9.2. 1295 SETTINGS_FLOW_CONTROL_OPTIONS (10): indicates flow control options. 1296 The least significant bit (0x1) of the value is set to indicate 1297 that the sender has disabled all flow control. This bit cannot be 1298 cleared once set, see Section 6.9.4. 1300 All bits other than the least significant are reserved. 1302 6.6. PUSH_PROMISE 1304 The PUSH_PROMISE frame (type=0x5) is used to notify the peer endpoint 1305 in advance of streams the sender intends to initiate. The 1306 PUSH_PROMISE frame includes the unsigned 31-bit identifier of the 1307 stream the endpoint plans to create along with a minimal set of 1308 headers that provide additional context for the stream. Section 8.2 1309 contains a thorough description of the use of PUSH_PROMISE frames. 1311 0 1 2 3 1312 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 1313 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1314 |X| Promised-Stream-ID (31) | 1315 +-+-------------------------------------------------------------+ 1316 | Header Block Fragment (*) ... 1317 +---------------------------------------------------------------+ 1319 PUSH_PROMISE Payload Format 1321 The payload of a PUSH_PROMISE includes a "Promised-Stream-ID". This 1322 unsigned 31-bit integer identifies the stream the endpoint intends to 1323 start sending frames for. The promised stream identifier MUST be a 1324 valid choice for the next stream sent by the sender (see new stream 1325 identifier (Section 5.1.1)). 1327 Following the "Promised-Stream-ID" is a header block fragment 1328 (Section 4.3). 1330 PUSH_PROMISE frames MUST be associated with an existing, peer- 1331 initiated stream. If the stream identifier field specifies the value 1332 0x0, a recipient MUST respond with a connection error (Section 5.4.1) 1333 of type PROTOCOL_ERROR. 1335 The PUSH_PROMISE frame defines the following flags: 1337 END_PUSH_PROMISE (0x4): The END_PUSH_PROMISE bit indicates that this 1338 frame ends the sequence of header block fragments necessary to 1339 provide a complete set of headers. 1341 The payload for a complete header block is provided by a sequence 1342 of frames that starts with a PUSH_PROMISE frame, followed by zero 1343 or more CONTINUATION frames. The sequence terminates by a 1344 PUSH_PROMISE frame with the END_PUSH_PROMISE flag set or a 1345 CONTINUATION frame with the END_HEADERS flag set. Once the 1346 sequence terminates, the payload of all frames in the sequence are 1347 concatenated and interpreted as a single block. 1349 A PUSH_PROMISE frame without the END_PUSH_PROMISE flag set MUST be 1350 followed by a CONTINUATION frame for the same stream. A receiver 1351 MUST treat the receipt of any other type of frame or a frame on a 1352 different stream as a connection error (Section 5.4.1) of type 1353 PROTOCOL_ERROR. 1355 Promised streams are not required to be used in order promised. The 1356 PUSH_PROMISE only reserves stream identifiers for later use. 1358 Recipients of PUSH_PROMISE frames can choose to reject promised 1359 streams by returning a RST_STREAM referencing the promised stream 1360 identifier back to the sender of the PUSH_PROMISE. 1362 The PUSH_PROMISE frame modifies the connection state as defined in 1363 Section 4.3. 1365 A PUSH_PROMISE frame modifies the connection state in two ways. The 1366 inclusion of a header block (Section 4.3) potentially modifies the 1367 compression state. PUSH_PROMISE also reserves a stream for later 1368 use, causing the promised stream to enter the "reserved" state. A 1369 sender MUST NOT send a PUSH_PROMISE on a stream unless that stream is 1370 either "open" or "half closed (remote)"; the sender MUST ensure that 1371 the promised stream is a valid choice for a new stream identifier 1372 (Section 5.1.1) (that is, the promised stream MUST be in the "idle" 1373 state). 1375 Since PUSH_PROMISE reserves a stream, ignoring a PUSH_PROMISE frame 1376 causes the stream state to become indeterminate. A receiver MUST 1377 treat the receipt of a PUSH_PROMISE on a stream that is neither 1378 "open" nor "half-closed (local)" as a connection error 1379 (Section 5.4.1) of type PROTOCOL_ERROR. Similarly, a receiver MUST 1380 treat the receipt of a PUSH_PROMISE that promises an illegal stream 1381 identifier (Section 5.1.1) (that is, an identifier for a stream that 1382 is not currently in the "idle" state) as a connection error 1383 (Section 5.4.1) of type PROTOCOL_ERROR, unless the receiver recently 1384 sent a RST_STREAM frame to cancel the associated stream (see 1385 Section 5.1). 1387 6.7. PING 1389 The PING frame (type=0x6) is a mechanism for measuring a minimal 1390 round-trip time from the sender, as well as determining whether an 1391 idle connection is still functional. PING frames can be sent from 1392 any endpoint. 1394 0 1 2 3 1395 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 1396 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1397 | | 1398 | Opaque Data (64) | 1399 | | 1400 +---------------------------------------------------------------+ 1402 PING Payload Format 1404 In addition to the frame header, PING frames MUST contain 8 octets of 1405 data in the payload. A sender can include any value it chooses and 1406 use those bytes in any fashion. 1408 Receivers of a PING frame that does not include a PONG flag MUST send 1409 a PING frame with the PONG flag set in response, with an identical 1410 payload. PING responses SHOULD given higher priority than any other 1411 frame. 1413 The PING frame defines the following flags: 1415 PONG (0x1): Bit 1 being set indicates that this PING frame is a PING 1416 response. An endpoint MUST set this flag in PING responses. An 1417 endpoint MUST NOT respond to PING frames containing this flag. 1419 PING frames are not associated with any individual stream. If a PING 1420 frame is received with a stream identifier field value other than 1421 0x0, the recipient MUST respond with a connection error 1422 (Section 5.4.1) of type PROTOCOL_ERROR. 1424 Receipt of a PING frame with a length field value other than 8 MUST 1425 be treated as a connection error (Section 5.4.1) of type 1426 PROTOCOL_ERROR. 1428 6.8. GOAWAY 1430 The GOAWAY frame (type=0x7) informs the remote peer to stop creating 1431 streams on this connection. It can be sent from the client or the 1432 server. Once sent, the sender will ignore frames sent on new streams 1433 for the remainder of the connection. Receivers of a GOAWAY frame 1434 MUST NOT open additional streams on the connection, although a new 1435 connection can be established for new streams. The purpose of this 1436 frame is to allow an endpoint to gracefully stop accepting new 1437 streams (perhaps for a reboot or maintenance), while still finishing 1438 processing of previously established streams. 1440 There is an inherent race condition between an endpoint starting new 1441 streams and the remote sending a GOAWAY frame. To deal with this 1442 case, the GOAWAY contains the stream identifier of the last stream 1443 which was processed on the sending endpoint in this connection. If 1444 the receiver of the GOAWAY used streams that are newer than the 1445 indicated stream identifier, they were not processed by the sender 1446 and the receiver may treat the streams as though they had never been 1447 created at all (hence the receiver may want to re-create the streams 1448 later on a new connection). 1450 Endpoints SHOULD always send a GOAWAY frame before closing a 1451 connection so that the remote can know whether a stream has been 1452 partially processed or not. For example, if an HTTP client sends a 1453 POST at the same time that a server closes a connection, the client 1454 cannot know if the server started to process that POST request if the 1455 server does not send a GOAWAY frame to indicate where it stopped 1456 working. An endpoint might choose to close a connection without 1457 sending GOAWAY for misbehaving peers. 1459 After sending a GOAWAY frame, the sender can discard frames for new 1460 streams. However, any frames that alter connection state cannot be 1461 completely ignored. For instance, HEADERS, PUSH_PROMISE and 1462 CONTINUATION frames MUST be minimally processed to ensure a 1463 consistent compression state (see Section 4.3); similarly DATA frames 1464 MUST be counted toward the connection flow control window. 1466 0 1 2 3 1467 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 1468 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1469 |X| Last-Stream-ID (31) | 1470 +-+-------------------------------------------------------------+ 1471 | Error Code (32) | 1472 +---------------------------------------------------------------+ 1473 | Additional Debug Data (*) | 1474 +---------------------------------------------------------------+ 1476 GOAWAY Payload Format 1478 The GOAWAY frame does not define any flags. 1480 The GOAWAY frame applies to the connection, not a specific stream. 1481 The stream identifier MUST be zero. 1483 The last stream identifier in the GOAWAY frame contains the highest 1484 numbered stream identifier for which the sender of the GOAWAY frame 1485 has received frames on and might have taken some action on. All 1486 streams up to and including the identified stream might have been 1487 processed in some way. The last stream identifier is set to 0 if no 1488 streams were processed. 1490 Note: In this case, "processed" means that some data from the 1491 stream was passed to some higher layer of software that might have 1492 taken some action as a result. 1494 If a connection terminates without a GOAWAY frame, this value is 1495 effectively the highest stream identifier. 1497 On streams with lower or equal numbered identifiers that were not 1498 closed completely prior to the connection being closed, re-attempting 1499 requests, transactions, or any protocol activity is not possible 1500 (with the exception of idempotent actions like HTTP GET, PUT, or 1501 DELETE). Any protocol activity that uses higher numbered streams can 1502 be safely retried using a new connection. 1504 Activity on streams numbered lower or equal to the last stream 1505 identifier might still complete successfully. The sender of a GOAWAY 1506 frame might gracefully shut down a connection by sending a GOAWAY 1507 frame, maintaining the connection in an open state until all in- 1508 progress streams complete. 1510 The last stream ID MUST be 0 if no streams were acted upon. 1512 The GOAWAY frame also contains a 32-bit error code (Section 7) that 1513 contains the reason for closing the connection. 1515 Endpoints MAY append opaque data to the payload of any GOAWAY frame. 1516 Additional debug data is intended for diagnostic purposes only and 1517 carries no semantic value. Debug data MUST NOT be persistently 1518 stored, since it could contain sensitive information. 1520 6.9. WINDOW_UPDATE 1522 The WINDOW_UPDATE frame (type=0x9) is used to implement flow control. 1524 Flow control operates at two levels: on each individual stream and on 1525 the entire connection. 1527 Both types of flow control are hop by hop; that is, only between the 1528 two endpoints. Intermediaries do not forward WINDOW_UPDATE frames 1529 between dependent connections. However, throttling of data transfer 1530 by any receiver can indirectly cause the propagation of flow control 1531 information toward the original sender. 1533 Flow control only applies to frames that are identified as being 1534 subject to flow control. Of the frame types defined in this 1535 document, this includes only DATA frame. Frames that are exempt from 1536 flow control MUST be accepted and processed, unless the receiver is 1537 unable to assign resources to handling the frame. A receiver MAY 1538 respond with a stream error (Section 5.4.2) or connection error 1539 (Section 5.4.1) of type FLOW_CONTROL_ERROR if it is unable accept a 1540 frame. 1542 0 1 2 3 1543 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 1544 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1545 |X| Window Size Increment (31) | 1546 +-+-------------------------------------------------------------+ 1548 WINDOW_UPDATE Payload Format 1550 The payload of a WINDOW_UPDATE frame is one reserved bit, plus an 1551 unsigned 31-bit integer indicating the number of bytes that the 1552 sender can transmit in addition to the existing flow control window. 1553 The legal range for the increment to the flow control window is 1 to 1554 2^31 - 1 (0x7fffffff) bytes. 1556 The WINDOW_UPDATE frame does not define any flags. 1558 The WINDOW_UPDATE frame can be specific to a stream or to the entire 1559 connection. In the former case, the frame's stream identifier 1560 indicates the affected stream; in the latter, the value "0" indicates 1561 that the entire connection is the subject of the frame. 1563 WINDOW_UPDATE can be sent by a peer that has sent a frame bearing the 1564 END_STREAM flag. This means that a receiver could receive a 1565 WINDOW_UPDATE frame on a "half closed (remote)" or "closed" stream. 1566 A receiver MUST NOT treat this as an error, see Section 5.1. 1568 A receiver that receives a flow controlled frame MUST always account 1569 for its contribution against the connection flow control window, 1570 unless the receiver treats this as a connection error 1571 (Section 5.4.1). This is necessary even if the frame is in error. 1572 Since the sender counts the frame toward the flow control window, if 1573 the receiver does not, the flow control window at sender and receiver 1574 can become different. 1576 6.9.1. The Flow Control Window 1578 Flow control in HTTP/2.0 is implemented using a window kept by each 1579 sender on every stream. The flow control window is a simple integer 1580 value that indicates how many bytes of data the sender is permitted 1581 to transmit; as such, its size is a measure of the buffering 1582 capability of the receiver. 1584 Two flow control windows are applicable: the stream flow control 1585 window and the connection flow control window. The sender MUST NOT 1586 send a flow controlled frame with a length that exceeds the space 1587 available in either of the flow control windows advertised by the 1588 receiver. Frames with zero length with the END_STREAM flag set (for 1589 example, an empty data frame) MAY be sent if there is no available 1590 space in either flow control window. 1592 For flow control calculations, the 8 byte frame header is not 1593 counted. 1595 After sending a flow controlled frame, the sender reduces the space 1596 available in both windows by the length of the transmitted frame. 1598 The receiver of a frame sends a WINDOW_UPDATE frame as it consumes 1599 data and frees up space in flow control windows. Separate 1600 WINDOW_UPDATE frames are sent for the stream and connection level 1601 flow control windows. 1603 A sender that receives a WINDOW_UPDATE frame updates the 1604 corresponding window by the amount specified in the frame. 1606 A sender MUST NOT allow a flow control window to exceed 2^31 - 1 1607 bytes. If a sender receives a WINDOW_UPDATE that causes a flow 1608 control window to exceed this maximum it MUST terminate either the 1609 stream or the connection, as appropriate. For streams, the sender 1610 sends a RST_STREAM with the error code of FLOW_CONTROL_ERROR code; 1611 for the connection, a GOAWAY frame with a FLOW_CONTROL_ERROR code. 1613 Flow controlled frames from the sender and WINDOW_UPDATE frames from 1614 the receiver are completely asynchronous with respect to each other. 1615 This property allows a receiver to aggressively update the window 1616 size kept by the sender to prevent streams from stalling. 1618 6.9.2. Initial Flow Control Window Size 1620 When a HTTP/2.0 connection is first established, new streams are 1621 created with an initial flow control window size of 65535 bytes. The 1622 connection flow control window is 65535 bytes. Both endpoints can 1623 adjust the initial window size for new streams by including a value 1624 for SETTINGS_INITIAL_WINDOW_SIZE in the SETTINGS frame that forms 1625 part of the connection header. 1627 Prior to receiving a SETTINGS frame that sets a value for 1628 SETTINGS_INITIAL_WINDOW_SIZE, an endpoint can only use the default 1629 initial window size when sending flow controlled frames. Similarly, 1630 the connection flow control window is set to the default initial 1631 window size until a WINDOW_UPDATE frame is received. 1633 A SETTINGS frame can alter the initial flow control window size for 1634 all current streams. When the value of SETTINGS_INITIAL_WINDOW_SIZE 1635 changes, a receiver MUST adjust the size of all stream flow control 1636 windows that it maintains by the difference between the new value and 1637 the old value. A SETTINGS frame cannot alter the connection flow 1638 control window. 1640 A change to SETTINGS_INITIAL_WINDOW_SIZE could cause the available 1641 space in a flow control window to become negative. A sender MUST 1642 track the negative flow control window, and MUST NOT send new flow 1643 controlled frames until it receives WINDOW_UPDATE frames that cause 1644 the flow control window to become positive. 1646 For example, if the client sends 60KB immediately on connection 1647 establishment, and the server sets the initial window size to be 1648 16KB, the client will recalculate the available flow control window 1649 to be -44KB on receipt of the SETTINGS frame. The client retains a 1650 negative flow control window until WINDOW_UPDATE frames restore the 1651 window to being positive, after which the client can resume sending. 1653 6.9.3. Reducing the Stream Window Size 1655 A receiver that wishes to use a smaller flow control window than the 1656 current size can send a new SETTINGS frame. However, the receiver 1657 MUST be prepared to receive data that exceeds this window size, since 1658 the sender might send data that exceeds the lower limit prior to 1659 processing the SETTINGS frame. 1661 A receiver has two options for handling streams that exceed flow 1662 control limits: 1664 1. The receiver can immediately send RST_STREAM with 1665 FLOW_CONTROL_ERROR error code for the affected streams. 1667 2. The receiver can accept the streams and tolerate the resulting 1668 head of line blocking, sending WINDOW_UPDATE frames as it 1669 consumes data. 1671 If a receiver decides to accept streams, both sides MUST recompute 1672 the available flow control window based on the initial window size 1673 sent in the SETTINGS. 1675 6.9.4. Ending Flow Control 1677 After a receiver reads in a frame that marks the end of a stream (for 1678 example, a data stream with a END_STREAM flag set), it MUST cease 1679 transmission of WINDOW_UPDATE frames for that stream. A sender is 1680 not obligated to maintain the available flow control window for 1681 streams that it is no longer sending on. 1683 Flow control can be disabled the entire connection using the 1684 SETTINGS_FLOW_CONTROL_OPTIONS setting. This setting ends all forms 1685 of flow control. An implementation that does not wish to perform 1686 flow control can use this in the initial SETTINGS exchange. 1688 Flow control cannot be enabled again once disabled. Any attempt to 1689 re-enable flow control - by sending a WINDOW_UPDATE or by clearing 1690 the bits on the SETTINGS_FLOW_CONTROL_OPTIONS setting - MUST be 1691 rejected with a FLOW_CONTROL_ERROR error code. 1693 6.10. CONTINUATION 1695 The CONTINUATION frame (type=0xA) is used to continue a sequence of 1696 header block fragments (Section 4.3). Any number of CONTINUATION 1697 frames can be sent on an existing stream, as long as the preceding 1698 frame on the same stream is one of HEADERS, PUSH_PROMISE or 1699 CONTINUATION. 1701 0 1 2 3 1702 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 1703 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1704 | Header Block Fragment (*) ... 1705 +---------------------------------------------------------------+ 1707 CONTINUATION Frame Payload 1709 The CONTINUATION frame defines the following flags: 1711 END_STREAM (0x1): Bit 1 being set indicates that this frame is the 1712 last that the endpoint will send for the identified stream. 1713 Setting this flag causes the stream to enter a "half closed" or 1714 "closed" state (Section 5.1). [[anchor12: We have not decided yet 1715 if it is a good idea to keep this flag here since it could be used 1716 to end a stream by being attached to a PUSH_PROMISE continuation. 1717 See https://github.com/http2/http2-spec/issues/228 for details.]] 1719 Unused (0x2): This flag is not currently used. 1721 END_HEADERS (0x4): The END_HEADERS bit indicates that this frame 1722 ends the sequence of header block fragments necessary to provide a 1723 complete set of headers. 1725 The payload for a complete header block is provided by a sequence 1726 that starts with a HEADERS or PUSH_PROMISE frame and zero or more 1727 CONTINUATION frames, terminated by a HEADERS or CONTINUATION frame 1728 with the END_HEADERS flag set, or PUSH_PROMISE frame with the 1729 END_PUSH_PROMISE flag set. Once the sequence terminates, the 1730 payload of all frames in the sequence are concatenated and 1731 interpreted as a single block. 1733 A HEADERS, PUSH_PROMISE, or CONTINUATION frame without the 1734 END_HEADERS flag set MUST be followed by a CONTINUATION frame for 1735 the same stream. A receiver MUST treat the receipt of any other 1736 type of frame or a frame on a different stream as a connection 1737 error (Section 5.4.1) of type PROTOCOL_ERROR. 1739 The payload of a CONTINUATION frame contains a header block fragment 1740 (Section 4.3). 1742 The CONTINUATION frame changes the connection state as defined in 1743 Section 4.3. 1745 CONTINUATION frames MUST be associated with a stream. If a 1746 CONTINUATION frame is received whose stream identifier field is 0x0, 1747 the recipient MUST respond with a connection error (Section 5.4.1) of 1748 type PROTOCOL_ERROR. 1750 header block fragments (Section 4.3). A CONTINUATION frame MUST be 1751 preceded by one of HEADERS, PUSH_PROMISE or CONTINUATION frame. A 1752 recipient that observes violation of this rule MUST respond with a 1753 connection error (Section 5.4.1) of type PROTOCOL_ERROR. 1755 7. Error Codes 1757 Error codes are 32-bit fields that are used in RST_STREAM and GOAWAY 1758 frames to convey the reasons for the stream or connection error. 1760 Error codes share a common code space. Some error codes only apply 1761 to specific conditions and have no defined semantics in certain frame 1762 types. 1764 The following error codes are defined: 1766 NO_ERROR (0): The associated condition is not as a result of an 1767 error. For example, a GOAWAY might include this code to indicate 1768 graceful shutdown of a connection. 1770 PROTOCOL_ERROR (1): The endpoint detected an unspecific protocol 1771 error. This error is for use when a more specific error code is 1772 not available. 1774 INTERNAL_ERROR (2): The endpoint encountered an unexpected internal 1775 error. 1777 FLOW_CONTROL_ERROR (3): The endpoint detected that its peer violated 1778 the flow control protocol. 1780 STREAM_CLOSED (5): The endpoint received a frame after a stream was 1781 half closed. 1783 FRAME_TOO_LARGE (6): The endpoint received a frame that was larger 1784 than the maximum size that it supports. 1786 REFUSED_STREAM (7): The endpoint refuses the stream prior to 1787 performing any application processing, see Section 8.1.3 for 1788 details. 1790 CANCEL (8): Used by the endpoint to indicate that the stream is no 1791 longer needed. 1793 COMPRESSION_ERROR (9): The endpoint is unable to maintain the 1794 compression context for the connection. 1796 8. HTTP Message Exchanges 1798 HTTP/2.0 is intended to be as compatible as possible with current 1799 web-based applications. This means that, from the perspective of the 1800 server business logic or application API, the features of HTTP are 1801 unchanged. To achieve this, all of the application request and 1802 response header semantics are preserved, although the syntax of 1803 conveying those semantics has changed. Thus, the rules from HTTP/1.1 1804 ([HTTP-p1], [HTTP-p2], [HTTP-p4], [HTTP-p5], [HTTP-p6], and 1805 [HTTP-p7]) apply with the changes in the sections below. 1807 8.1. HTTP Request/Response Exchange 1809 A client sends an HTTP request on a new stream, using a previously 1810 unused stream identifier (Section 5.1.1). A server sends an HTTP 1811 response on the same stream as the request. 1813 An HTTP request or response each consist of: 1815 1. a HEADERS frame; 1817 2. one contiguous sequence of zero or more CONTINUATION frames; 1819 3. zero or more DATA frames; and 1821 4. optionally, a contiguous sequence that starts with a HEADERS 1822 frame, followed by zero or more CONTINUATION frames. 1824 The last frame in the sequence bears an END_STREAM flag. 1826 Other frames MAY be interspersed with these frames, but those frames 1827 do not carry HTTP semantics. In particular, HEADERS frames (and any 1828 CONTINUATION frames that follow) other than the first and optional 1829 last frames in this sequence do not carry HTTP semantics. 1831 Trailing header fields are carried in a header block that also 1832 terminates the stream. That is, a sequence starting with a HEADERS 1833 frame, followed by zero or more CONTINUATION frames, that carries an 1834 END_STREAM flag on the last frame. Header blocks after the first 1835 that do not terminate the stream are not part of an HTTP request or 1836 response. 1838 An HTTP request/response exchange fully consumes a single stream. A 1839 request starts with the HEADERS frame that puts the stream into an 1840 "open" state and ends with a frame bearing END_STREAM, which causes 1841 the stream to become "half closed" for the client. A response starts 1842 with a HEADERS frame and ends with a frame bearing END_STREAM, which 1843 places the stream in the "closed" state. 1845 8.1.1. Examples 1847 For example, an HTTP GET request that includes request header fields 1848 and no body, is transmitted as a single contiguous sequence of 1849 HEADERS frames containing the serialized block of request header 1850 fields. The last HEADERS frame in the sequence has both the 1851 END_HEADERS and END_STREAM flag set: 1853 GET /resource HTTP/1.1 HEADERS 1854 Host: example.org ==> + END_STREAM 1855 Accept: image/jpeg + END_HEADERS 1856 :method = GET 1857 :scheme = https 1858 :host = example.org 1859 :path = /resource 1860 accept = image/jpeg 1862 Similarly, a response that includes only response header fields is 1863 transmitted as a sequence of HEADERS frames containing the serialized 1864 block of response header fields. The last HEADERS frame in the 1865 sequence has both the END_HEADERS and END_STREAM flag set: 1867 HTTP/1.1 204 No Content HEADERS 1868 Content-Length: 0 ===> + END_STREAM 1869 + END_HEADERS 1870 :status = 204 1871 content-length: 0 1873 An HTTP POST request that includes request header fields and payload 1874 data is transmitted as one HEADERS frame, followed by zero or more 1875 CONTINUATION frames, containing the request headers followed by one 1876 or more DATA frames, with the last CONTINUATION (or HEADERS) frame 1877 having the END_HEADERS flag set and the final DATA frame having the 1878 END_STREAM flag set: 1880 POST /resource HTTP/1.1 HEADERS 1881 Host: example.org ==> - END_STREAM 1882 Content-Type: image/jpeg + END_HEADERS 1883 Content-Length: 123 :method = POST 1884 :scheme = https 1885 {binary data} :host = example.org 1886 :path = /resource 1887 content-type = image/jpeg 1888 content-length = 123 1890 DATA 1891 + END_STREAM 1892 {binary data} 1894 A response that includes header fields and payload data is 1895 transmitted as a HEADERS frame, followed by zero or more CONTINUATION 1896 frames, followed by one or more DATA frames, with the last DATA frame 1897 in the sequence having the END_STREAM flag set: 1899 HTTP/1.1 200 OK HEADERS 1900 Content-Type: image/jpeg ==> - END_STREAM 1901 Content-Length: 123 + END_HEADERS 1902 :status = 200 1903 {binary data} content-type = image/jpeg 1904 content-length = 123 1906 DATA 1907 + END_STREAM 1908 {binary data} 1910 Trailing header fields are sent as a header block after both the 1911 request or response header block and all the DATA frames have been 1912 sent. The sequence of HEADERS/CONTINUATION frames that bears the 1913 trailers includes a terminal frame that has both END_HEADERS and 1914 END_STREAM flags set. 1916 HTTP/1.1 200 OK HEADERS 1917 Content-Type: image/jpeg ===> - END_STREAM 1918 Content-Length: 123 + END_HEADERS 1919 TE: trailers :status = 200 1920 123 content-type = image/jpeg 1921 {binary data} content-length = 123 1922 0 1923 Foo: bar DATA 1924 - END_STREAM 1925 {binary data} 1927 HEADERS 1928 + END_STREAM 1929 + END_HEADERS 1930 foo: bar 1932 8.1.2. HTTP Header Fields 1934 HTTP/2.0 request and response header fields carry information as a 1935 series of key-value pairs. This includes the target URI for the 1936 request, the status code for the response, as well as HTTP header 1937 fields. 1939 HTTP header field names are strings of ASCII characters that are 1940 compared in a case-insensitive fashion. Note that header compression 1941 could cause case information to be lost. 1943 The semantics of HTTP header fields are not altered by this 1944 specification, though header fields relating to connection management 1945 or request framing are no longer necessary. An HTTP/2.0 request or 1946 response MUST NOT include any of the following header fields: 1947 Connection, Host, Keep-Alive, Proxy-Connection, TE, Transfer- 1948 Encoding, and Upgrade. A server MUST treat the presence of any of 1949 these header fields as a stream error (Section 5.4.2) of type 1950 PROTOCOL_ERROR. 1952 8.1.2.1. Request Header Fields 1954 HTTP/2.0 defines a number of headers starting with a ':' character 1955 that carry information about the request target: 1957 o The ":method" header field includes the HTTP method ([HTTP-p2], 1958 Section 4). 1960 o The ":scheme" header field includes the scheme portion of the 1961 target URI ([RFC3986], Section 3.1). 1963 o The ":host" header field includes the authority portion of the 1964 target URI ([RFC3986], Section 3.2). 1966 o The ":path" header field includes the path and query parts of the 1967 target URI (the "path-absolute" production from [RFC3986] and 1968 optionally a '?' character followed by the "query" production, see 1969 [RFC3986], Section 3.3 and [RFC3986], Section 3.4). This field 1970 MUST NOT be empty; URIs that do not contain a path component MUST 1971 include a value of '/', unless the request is an OPTIONS request 1972 for '*', in which case the ":path" header field MUST include '*'. 1974 All HTTP/2.0 requests MUST include exactly one valid value for all of 1975 these header fields. An intermediary MUST ensure that requests that 1976 it forwards are correct. A server MUST treat the absence of any of 1977 these header fields, presence of multiple values, or an invalid value 1978 as a stream error (Section 5.4.2) of type PROTOCOL_ERROR. 1980 HTTP/2.0 does not define a way to carry the version identifier that 1981 is included in the HTTP/1.1 request line. 1983 All HTTP Requests that include a body can include a "content-length" 1984 header field. If a server receives a request where the sum of the 1985 DATA frame payload lengths does not equal the value of the 1986 "content-length" header field, the server MUST return a 400 (Bad 1987 Request) error. 1989 8.1.2.2. Response Header Fields 1991 A single ":status" header field is defined that carries the HTTP 1992 status code field (see [HTTP-p2], Section 6). This header field MUST 1993 be included in all responses. An intermediary MUST ensure that it 1994 does not forward responses with absent or invalid values. A client 1995 MUST treat the absence of the ":status"" header field, the presence 1996 of multiple values, or an invalid value as a stream error 1997 (Section 5.4.2) of type PROTOCOL_ERROR. 1999 HTTP/2.0 does not define a way to carry the version or reason phrase 2000 that is included in an HTTP/1.1 status line. 2002 8.1.3. Request Reliability Mechanisms in HTTP/2.0 2004 In HTTP/1.1, an HTTP client is unable to retry a non-idempotent 2005 request when an error occurs, because there is no means to determine 2006 the nature of the error. It is possible that some server processing 2007 occurred prior to the error, which could result in undesirable 2008 effects if the request were reattempted. 2010 HTTP/2.0 provides two mechanisms for providing a guarantee to a 2011 client that a request has not been processed: 2013 o The GOAWAY frame indicates the highest stream number that might 2014 have been processed. Requests on streams with higher numbers are 2015 therefore guaranteed to be safe to retry. 2017 o The REFUSED_STREAM error code can be included in a RST_STREAM 2018 frame to indicate that the stream is being closed prior to any 2019 processing having occurred. Any request that was sent on the 2020 reset stream can be safely retried. 2022 In both cases, clients MAY automatically retry all requests, 2023 including those with non-idempotent methods. 2025 A server MUST NOT indicate that a stream has not been processed 2026 unless it can guarantee that fact. If frames that are on a stream 2027 are passed to the application layer for any stream, then 2028 REFUSED_STREAM MUST NOT be used for that stream, and a GOAWAY frame 2029 MUST include a stream identifier that is greater than or equal to the 2030 given stream identifier. 2032 In addition to these mechanisms, the PING frame provides a way for a 2033 client to easily test a connection. Connections that remain idle can 2034 become broken as some middleboxes (for instance, network address 2035 translators, or load balancers) silently discard connection bindings. 2036 The PING frame allows a client to safely test whether a connection is 2037 still active without sending a request. 2039 8.2. Server Push 2041 HTTP/2.0 enables a server to pre-emptively send (or "push") multiple 2042 associated resources to a client in response to a single request. 2043 This feature becomes particularly helpful when the server knows the 2044 client will need to have those resources available in order to fully 2045 process the originally requested resource. 2047 Pushing additional resources is optional, and is negotiated only 2048 between individual endpoints. For instance, an intermediary could 2049 receive pushed resources from the server but is not required to 2050 forward those on to the client. How to make use of the pushed 2051 resources is up to that intermediary. Equally, the intermediary 2052 might choose to push additional resources to the client, without any 2053 action taken by the server. 2055 8.2.1. Push Requests 2057 Server push is semantically equivalent to a server responding to a 2058 request. The PUSH_PROMISE frame, or frames, sent by the server 2059 includes a header block that contains a complete set of request 2060 headers that the server attributes to the request. It is not 2061 possible to push a response to a request that includes a request 2062 body. 2064 Pushed resources are always associated with an explicit request from 2065 a client. The PUSH_PROMISE frames sent by the server are sent on the 2066 stream created for the original request. The PUSH_PROMISE frame 2067 includes a promised stream identifier, chosen from the stream 2068 identifiers available to the server (see Section 5.1.1). 2070 The header fields in PUSH_PROMISE and any subsequent CONTINUATION 2071 frames MUST be a valid and complete set of request headers 2072 (Section 8.1.2.1). The server MUST include a method in the ":method" 2073 header field that is safe (see [HTTP-p2], Section 4.2.1). If a 2074 client receives a PUSH_PROMISE that does not include a complete and 2075 valid set of header fields, or the ":method" header field identifies 2076 a method that is not safe, it MUST respond with a stream error 2077 (Section 5.4.2) of type PROTOCOL_ERROR. 2079 The server SHOULD send PUSH_PROMISE (Section 6.6) frames prior to 2080 sending any frames that reference the promised resources. This 2081 avoids a race where clients issue requests for resources prior to 2082 receiving any PUSH_PROMISE frames. 2084 For example, if the server receives a request for a document 2085 containing embedded links to multiple image files, and the server 2086 chooses to push those additional images to the client, sending push 2087 promises before the DATA frames that contain the image links ensure 2088 that the client is able to see the promises before discovering the 2089 resources. Similarly, if the server pushes resources referenced by 2090 the header block (for instance, in Link header fields), sending the 2091 push promises before sending the header block ensures that clients do 2092 not request those resources. 2094 PUSH_PROMISE frames MUST NOT be sent by the client. PUSH_PROMISE 2095 frames can be sent by the server on any stream that was opened by the 2096 client. They MUST be sent on a stream that is in either the "open" 2097 or "half closed (remote)" to the server. PUSH_PROMISE frames are 2098 interspersed with the frames that comprise a response, though they 2099 cannot be interspersed with HEADERS and CONTINUATION frames that 2100 comprise a single header block. 2102 8.2.2. Push Responses 2104 After sending the PUSH_PROMISE frame, the server can begin delivering 2105 the pushed resource as a response (Section 8.1.2.2) on a server- 2106 initiated stream that uses the promised stream identifier. The 2107 server uses this stream to transmit an HTTP response, using the same 2108 sequence of frames as defined in Section 8.1. This stream becomes 2109 "half closed" to the client (Section 5.1) after the initial HEADERS 2110 frame is sent. 2112 Once a client receives a PUSH_PROMISE frame and chooses to accept the 2113 pushed resource, the client SHOULD NOT issue any requests for the 2114 promised resource until after the promised stream has closed. 2116 If the client determines, for any reason, that it does not wish to 2117 receive the pushed resource from the server, or if the server takes 2118 too long to begin sending the promised resource, the client can send 2119 an RST_STREAM frame, using either the CANCEL or REFUSED_STREAM codes, 2120 and referencing the pushed stream's identifier. 2122 A client can use the SETTINGS_MAX_CONCURRENT_STREAMS setting to limit 2123 the number of resources that can be concurrently pushed by a server. 2124 Advertising a SETTINGS_MAX_CONCURRENT_STREAMS value of zero disables 2125 server push by preventing the server from creating the necessary 2126 streams. This does not prohibit a server from sending PUSH_PROMISE 2127 frames; clients need to reset any promised streams that are not 2128 wanted. 2130 Clients receiving a pushed response MUST validate that the server is 2131 authorized to push the resource using the same-origin policy 2132 ([RFC6454], Section 3). For example, a HTTP/2.0 connection to 2133 "example.com" is generally [[anchor16: Ed: weaselly use of 2134 "generally", needs better definition]] not permitted to push a 2135 response for "www.example.org". 2137 9. Additional HTTP Requirements/Considerations 2139 This section outlines attributes of the HTTP protocol that improve 2140 interoperability, reduce exposure to known security vulnerabilities, 2141 or reduce the potential for implementation variation. 2143 9.1. Connection Management 2145 HTTP/2.0 connections are persistent. For best performance, it is 2146 expected clients will not close connections until it is determined 2147 that no further communication with a server is necessary (for 2148 example, when a user navigates away from a particular web page), or 2149 until the server closes the connection. 2151 Clients SHOULD NOT open more than one HTTP/2.0 connection to a given 2152 origin ([RFC6454]) concurrently. A client can create additional 2153 connections as replacements, either to replace connections that are 2154 near to exhausting the available stream identifiers (Section 5.1.1), 2155 or to replace connections that have encountered errors 2156 (Section 5.4.1). 2158 Servers are encouraged to maintain open connections for as long as 2159 possible, but are permitted to terminate idle connections if 2160 necessary. When either endpoint chooses to close the transport-level 2161 TCP connection, the terminating endpoint SHOULD first send a GOAWAY 2162 (Section 6.8) frame so that both endpoints can reliably determine 2163 whether previously sent frames have been processed and gracefully 2164 complete or terminate any necessary remaining tasks. 2166 9.2. Use of TLS Features 2168 Implementations of HTTP/2.0 MUST support TLS 1.1 [TLS11]. [[anchor19: 2169 The working group intends to require at least the use of TLS 1.2 2170 [TLS12] prior to publication of this document; negotiating TLS 1.1 is 2171 permitted to enable the creation of interoperable implementations of 2172 early drafts.]] 2174 The TLS implementation MUST support the Server Name Indication (SNI) 2175 [TLS-EXT] extension to TLS. HTTP/2.0 clients MUST indicate the 2176 target domain name when negotiating TLS. 2178 A server that receives a TLS handshake that does not include either 2179 TLS 1.1 or SNI, MUST NOT negotiate HTTP/2.0. Removing HTTP/2.0 2180 protocols from consideration could result in the removal of all 2181 protocols from the set of protocols offered by the client. This 2182 causes protocol negotiation failure, as described in Section 3.2 of 2183 [TLSALPN]. 2185 Implementations are encouraged not to negotiate TLS cipher suites 2186 with known vulnerabilities, such as [RC4]. 2188 9.3. Frame Size Limits for HTTP 2190 Frames used for HTTP messages MUST NOT exceed 2^14-1 (16,383) octets 2191 in length, not counting the 8 octet frame header. An endpoint MUST 2192 treat the receipt of a larger frame as a FRAME_TOO_LARGE error (see 2193 Section 4.2). 2195 9.4. GZip Content-Encoding 2197 Clients MUST support gzip compression for HTTP response bodies. 2198 Regardless of the value of the accept-encoding header field, a server 2199 MAY send responses with gzip or deflate encoding. A compressed 2200 response MUST still bear an appropriate content-encoding header 2201 field. 2203 10. Security Considerations 2205 10.1. Server Authority and Same-Origin 2207 This specification uses the same-origin policy ([RFC6454], Section 3) 2208 to determine whether an origin server is permitted to provide 2209 content. 2211 A server that is contacted using TLS is authenticated based on the 2212 certificate that it offers in the TLS handshake (see [RFC2818], 2213 Section 3). A server is considered authoritative for an "https" 2214 resource if it has been successfully authenticated for the domain 2215 part of the origin of the resource that it is providing. 2217 A server is considered authoritative for an "http" resource if the 2218 connection is established to a resolved IP address for the domain in 2219 the origin of the resource. 2221 A client MUST NOT use, in any way, resources provided by a server 2222 that is not authoritative for those resources. 2224 10.2. Cross-Protocol Attacks 2226 When using TLS, we believe that HTTP/2.0 introduces no new cross- 2227 protocol attacks. TLS encrypts the contents of all transmission 2228 (except the handshake itself), making it difficult for attackers to 2229 control the data which could be used in a cross-protocol attack. 2230 [[anchor23: Issue: This is no longer true]] 2232 10.3. Cacheability of Pushed Resources 2234 Pushed resources are responses without an explicit request; the 2235 request for a pushed resource is synthesized from the request that 2236 triggered the push, plus resource identification information provided 2237 by the server. Request header fields are necessary for HTTP cache 2238 control validations (such as the Vary header field) to work. For 2239 this reason, caches MUST inherit request header fields from the 2240 associated stream for the push. This includes the Cookie header 2241 field. 2243 Caching resources that are pushed is possible, based on the guidance 2244 provided by the origin server in the Cache-Control header field. 2245 However, this can cause issues if a single server hosts more than one 2246 tenant. For example, a server might offer multiple users each a 2247 small portion of its URI space. 2249 Where multiple tenants share space on the same server, that server 2250 MUST ensure that tenants are not able to push representations of 2251 resources that they do not have authority over. Failure to enforce 2252 this would allow a tenant to provide a representation that would be 2253 served out of cache, overriding the actual representation that the 2254 authoritative tenant provides. 2256 Pushed resources for which an origin server is not authoritative are 2257 never cached or used. 2259 11. Privacy Considerations 2261 HTTP/2.0 aims to keep connections open longer between clients and 2262 servers in order to reduce the latency when a user makes a request. 2263 The maintenance of these connections over time could be used to 2264 expose private information. For example, a user using a browser 2265 hours after the previous user stopped using that browser may be able 2266 to learn about what the previous user was doing. This is a problem 2267 with HTTP in its current form as well, however the short lived 2268 connections make it less of a risk. 2270 12. IANA Considerations 2272 This document establishes registries for frame types, error codes and 2273 settings. These new registries are entered in a new "Hypertext 2274 Transfer Protocol (HTTP) 2.0 Parameters" section. 2276 This document also registers the "HTTP2-Settings" header field for 2277 use in HTTP. 2279 12.1. Frame Type Registry 2281 This document establishes a registry for HTTP/2.0 frame types. The 2282 "HTTP/2.0 Frame Type" registry operates under the "IETF Review" 2283 policy [RFC5226]. 2285 Frame types are an 8-bit value. When reviewing new frame type 2286 registrations, special attention is advised for any frame type- 2287 specific flags that are defined. Frame flags can interact with 2288 existing flags and could prevent the creation of globally applicable 2289 flags. 2291 Initial values for the "HTTP/2.0 Frame Type" registry are shown in 2292 Table 1. 2294 +--------+---------------+---------------------------+--------------+ 2295 | Frame | Name | Flags | Section | 2296 | Type | | | | 2297 +--------+---------------+---------------------------+--------------+ 2298 | 0 | DATA | END_STREAM(1) | Section 6.1 | 2299 | 1 | HEADERS | END_STREAM(1), | Section 6.2 | 2300 | | | END_HEADERS(4), | | 2301 | | | PRIORITY(8) | | 2302 | 2 | PRIORITY | - | Section 6.3 | 2303 | 3 | RST_STREAM | - | Section 6.4 | 2304 | 4 | SETTINGS | - | Section 6.5 | 2305 | 5 | PUSH_PROMISE | END_PUSH_PROMISE(1) | Section 6.6 | 2306 | 6 | PING | PONG(1) | Section 6.7 | 2307 | 7 | GOAWAY | - | Section 6.8 | 2308 | 9 | WINDOW_UPDATE | - | Section 6.9 | 2309 | 10 | CONTINUATION | END_STREAM(1), | Section 6.10 | 2310 | | | END_HEADERS(4) | | 2311 +--------+---------------+---------------------------+--------------+ 2313 Table 1 2315 12.2. Error Code Registry 2317 This document establishes a registry for HTTP/2.0 error codes. The 2318 "HTTP/2.0 Error Code" registry manages a 32-bit space. The "HTTP/2.0 2319 Error Code" registry operates under the "Expert Review" policy 2320 [RFC5226]. 2322 Registrations for error codes are required to include a description 2323 of the error code. An expert reviewer is advised to examine new 2324 registrations for possible duplication with existing error codes. 2325 Use of existing registrations is to be encouraged, but not mandated. 2327 New registrations are advised to provide the following information: 2329 Error Code: The 32-bit error code value. 2331 Name: A name for the error code. Specifying an error code name is 2332 optional. 2334 Description: A description of the conditions where the error code is 2335 applicable. 2337 Specification: An optional reference for a specification that 2338 defines the error code. 2340 An initial set of error code registrations can be found in Section 7. 2342 12.3. Settings Registry 2344 This document establishes a registry for HTTP/2.0 settings. The 2345 "HTTP/2.0 Settings" registry manages a 24-bit space. The "HTTP/2.0 2346 Settings" registry operates under the "Expert Review" policy 2347 [RFC5226]. 2349 Registrations for settings are required to include a description of 2350 the setting. An expert reviewer is advised to examine new 2351 registrations for possible duplication with existing settings. Use 2352 of existing registrations is to be encouraged, but not mandated. 2354 New registrations are advised to provide the following information: 2356 Setting: The 24-bit setting value. 2358 Name: A name for the setting. Specifying a name is optional. 2360 Flags: Any setting-specific flags that apply, including their value 2361 and semantics. 2363 Description: A description of the setting. This might include the 2364 range of values, any applicable units and how to act upon a value 2365 when it is provided. 2367 Specification: An optional reference for a specification that 2368 defines the setting. 2370 An initial set of settings registrations can be found in 2371 Section 6.5.2. 2373 12.4. HTTP2-Settings Header Field Registration 2375 This section registers the "HTTP2-Settings" header field in the 2376 Permanent Message Header Field Registry [BCP90]. 2378 Header field name: HTTP2-Settings 2380 Applicable protocol: http 2382 Status: standard 2384 Author/Change controller: IETF 2386 Specification document(s): Section 3.2.1 of this document 2387 Related information: This header field is only used by an HTTP/2.0 2388 client for Upgrade-based negotiation. 2390 13. Acknowledgements 2392 This document includes substantial input from the following 2393 individuals: 2395 o Adam Langley, Wan-Teh Chang, Jim Morrison, Mark Nottingham, Alyssa 2396 Wilk, Costin Manolache, William Chan, Vitaliy Lvin, Joe Chan, Adam 2397 Barth, Ryan Hamilton, Gavin Peters, Kent Alstad, Kevin Lindsay, 2398 Paul Amer, Fan Yang, Jonathan Leighton (SPDY contributors). 2400 o Gabriel Montenegro and Willy Tarreau (Upgrade mechanism) 2402 o William Chan, Salvatore Loreto, Osama Mazahir, Gabriel Montenegro, 2403 Jitu Padhye, Roberto Peon, Rob Trace (Flow control) 2405 o Mark Nottingham, Julian Reschke, James Snell, Jeff Pinner 2406 (Substantial editorial contributions) 2408 14. References 2410 14.1. Normative References 2412 [COMPRESSION] Ruellan, H. and R. Peon, "HTTP Header Compression", 2413 draft-ietf-httpbis-header-compression-02 (work in 2414 progress), August 2013. 2416 [HTTP-p1] Fielding, R. and J. Reschke, "Hypertext Transfer 2417 Protocol (HTTP/1.1): Message Syntax and Routing", 2418 draft-ietf-httpbis-p1-messaging-23 (work in progress), 2419 July 2013. 2421 [HTTP-p2] Fielding, R. and J. Reschke, "Hypertext Transfer 2422 Protocol (HTTP/1.1): Semantics and Content", 2423 draft-ietf-httpbis-p2-semantics-23 (work in progress), 2424 July 2013. 2426 [HTTP-p4] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext 2427 Transfer Protocol (HTTP/1.1): Conditional Requests", 2428 draft-ietf-httpbis-p4-conditional-23 (work in 2429 progress), July 2013. 2431 [HTTP-p5] Fielding, R., Ed., Lafon, Y., Ed., and J. Reschke, 2432 Ed., "Hypertext Transfer Protocol (HTTP/1.1): Range 2433 Requests", draft-ietf-httpbis-p5-range-23 (work in 2434 progress), July 2013. 2436 [HTTP-p6] Fielding, R., Ed., Nottingham, M., Ed., and J. 2437 Reschke, Ed., "Hypertext Transfer Protocol (HTTP/1.1): 2438 Caching", draft-ietf-httpbis-p6-cache-23 (work in 2439 progress), July 2013. 2441 [HTTP-p7] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext 2442 Transfer Protocol (HTTP/1.1): Authentication", 2443 draft-ietf-httpbis-p7-auth-23 (work in progress), 2444 July 2013. 2446 [RFC0793] Postel, J., "Transmission Control Protocol", STD 7, 2447 RFC 793, September 1981. 2449 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 2450 Requirement Levels", BCP 14, RFC 2119, March 1997. 2452 [RFC2818] Rescorla, E., "HTTP Over TLS", RFC 2818, May 2000. 2454 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, 2455 "Uniform Resource Identifier (URI): Generic Syntax", 2456 STD 66, RFC 3986, January 2005. 2458 [RFC4648] Josefsson, S., "The Base16, Base32, and Base64 Data 2459 Encodings", RFC 4648, October 2006. 2461 [RFC5226] Narten, T. and H. Alvestrand, "Guidelines for Writing 2462 an IANA Considerations Section in RFCs", BCP 26, 2463 RFC 5226, May 2008. 2465 [RFC5234] Crocker, D. and P. Overell, "Augmented BNF for Syntax 2466 Specifications: ABNF", STD 68, RFC 5234, January 2008. 2468 [RFC6454] Barth, A., "The Web Origin Concept", RFC 6454, 2469 December 2011. 2471 [TLS-EXT] Eastlake, D., "Transport Layer Security (TLS) 2472 Extensions: Extension Definitions", RFC 6066, 2473 January 2011. 2475 [TLS11] Dierks, T. and E. Rescorla, "The Transport Layer 2476 Security (TLS) Protocol Version 1.1", RFC 4346, 2477 April 2006. 2479 [TLS12] Dierks, T. and E. Rescorla, "The Transport Layer 2480 Security (TLS) Protocol Version 1.2", RFC 5246, 2481 August 2008. 2483 [TLSALPN] Friedl, S., Popov, A., Langley, A., and E. Stephan, 2484 "Transport Layer Security (TLS) Application Layer 2485 Protocol Negotiation Extension", 2486 draft-ietf-tls-applayerprotoneg-01 (work in progress), 2487 April 2013. 2489 14.2. Informative References 2491 [BCP90] Klyne, G., Nottingham, M., and J. Mogul, "Registration 2492 Procedures for Message Header Fields", BCP 90, 2493 RFC 3864, September 2004. 2495 [RC4] Rivest, R., "The RC4 encryption algorithm", RSA Data 2496 Security, Inc. , March 1992. 2498 [RFC1323] Jacobson, V., Braden, B., and D. Borman, "TCP 2499 Extensions for High Performance", RFC 1323, May 1992. 2501 [TALKING] Huang, L-S., Chen, E., Barth, A., Rescorla, E., and C. 2502 Jackson, "Talking to Yourself for Fun and Profit", 2503 2011, . 2505 Appendix A. Change Log (to be removed by RFC Editor before publication) 2507 A.1. Since draft-ietf-httpbis-http2-05 2509 Marking the draft ready for implementation. 2511 Renumbering END_PUSH_PROMISE flag. 2513 Editorial clarifications and changes. 2515 A.2. Since draft-ietf-httpbis-http2-04 2517 Added CONTINUATION frame for HEADERS and PUSH_PROMISE. 2519 PUSH_PROMISE is no longer implicitly prohibited if 2520 SETTINGS_MAX_CONCURRENT_STREAMS is zero. 2522 Push expanded to allow all safe methods without a request body. 2524 Clarified the use of HTTP header fields in requests and responses. 2525 Prohibited HTTP/1.1 hop-by-hop header fields. 2527 Requiring that intermediaries not forward requests with missing or 2528 illegal routing :-headers. 2530 Clarified requirements around handling different frames after stream 2531 close, stream reset and GOAWAY. 2533 Added more specific prohibitions for sending of different frame types 2534 in various stream states. 2536 Making the last received setting value the effective value. 2538 Clarified requirements on TLS version, extension and ciphers. 2540 A.3. Since draft-ietf-httpbis-http2-03 2542 Committed major restructuring atrocities. 2544 Added reference to first header compression draft. 2546 Added more formal description of frame lifecycle. 2548 Moved END_STREAM (renamed from FINAL) back to HEADERS/DATA. 2550 Removed HEADERS+PRIORITY, added optional priority to HEADERS frame. 2552 Added PRIORITY frame. 2554 A.4. Since draft-ietf-httpbis-http2-02 2556 Added continuations to frames carrying header blocks. 2558 Replaced use of "session" with "connection" to avoid confusion with 2559 other HTTP stateful concepts, like cookies. 2561 Removed "message". 2563 Switched to TLS ALPN from NPN. 2565 Editorial changes. 2567 A.5. Since draft-ietf-httpbis-http2-01 2569 Added IANA considerations section for frame types, error codes and 2570 settings. 2572 Removed data frame compression. 2574 Added PUSH_PROMISE. 2576 Added globally applicable flags to framing. 2578 Removed zlib-based header compression mechanism. 2580 Updated references. 2582 Clarified stream identifier reuse. 2584 Removed CREDENTIALS frame and associated mechanisms. 2586 Added advice against naive implementation of flow control. 2588 Added session header section. 2590 Restructured frame header. Removed distinction between data and 2591 control frames. 2593 Altered flow control properties to include session-level limits. 2595 Added note on cacheability of pushed resources and multiple tenant 2596 servers. 2598 Changed protocol label form based on discussions. 2600 A.6. Since draft-ietf-httpbis-http2-00 2602 Changed title throughout. 2604 Removed section on Incompatibilities with SPDY draft#2. 2606 Changed INTERNAL_ERROR on GOAWAY to have a value of 2 . 2609 Replaced abstract and introduction. 2611 Added section on starting HTTP/2.0, including upgrade mechanism. 2613 Removed unused references. 2615 Added flow control principles (Section 5.2.1) based on . 2618 A.7. Since draft-mbelshe-httpbis-spdy-00 2620 Adopted as base for draft-ietf-httpbis-http2. 2622 Updated authors/editors list. 2624 Added status note. 2626 Authors' Addresses 2628 Mike Belshe 2629 Twist 2631 EMail: mbelshe@chromium.org 2633 Roberto Peon 2634 Google, Inc 2636 EMail: fenix@google.com 2638 Martin Thomson (editor) 2639 Microsoft 2640 3210 Porter Drive 2641 Palo Alto 94304 2642 US 2644 EMail: martin.thomson@skype.net 2646 Alexey Melnikov (editor) 2647 Isode Ltd 2648 5 Castle Business Village 2649 36 Station Road 2650 Hampton, Middlesex TW12 2BX 2651 UK 2653 EMail: Alexey.Melnikov@isode.com