idnits 2.17.1
draft-ietf-httpbis-http2-05.txt:
Checking boilerplate required by RFC 5378 and the IETF Trust (see
https://trustee.ietf.org/license-info):
----------------------------------------------------------------------------
No issues found here.
Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt:
----------------------------------------------------------------------------
No issues found here.
Checking nits according to https://www.ietf.org/id-info/checklist :
----------------------------------------------------------------------------
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 13, 2013) is 3910 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-00
== 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 14, 2014 Google, Inc
6 M. Thomson, Ed.
7 Microsoft
8 A. Melnikov, Ed.
9 Isode Ltd
10 August 13, 2013
12 Hypertext Transfer Protocol version 2.0
13 draft-ietf-httpbis-http2-05
15 Abstract
17 This specification describes an optimized expression of the syntax of
18 the Hypertext Transfer Protocol (HTTP). The HTTP/2.0 encapsulation
19 enables more efficient use of network resources and reduced
20 perception of latency by allowing header field compression and
21 multiple concurrent messages on the same connection. It also
22 introduces unsolicited push of representations from servers to
23 clients.
25 This document is an alternative to, but does not obsolete the
26 HTTP/1.1 message format or protocol. HTTP's existing semantics
27 remain unchanged.
29 Editorial Note (To be removed by RFC Editor)
31 Discussion of this draft takes place on the HTTPBIS working group
32 mailing list (ietf-http-wg@w3.org), which is archived at
33 .
35 Working Group information and related documents can be found at
36 (Wiki) and
37 (source code and issues
38 tracker).
40 The changes in this draft are summarized in Appendix A.1.
42 Status of This Memo
44 This Internet-Draft is submitted in full conformance with the
45 provisions of BCP 78 and BCP 79.
47 Internet-Drafts are working documents of the Internet Engineering
48 Task Force (IETF). Note that other groups may also distribute
49 working documents as Internet-Drafts. The list of current Internet-
50 Drafts is at http://datatracker.ietf.org/drafts/current/.
52 Internet-Drafts are draft documents valid for a maximum of six months
53 and may be updated, replaced, or obsoleted by other documents at any
54 time. It is inappropriate to use Internet-Drafts as reference
55 material or to cite them other than as "work in progress."
57 This Internet-Draft will expire on February 14, 2014.
59 Copyright Notice
61 Copyright (c) 2013 IETF Trust and the persons identified as the
62 document authors. All rights reserved.
64 This document is subject to BCP 78 and the IETF Trust's Legal
65 Provisions Relating to IETF Documents
66 (http://trustee.ietf.org/license-info) in effect on the date of
67 publication of this document. Please review these documents
68 carefully, as they describe your rights and restrictions with respect
69 to this document. Code Components extracted from this document must
70 include Simplified BSD License text as described in Section 4.e of
71 the Trust Legal Provisions and are provided without warranty as
72 described in the Simplified BSD License.
74 Table of Contents
76 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 5
77 1.1. Document Organization . . . . . . . . . . . . . . . . . . 5
78 1.2. Conventions and Terminology . . . . . . . . . . . . . . . 6
79 2. HTTP/2.0 Protocol Overview . . . . . . . . . . . . . . . . . . 6
80 2.1. HTTP Frames . . . . . . . . . . . . . . . . . . . . . . . 7
81 2.2. HTTP Multiplexing . . . . . . . . . . . . . . . . . . . . 7
82 2.3. HTTP Semantics . . . . . . . . . . . . . . . . . . . . . . 7
83 3. Starting HTTP/2.0 . . . . . . . . . . . . . . . . . . . . . . 7
84 3.1. HTTP/2.0 Version Identification . . . . . . . . . . . . . 8
85 3.2. Starting HTTP/2.0 for "http" URIs . . . . . . . . . . . . 8
86 3.2.1. HTTP2-Settings Header Field . . . . . . . . . . . . . 10
87 3.3. Starting HTTP/2.0 for "https" URIs . . . . . . . . . . . . 10
88 3.4. Starting HTTP/2.0 with Prior Knowledge . . . . . . . . . . 10
89 3.5. Connection Header . . . . . . . . . . . . . . . . . . . . 11
90 4. HTTP Frames . . . . . . . . . . . . . . . . . . . . . . . . . 12
91 4.1. Frame Format . . . . . . . . . . . . . . . . . . . . . . . 12
92 4.2. Frame Size . . . . . . . . . . . . . . . . . . . . . . . . 13
93 4.3. Header Compression and Decompression . . . . . . . . . . . 13
94 5. Streams and Multiplexing . . . . . . . . . . . . . . . . . . . 14
95 5.1. Stream States . . . . . . . . . . . . . . . . . . . . . . 14
96 5.1.1. Stream Identifiers . . . . . . . . . . . . . . . . . . 18
97 5.1.2. Stream Concurrency . . . . . . . . . . . . . . . . . . 19
98 5.2. Flow Control . . . . . . . . . . . . . . . . . . . . . . . 19
99 5.2.1. Flow Control Principles . . . . . . . . . . . . . . . 19
100 5.2.2. Appropriate Use of Flow Control . . . . . . . . . . . 21
101 5.3. Stream priority . . . . . . . . . . . . . . . . . . . . . 21
102 5.4. Error Handling . . . . . . . . . . . . . . . . . . . . . . 22
103 5.4.1. Connection Error Handling . . . . . . . . . . . . . . 22
104 5.4.2. Stream Error Handling . . . . . . . . . . . . . . . . 22
105 5.4.3. Connection Termination . . . . . . . . . . . . . . . . 23
106 6. Frame Definitions . . . . . . . . . . . . . . . . . . . . . . 23
107 6.1. DATA . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
108 6.2. HEADERS . . . . . . . . . . . . . . . . . . . . . . . . . 24
109 6.3. PRIORITY . . . . . . . . . . . . . . . . . . . . . . . . . 25
110 6.4. RST_STREAM . . . . . . . . . . . . . . . . . . . . . . . . 26
111 6.5. SETTINGS . . . . . . . . . . . . . . . . . . . . . . . . . 27
112 6.5.1. Setting Format . . . . . . . . . . . . . . . . . . . . 27
113 6.5.2. Defined Settings . . . . . . . . . . . . . . . . . . . 28
114 6.6. PUSH_PROMISE . . . . . . . . . . . . . . . . . . . . . . . 28
115 6.7. PING . . . . . . . . . . . . . . . . . . . . . . . . . . . 30
116 6.8. GOAWAY . . . . . . . . . . . . . . . . . . . . . . . . . . 31
117 6.9. WINDOW_UPDATE . . . . . . . . . . . . . . . . . . . . . . 33
118 6.9.1. The Flow Control Window . . . . . . . . . . . . . . . 34
119 6.9.2. Initial Flow Control Window Size . . . . . . . . . . . 35
120 6.9.3. Reducing the Stream Window Size . . . . . . . . . . . 36
121 6.9.4. Ending Flow Control . . . . . . . . . . . . . . . . . 36
122 6.10. CONTINUATION . . . . . . . . . . . . . . . . . . . . . . . 36
123 7. Error Codes . . . . . . . . . . . . . . . . . . . . . . . . . 38
124 8. HTTP Message Exchanges . . . . . . . . . . . . . . . . . . . . 38
125 8.1. HTTP Request/Response Exchange . . . . . . . . . . . . . . 39
126 8.1.1. Examples . . . . . . . . . . . . . . . . . . . . . . . 39
127 8.1.2. HTTP Header Fields . . . . . . . . . . . . . . . . . . 41
128 8.1.3. Request Reliability Mechanisms in HTTP/2.0 . . . . . . 43
129 8.2. Server Push . . . . . . . . . . . . . . . . . . . . . . . 43
130 8.2.1. Push Requests . . . . . . . . . . . . . . . . . . . . 44
131 8.2.2. Push Responses . . . . . . . . . . . . . . . . . . . . 45
132 9. Additional HTTP Requirements/Considerations . . . . . . . . . 46
133 9.1. Connection Management . . . . . . . . . . . . . . . . . . 46
134 9.2. Use of TLS Features . . . . . . . . . . . . . . . . . . . 46
135 9.3. Frame Size Limits for HTTP . . . . . . . . . . . . . . . . 47
136 9.4. GZip Content-Encoding . . . . . . . . . . . . . . . . . . 47
137 10. Security Considerations . . . . . . . . . . . . . . . . . . . 47
138 10.1. Server Authority and Same-Origin . . . . . . . . . . . . . 47
139 10.2. Cross-Protocol Attacks . . . . . . . . . . . . . . . . . . 47
140 10.3. Cacheability of Pushed Resources . . . . . . . . . . . . . 48
141 11. Privacy Considerations . . . . . . . . . . . . . . . . . . . . 48
142 12. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 48
143 12.1. Frame Type Registry . . . . . . . . . . . . . . . . . . . 49
144 12.2. Error Code Registry . . . . . . . . . . . . . . . . . . . 49
145 12.3. Settings Registry . . . . . . . . . . . . . . . . . . . . 50
146 12.4. HTTP2-Settings Header Field Registration . . . . . . . . . 51
147 13. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . 51
148 14. References . . . . . . . . . . . . . . . . . . . . . . . . . . 51
149 14.1. Normative References . . . . . . . . . . . . . . . . . . . 51
150 14.2. Informative References . . . . . . . . . . . . . . . . . . 53
151 Appendix A. Change Log (to be removed by RFC Editor before
152 publication) . . . . . . . . . . . . . . . . . . . . 53
153 A.1. Since draft-ietf-httpbis-http2-04 . . . . . . . . . . . . 53
154 A.2. Since draft-ietf-httpbis-http2-03 . . . . . . . . . . . . 54
155 A.3. Since draft-ietf-httpbis-http2-02 . . . . . . . . . . . . 54
156 A.4. Since draft-ietf-httpbis-http2-01 . . . . . . . . . . . . 54
157 A.5. Since draft-ietf-httpbis-http2-00 . . . . . . . . . . . . 55
158 A.6. Since draft-mbelshe-httpbis-spdy-00 . . . . . . . . . . . 55
160 1. Introduction
162 The Hypertext Transfer Protocol (HTTP) is a wildly successful
163 protocol. However, the HTTP/1.1 message format ([HTTP-p1], Section
164 3) is optimized for implementation simplicity and accessibility, not
165 application performance. As such it has several characteristics that
166 have a negative overall effect on application performance.
168 In particular, HTTP/1.0 only allows one request to be delivered at a
169 time on a given connection. HTTP/1.1 pipelining only partially
170 addressed request concurrency, and is not widely deployed.
171 Therefore, clients that need to make many requests (as is common on
172 the Web) typically use multiple connections to a server in order to
173 reduce perceived latency.
175 Furthermore, HTTP/1.1 header fields are often repetitive and verbose,
176 which, in addition to generating more or larger network packets, can
177 cause the small initial TCP congestion window to quickly fill. This
178 can result in excessive latency when multiple requests are made on a
179 single new TCP connection.
181 This document addresses these issues by defining an optimized mapping
182 of HTTP's semantics to an underlying connection. Specifically, it
183 allows interleaving of request and response messages on the same
184 connection and uses an efficient coding for HTTP header fields. It
185 also allows prioritization of requests, letting more important
186 requests complete more quickly, further improving perceived
187 performance.
189 The resulting protocol is designed to be more friendly to the
190 network, because fewer TCP connections can be used, in comparison to
191 HTTP/1.x. This means less competition with other flows, and longer-
192 lived connections, which in turn leads to better utilization of
193 available network capacity.
195 Finally, this encapsulation also enables more scalable processing of
196 messages through use of binary message framing.
198 1.1. Document Organization
200 The HTTP/2.0 Specification is split into three parts: starting
201 HTTP/2.0 (Section 3), which covers how a HTTP/2.0 connection is
202 initiated; a framing layer (Section 4), which multiplexes a single
203 TCP connection into independent frames of various types; and an HTTP
204 layer (Section 8), which specifies the mechanism for expressing HTTP
205 interactions using the framing layer. While some of the framing
206 layer concepts are isolated from HTTP, building a generic framing
207 layer has not been a goal. The framing layer is tailored to the
208 needs of the HTTP protocol and server push.
210 1.2. Conventions and Terminology
212 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
213 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
214 document are to be interpreted as described in RFC 2119 [RFC2119].
216 All numeric values are in network byte order. Values are unsigned
217 unless otherwise indicated. Literal values are provided in decimal
218 or hexadecimal as appropriate. Hexadecimal literals are prefixed
219 with "0x" to distinguish them from decimal literals.
221 The following terms are used:
223 client: The endpoint initiating the HTTP connection.
225 connection: A transport-level connection between two endpoints.
227 endpoint: Either the client or server of the connection.
229 frame: The smallest unit of communication within an HTTP/2.0
230 connection, consisting of a header and a variable-length sequence
231 of bytes structured according to the frame type.
233 peer: An endpoint. When discussing a particular endpoint, "peer"
234 refers to the endpoint that is remote to the primary subject of
235 discussion.
237 receiver: An endpoint that is receiving frames.
239 sender: An endpoint that is transmitting frames.
241 server: The endpoint which did not initiate the HTTP connection.
243 connection error: An error on the HTTP/2.0 connection.
245 stream: A bi-directional flow of frames across a virtual channel
246 within the HTTP/2.0 connection.
248 stream error: An error on the individual HTTP/2.0 stream.
250 2. HTTP/2.0 Protocol Overview
252 HTTP/2.0 provides an optimized transport for HTTP semantics.
254 An HTTP/2.0 connection is an application level protocol running on
255 top of a TCP connection ([RFC0793]). The client is the TCP
256 connection initiator.
258 This document describes the HTTP/2.0 protocol using a logical
259 structure that is formed of three parts: framing, streams, and
260 application mapping. This structure is provided primarily as an aid
261 to specification, implementations are free to diverge from this
262 structure as necessary.
264 2.1. HTTP Frames
266 HTTP/2.0 provides an efficient serialization of HTTP semantics. HTTP
267 requests and responses are encoded into length-prefixed frames (see
268 Section 4.1).
270 HTTP headers are compressed into a series of frames that contain
271 header block fragments (see Section 4.3).
273 2.2. HTTP Multiplexing
275 HTTP/2.0 provides the ability to multiplex multiple HTTP requests and
276 responses onto a single connection. Multiple requests or responses
277 can be sent concurrently on a connection using streams (Section 5).
278 In order to maintain independent streams, flow control and
279 prioritization are necessary.
281 2.3. HTTP Semantics
283 HTTP/2.0 defines how HTTP requests and responses are mapped to
284 streams (see Section 8.1) and introduces a new interaction model,
285 server push (Section 8.2).
287 3. Starting HTTP/2.0
289 HTTP/2.0 uses the same "http" and "https" URI schemes used by
290 HTTP/1.1. HTTP/2.0 shares the same default port numbers: 80 for
291 "http" URIs and 443 for "https" URIs. As a result, implementations
292 processing requests for target resource URIs like
293 "http://example.org/foo" or "https://example.com/bar" are required to
294 first discover whether the upstream server (the immediate peer to
295 which the client wishes to establish a connection) supports HTTP/2.0.
297 The means by which support for HTTP/2.0 is determined is different
298 for "http" and "https" URIs. Discovery for "http" URIs is described
299 in Section 3.2. Discovery for "https" URIs is described in
300 Section 3.3.
302 3.1. HTTP/2.0 Version Identification
304 The protocol defined in this document is identified using the string
305 "HTTP/2.0". This identification is used in the HTTP/1.1 Upgrade
306 header field, in the TLS application layer protocol negotiation
307 extension [TLSALPN] field, and other places where protocol
308 identification is required.
310 Negotiating "HTTP/2.0" implies the use of the transport, security,
311 framing and message semantics described in this document.
313 [[anchor6: Editor's Note: please remove the remainder of this section
314 prior to the publication of a final version of this document.]]
316 Only implementations of the final, published RFC can identify
317 themselves as "HTTP/2.0". Until such an RFC exists, implementations
318 MUST NOT identify themselves using "HTTP/2.0".
320 Examples and text throughout the rest of this document use "HTTP/2.0"
321 as a matter of editorial convenience only. Implementations of draft
322 versions MUST NOT identify using this string. The exception to this
323 rule is the string included in the connection header sent by clients
324 immediately after establishing an HTTP/2.0 connection (see
325 Section 3.5); this fixed length sequence of octets does not change.
327 Implementations of draft versions of the protocol MUST add the string
328 "-draft-" and the corresponding draft number to the identifier before
329 the separator ('/'). For example, draft-ietf-httpbis-http2-03 is
330 identified using the string "HTTP-draft-03/2.0".
332 Non-compatible experiments that are based on these draft versions
333 MUST instead replace the string "draft" with a different identifier.
334 For example, an experimental implementation of packet mood-based
335 encoding based on draft-ietf-httpbis-http2-07 might identify itself
336 as "HTTP-emo-07/2.0". Note that any label MUST conform to the
337 "token" syntax defined in Section 3.2.6 of [HTTP-p1]. Experimenters
338 are encouraged to coordinate their experiments on the
339 ietf-http-wg@w3.org mailing list.
341 3.2. Starting HTTP/2.0 for "http" URIs
343 A client that makes a request to an "http" URI without prior
344 knowledge about support for HTTP/2.0 uses the HTTP Upgrade mechanism
345 (Section 6.7 of [HTTP-p1]). The client makes an HTTP/1.1 request
346 that includes an Upgrade header field identifying HTTP/2.0. The
347 HTTP/1.1 request MUST include exactly one HTTP2-Settings
348 (Section 3.2.1) header field.
350 For example:
352 GET /default.htm HTTP/1.1
353 Host: server.example.com
354 Connection: Upgrade, HTTP2-Settings
355 Upgrade: HTTP/2.0
356 HTTP2-Settings:
358 Requests that contain a request entity body MUST be sent in their
359 entirety before the client can send HTTP/2.0 frames. This means that
360 a large request entity can block the use of the connection until it
361 is completely sent.
363 If concurrency of an initial request with subsequent requests is
364 important, a small request can be used to perform the upgrade to
365 HTTP/2.0, at the cost of an additional round trip.
367 A server that does not support HTTP/2.0 can respond to the request as
368 though the Upgrade header field were absent:
370 HTTP/1.1 200 OK
371 Content-length: 243
372 Content-type: text/html
374 ...
376 A server that supports HTTP/2.0 accepts the upgrade with a 101
377 (Switching Protocols) status code. After the empty line that
378 terminates the 101 response, the server can begin sending HTTP/2.0
379 frames. These frames MUST include a response to the request that
380 initiated the Upgrade.
382 HTTP/1.1 101 Switching Protocols
383 Connection: Upgrade
384 Upgrade: HTTP/2.0
386 [ HTTP/2.0 connection ...
388 The first HTTP/2.0 frame sent by the server is a SETTINGS frame
389 (Section 6.5). Upon receiving the 101 response, the client sends a
390 connection header (Section 3.5), which includes a SETTINGS frame.
392 The HTTP/1.1 request that is sent prior to upgrade is associated with
393 stream 1 and is assigned the highest possible priority. Stream 1 is
394 implicitly half closed from the client toward the server, since the
395 request is completed as an HTTP/1.1 request. After commencing the
396 HTTP/2.0 connection, stream 1 is used for the response.
398 3.2.1. HTTP2-Settings Header Field
400 A client that upgrades from HTTP/1.1 to HTTP/2.0 MUST include exactly
401 one "HTTP2-Settings" header field. The "HTTP2-Settings" header field
402 is a hop-by-hop header field that includes settings that govern the
403 HTTP/2.0 connection, provided in anticipation of the server accepting
404 the request to upgrade. A server MUST reject an attempt to upgrade
405 if this header is not present.
407 HTTP2-Settings = token68
409 The content of the "HTTP2-Settings" header field is the payload of a
410 SETTINGS frame (Section 6.5), encoded as a base64url string (that is,
411 the URL- and filename-safe Base64 encoding described in Section 5 of
412 [RFC4648], with any trailing '=' characters omitted). The ABNF
413 [RFC5234] production for "token68" is defined in Section 2.1 of
414 [HTTP-p7].
416 The client MUST include values for the following settings
417 (Section 6.5.1):
419 o SETTINGS_MAX_CONCURRENT_STREAMS
421 o SETTINGS_INITIAL_WINDOW_SIZE
423 As a hop-by-hop header field, the "Connection" header field MUST
424 include a value of "HTTP2-Settings" in addition to "Upgrade" when
425 upgrading to HTTP/2.0.
427 A server decodes and interprets these values as it would any other
428 SETTINGS frame. Providing these values in the Upgrade request
429 ensures that the protocol does not require default values for the
430 above settings, and gives a client an opportunity to provide other
431 settings prior to receiving any frames from the server.
433 3.3. Starting HTTP/2.0 for "https" URIs
435 A client that makes a request to an "https" URI without prior
436 knowledge about support for HTTP/2.0 uses TLS [TLS12] with the
437 application layer protocol negotiation extension [TLSALPN].
439 Once TLS negotiation is complete, both the client and the server send
440 a connection header (Section 3.5).
442 3.4. Starting HTTP/2.0 with Prior Knowledge
444 A client can learn that a particular server supports HTTP/2.0 by
445 other means. A client MAY immediately send HTTP/2.0 frames to a
446 server that is known to support HTTP/2.0, after the connection header
447 (Section 3.5). This only affects the resolution of "http" URIs;
448 servers supporting HTTP/2.0 are required to support protocol
449 negotiation in TLS [TLSALPN] for "https" URIs.
451 Prior support for HTTP/2.0 is not a strong signal that a given server
452 will support HTTP/2.0 for future connections. It is possible for
453 server configurations to change or for configurations to differ
454 between instances in clustered server. Interception proxies (a.k.a.
455 "transparent" proxies) are another source of variability.
457 3.5. Connection Header
459 Upon establishment of a TCP connection and determination that
460 HTTP/2.0 will be used by both peers, each endpoint MUST send a
461 connection header as a final confirmation and to establish the
462 initial settings for the HTTP/2.0 connection.
464 The client connection header is a sequence of 24 octets, which in hex
465 notation are:
467 505249202a20485454502f322e300d0a0d0a534d0d0a0d0a
469 (the string "PRI * HTTP/2.0\r\n\r\nSM\r\n\r\n") followed by a
470 SETTINGS frame (Section 6.5). The client sends the client connection
471 header immediately upon receipt of a 101 Switching Protocols response
472 (indicating a successful upgrade), or as the first application data
473 octets of a TLS connection. If starting an HTTP/2.0 connection with
474 prior knowledge of server support for the protocol, the client
475 connection header is sent upon connection establishment.
477 The client connection header is selected so that a large
478 proportion of HTTP/1.1 or HTTP/1.0 servers and intermediaries do
479 not attempt to process further frames. Note that this does not
480 address the concerns raised in [TALKING].
482 The server connection header consists of just a SETTINGS frame
483 (Section 6.5) that MUST be the first frame the server sends in the
484 HTTP/2.0 connection.
486 To avoid unnecessary latency, clients are permitted to send
487 additional frames to the server immediately after sending the client
488 connection header, without waiting to receive the server connection
489 header. It is important to note, however, that the server connection
490 header SETTINGS frame might include parameters that necessarily alter
491 how a client is expected to communicate with the server. Upon
492 receiving the SETTINGS frame, the client is expected to honor any
493 parameters established.
495 Clients and servers MUST terminate the TCP connection if either peer
496 does not begin with a valid connection header. A GOAWAY frame
497 (Section 6.8) MAY be omitted if it is clear that the peer is not
498 using HTTP/2.0.
500 4. HTTP Frames
502 Once the HTTP/2.0 connection is established, endpoints can begin
503 exchanging frames.
505 4.1. Frame Format
507 All frames begin with an 8-octet header followed by a payload of
508 between 0 and 65,535 octets.
510 0 1 2 3
511 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
512 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
513 | Length (16) | Type (8) | Flags (8) |
514 +-+-------------+---------------+-------------------------------+
515 |R| Stream Identifier (31) |
516 +-+-------------------------------------------------------------+
517 | Frame Payload (0...) ...
518 +---------------------------------------------------------------+
520 Frame Header
522 The fields of the frame header are defined as:
524 Length: The length of the frame payload expressed as an unsigned 16-
525 bit integer. The 8 octets of the frame header are not included in
526 this value.
528 Type: The 8-bit type of the frame. The frame type determines how
529 the remainder of the frame header and payload are interpreted.
530 Implementations MUST ignore frames of unsupported or unrecognized
531 types.
533 Flags: An 8-bit field reserved for frame-type specific boolean
534 flags.
536 Flags are assigned semantics specific to the indicated frame type.
537 Flags that have no defined semantics for a particular frame type
538 MUST be ignored, and MUST be left unset (0) when sending.
540 R: A reserved 1-bit field. The semantics of this bit are undefined
541 and the bit MUST remain unset (0) when sending and MUST be ignored
542 when receiving.
544 Stream Identifier: A 31-bit stream identifier (see Section 5.1.1).
545 A value 0 is reserved for frames that are associated with the
546 connection as a whole as opposed to an individual stream.
548 The structure and content of the frame payload is dependent entirely
549 on the frame type.
551 4.2. Frame Size
553 The maximum size of a frame payload varies by frame type and use.
554 The absolute maximum size is 65,535 octets. All implementations
555 SHOULD be capable of receiving and minimally processing frames up to
556 this size.
558 Certain frame types, such as PING (see Section 6.7), impose
559 additional limits on the amount of payload data allowed. Likewise,
560 additional size limits can be set by specific application uses (see
561 Section 9).
563 If a frame size exceeds any defined limit, or is too small to contain
564 mandatory frame data, the endpoint MUST send a FRAME_TOO_LARGE error.
565 Frame size errors in frames that affect connection-level state MUST
566 be treated as a connection error (Section 5.4.1).
568 4.3. Header Compression and Decompression
570 A header in HTTP/2.0 is a name-value pair with one or more associated
571 values. They are used within HTTP request and response messages as
572 well as server push operations (see Section 8.2).
574 Header sets are logical collections of zero or more header fields
575 arranged at the application layer. When transmitted over a
576 connection, the header set is serialized into a header block using
577 HTTP Header Compression [COMPRESSION]. The serialized header block
578 is then divided into one or more octet sequences, called header block
579 fragments, and transmitted within the payload of HEADERS
580 (Section 6.2), PUSH_PROMISE (Section 6.6) or CONTINUATION
581 (Section 6.10) frames. The receiving endpoint reassembles the header
582 block by concatenating the individual fragments, then decompresses
583 the block to reconstruct the header set.
585 Header block fragments can only be sent as the payload of HEADERS,
586 PUSH_PROMISE or CONTINUATION frames.
588 A compressed and encoded header block is transmitted in a HEADERS or
589 PUSH_PROMISE frame, followed by zero or more CONTINUATION frames. If
590 the number of octets in the block is greater than the space remaining
591 in the frame, the block is divided into multiple fragments, which are
592 then transmitted in multiple frames.
594 Header blocks MUST be transmitted as a contiguous sequence of frames,
595 with no interleaved frames of any other type, or from any other
596 stream. The last frame in a sequence of HEADERS/CONTINUATION frames
597 MUST have the END_HEADERS flag set. The last frame in a sequence of
598 PUSH_PROMISE/CONTINUATION frames MUST have the END_PUSH_PROMISE/
599 END_HEADERS flag set (respectively).
601 HEADERS, PUSH_PROMISE and CONTINUATION frames carry data that can
602 modify the compression context maintained by a receiver. An endpoint
603 receiving HEADERS, PUSH_PROMISE or CONTINUATION frames MUST
604 reassemble header blocks and perform decompression even if the frames
605 are to be discarded, which is likely to occur after a stream is
606 reset. A receiver MUST terminate the connection with a connection
607 error (Section 5.4.1) of type COMPRESSION_ERROR, if it does not
608 decompress a header block.
610 5. Streams and Multiplexing
612 A "stream" is an independent, bi-directional sequence of HEADERS and
613 DATA frames exchanged between the client and server within an
614 HTTP/2.0 connection. Streams have several important characteristics:
616 o A single HTTP/2.0 connection can contain multiple concurrently
617 active streams, with either endpoint interleaving frames from
618 multiple streams.
620 o Streams can be established and used unilaterally or shared by
621 either the client or server.
623 o Streams can be closed by either endpoint.
625 o The order in which frames are sent within a stream is significant.
626 Recipients process frames in the order they are received.
628 o Streams are identified by an integer. Stream identifiers are
629 assigned to streams by the endpoint that initiates a stream.
631 5.1. Stream States
633 The lifecycle of a stream is shown in Figure 1.
635 +--------+
636 PP | | PP
637 ,--------| idle |--------.
638 / | | \
639 v +--------+ v
640 +----------+ | +----------+
641 | | | H | |
642 ,---| reserved | | | reserved |---.
643 | | (local) | v | (remote) | |
644 | +----------+ +--------+ +----------+ |
645 | | ES | | ES | |
646 | | H ,-------| open |-------. | H |
647 | | / | | \ | |
648 | v v +--------+ v v |
649 | +----------+ | +----------+ |
650 | | half | | | half | |
651 | | closed | | R | closed | |
652 | | (remote) | | | (local) | |
653 | +----------+ | +----------+ |
654 | | v | |
655 | | ES / R +--------+ ES / R | |
656 | `----------->| |<-----------' |
657 | R | closed | R |
658 `-------------------->| |<--------------------'
659 +--------+
661 Figure 1: Stream States
663 Both endpoints have a subjective view of the state of a stream that
664 could be different when frames are in transit. Endpoints do not
665 coordinate the creation of streams, they are created unilaterally by
666 either endpoint. The negative consequences of a mismatch in states
667 are limited to the "closed" state after sending RST_STREAM, where
668 frames might be received for some time after closing.
670 Streams have the following states:
672 idle:
673 All streams start in the "idle" state. In this state, no frames
674 have been exchanged.
676 The following transitions are valid from this state:
678 * Sending or receiving a HEADERS frame causes the stream to
679 become "open". The stream identifier is selected as described
680 in Section 5.1.1.
682 * Sending a PUSH_PROMISE frame marks the associated stream for
683 later use. The stream state for the reserved stream
684 transitions to "reserved (local)".
686 * Receiving a PUSH_PROMISE frame marks the associated stream as
687 reserved by the remote peer. The state of the stream becomes
688 "reserved (remote)".
690 reserved (local):
691 A stream in the "reserved (local)" state is one that has been
692 promised by sending a PUSH_PROMISE frame. A PUSH_PROMISE frame
693 reserves an idle stream by associating the stream with an open
694 stream that was initiated by the remote peer (see Section 8.2).
696 In this state, only the following transitions are possible:
698 * The endpoint can send a HEADERS frame. This causes the stream
699 to open in a "half closed (remote)" state.
701 * Either endpoint can send a RST_STREAM frame to cause the stream
702 to become "closed". This also releases the stream reservation.
704 An endpoint MUST NOT send any other type of frame in this state.
705 Receiving any frame other than RST_STREAM or PRIORITY MUST be
706 treated as a connection error (Section 5.4.1) of type
707 PROTOCOL_ERROR.
709 reserved (remote):
710 A stream in the "reserved (remote)" state has been reserved by a
711 remote peer.
713 In this state, only the following transitions are possible:
715 * Receiving a HEADERS frame causes the stream to transition to
716 "half closed (local)".
718 * Either endpoint can send a RST_STREAM frame to cause the stream
719 to become "closed". This also releases the stream reservation.
721 Receiving any other type of frame MUST be treated as a stream
722 error (Section 5.4.2) of type PROTOCOL_ERROR. An endpoint MAY
723 send RST_STREAM or PRIORITY frames in this state to cancel or
724 reprioritize the reserved stream.
726 open:
727 The "open" state is where both peers can send frames of any type.
728 In this state, sending peers observe advertised stream level flow
729 control limits (Section 5.2).
731 From this state either endpoint can send a frame with a END_STREAM
732 flag set, which causes the stream to transition into one of the
733 "half closed" states: an endpoint sending a END_STREAM flag causes
734 the stream state to become "half closed (local)"; an endpoint
735 receiving a END_STREAM flag causes the stream state to become
736 "half closed (remote)".
738 Either endpoint can send a RST_STREAM frame from this state,
739 causing it to transition immediately to "closed".
741 half closed (local):
742 A stream that is "half closed (local)" cannot be used for sending
743 frames.
745 A stream transitions from this state to "closed" when a frame that
746 contains a END_STREAM flag is received, or when either peer sends
747 a RST_STREAM frame.
749 A receiver can ignore WINDOW_UPDATE or PRIORITY frames in this
750 state. These frame types might arrive for a short period after a
751 frame bearing the END_STREAM flag is sent.
753 half closed (remote):
754 A stream that is "half closed (remote)" is no longer being used by
755 the peer to send frames. In this state, an endpoint is no longer
756 obligated to maintain a receiver flow control window if it
757 performs flow control.
759 If an endpoint receives additional frames for a stream that is in
760 this state it MUST respond with a stream error (Section 5.4.2) of
761 type STREAM_CLOSED.
763 A stream can transition from this state to "closed" by sending a
764 frame that contains a END_STREAM flag, or when either peer sends a
765 RST_STREAM frame.
767 closed:
768 The "closed" state is the terminal state.
770 An endpoint MUST NOT send frames on a closed stream. An endpoint
771 that receives a frame after receiving a RST_STREAM or a frame
772 containing a END_STREAM flag on that stream MUST treat that as a
773 stream error (Section 5.4.2) of type STREAM_CLOSED.
775 WINDOW_UPDATE or PRIORITY frames can be received in this state for
776 a short period after a a frame containing an END_STREAM flag is
777 sent. Until the remote peer receives and processes the frame
778 bearing the END_STREAM flag, it might send either frame type.
780 Endpoints MUST ignore WINDOW_UPDATE frames received in this state,
781 though endpoints MAY choose to treat WINDOW_UPDATE frames that
782 arrive a significant time after sending END_STREAM as a connection
783 error (Section 5.4.1) of type PROTOCOL_ERROR.
785 If this state is reached as a result of sending a RST_STREAM
786 frame, the peer that receives the RST_STREAM might have already
787 sent - or enqueued for sending - frames on the stream that cannot
788 be withdrawn. An endpoint MUST ignore frames that it receives on
789 closed streams after it has sent a RST_STREAM frame. An endpoint
790 MAY choose to limit the period over which it ignores frames and
791 treat frames that arrive after this time as being in error.
793 Flow controlled frames (i.e., DATA) received after sending
794 RST_STREAM are counted toward the connection flow control window.
795 Even though these frames might be ignored, because they are sent
796 before the sender receives the RST_STREAM, the sender will
797 consider the frames to count against the flow control window.
799 An endpoint might receive a PUSH_PROMISE or a CONTINUATION frame
800 after it sends RST_STREAM. PUSH_PROMISE causes a stream to become
801 "reserved". If promised streams are not desired, a RST_STREAM can
802 be used to close any of those streams.
804 In the absence of more specific guidance elsewhere in this document,
805 implementations SHOULD treat the receipt of a message that is not
806 expressly permitted in the description of a state as a connection
807 error (Section 5.4.1) of type PROTOCOL_ERROR.
809 5.1.1. Stream Identifiers
811 Streams are identified with an unsigned 31-bit integer. Streams
812 initiated by a client MUST use odd-numbered stream identifiers; those
813 initiated by the server MUST use even-numbered stream identifiers. A
814 stream identifier of zero (0x0) is used for connection control
815 message; the stream identifier zero MUST NOT be used to establish a
816 new stream. A stream identifier of one (0x1) is used to respond to
817 the HTTP/1.1 request which was specified during Upgrade (see
818 Section 3.2); the stream identifier one MUST NOT be used to establish
819 a new stream.
821 The identifier of a newly established stream MUST be numerically
822 greater than all streams that the initiating endpoint has opened or
823 reserved. This governs streams that are opened using a HEADERS frame
824 and streams that are reserved using PUSH_PROMISE. An endpoint that
825 receives an unexpected stream identifier MUST respond with a
826 connection error (Section 5.4.1) of type PROTOCOL_ERROR.
828 The first use of a new stream identifier implicitly closes all idle
829 streams that might have been initiated by that peer with a lower-
830 valued stream identifier.
832 Stream identifiers cannot be reused. Long-lived connections can
833 result in endpoint exhausting the available range of stream
834 identifiers. A client that is unable to establish a new stream
835 identifier can establish a new connection for new streams.
837 5.1.2. Stream Concurrency
839 A peer can limit the number of concurrently active streams using the
840 SETTINGS_MAX_CONCURRENT_STREAMS parameters within a SETTINGS frame.
841 The maximum concurrent streams setting is specific to each endpoint
842 and applies only to the peer that receives the setting. That is,
843 clients specify the maximum number of concurrent streams the server
844 can initiate, and servers specify the maximum number of concurrent
845 streams the client can initiate. Endpoints MUST NOT exceed the limit
846 set by their peer.
848 Streams that are in the "open" state, or either of the "half closed"
849 states count toward the maximum number of streams that an endpoint is
850 permitted to open. Streams in any of these three states count toward
851 the limit advertised in the SETTINGS_MAX_CONCURRENT_STREAMS setting
852 (see Section 6.5.2).
854 Streams in either of the "reserved" states do not count as open, even
855 if a small amount of application state is retained to ensure that the
856 promised stream can be successfully used.
858 5.2. Flow Control
860 Using streams for multiplexing introduces contention over use of the
861 TCP connection, resulting in blocked streams. A flow control scheme
862 ensures that streams on the same connection do not destructively
863 interfere with each other. Flow control is used for both individual
864 streams and for the connection as a whole.
866 HTTP/2.0 provides for flow control through use of the WINDOW_UPDATE
867 frame type.
869 5.2.1. Flow Control Principles
871 Experience with TCP congestion control has shown that algorithms can
872 evolve over time to become more sophisticated without requiring
873 protocol changes. TCP congestion control and its evolution is
874 clearly different from HTTP/2.0 flow control, though the evolution of
875 TCP congestion control algorithms shows that a similar approach could
876 be feasible for HTTP/2.0 flow control.
878 HTTP/2.0 stream flow control aims to allow for future improvements to
879 flow control algorithms without requiring protocol changes. Flow
880 control in HTTP/2.0 has the following characteristics:
882 1. Flow control is hop-by-hop, not end-to-end.
884 2. Flow control is based on window update frames. Receivers
885 advertise how many bytes they are prepared to receive on a stream
886 and for the entire connection. This is a credit-based scheme.
888 3. Flow control is directional with overall control provided by the
889 receiver. A receiver MAY choose to set any window size that it
890 desires for each stream and for the entire connection. A sender
891 MUST respect flow control limits imposed by a receiver. Clients,
892 servers and intermediaries all independently advertise their flow
893 control preferences as a receiver and abide by the flow control
894 limits set by their peer when sending.
896 4. The initial value for the flow control window is 65535 bytes for
897 both new streams and the overall connection.
899 5. The frame type determines whether flow control applies to a
900 frame. Of the frames specified in this document, only DATA
901 frames are subject to flow control; all other frame types do not
902 consume space in the advertised flow control window. This
903 ensures that important control frames are not blocked by flow
904 control.
906 6. Flow control can be disabled by a receiver. A receiver can
907 choose to disable both forms of flow control by sending the
908 SETTINGS_FLOW_CONTROL_OPTIONS setting. See Ending Flow Control
909 (Section 6.9.4) for more details.
911 7. HTTP/2.0 standardizes only the format of the WINDOW_UPDATE frame
912 (Section 6.9). This does not stipulate how a receiver decides
913 when to send this frame or the value that it sends. Nor does it
914 specify how a sender chooses to send packets. Implementations
915 are able to select any algorithm that suits their needs.
917 Implementations are also responsible for managing how requests and
918 responses are sent based on priority; choosing how to avoid head of
919 line blocking for requests; and managing the creation of new streams.
920 Algorithm choices for these could interact with any flow control
921 algorithm.
923 5.2.2. Appropriate Use of Flow Control
925 Flow control is defined to protect endpoints that are operating under
926 resource constraints. For example, a proxy needs to share memory
927 between many connections, and also might have a slow upstream
928 connection and a fast downstream one. Flow control addresses cases
929 where the receiver is unable process data on one stream, yet wants to
930 continue to process other streams in the same connection.
932 Deployments that do not require this capability SHOULD disable flow
933 control for data that is being received. Note that flow control
934 cannot be disabled for sending. Sending data is always subject to
935 the flow control window advertised by the receiver.
937 Deployments with constrained resources (for example, memory) MAY
938 employ flow control to limit the amount of memory a peer can consume.
939 Note, however, that this can lead to suboptimal use of available
940 network resources if flow control is enabled without knowledge of the
941 bandwidth-delay product (see [RFC1323]).
943 Even with full awareness of the current bandwidth-delay product,
944 implementation of flow control can be difficult. When using flow
945 control, the receive MUST read from the TCP receive buffer in a
946 timely fashion. Failure to do so could lead to a deadlock when
947 critical frames, such as WINDOW_UPDATE, are not available to
948 HTTP/2.0. However, flow control can ensure that constrained
949 resources are protected without any reduction in connection
950 utilization.
952 5.3. Stream priority
954 The endpoint establishing a new stream can assign a priority for the
955 stream. Priority is represented as an unsigned 31-bit integer. 0
956 represents the highest priority and 2^31-1 represents the lowest
957 priority.
959 The purpose of this value is to allow an endpoint to express the
960 relative priority of a stream. An endpoint can use this information
961 to preferentially allocate resources to a stream. Within HTTP/2.0,
962 priority can be used to select streams for transmitting frames when
963 there is limited capacity for sending. For instance, an endpoint
964 might enqueue frames for all concurrently active streams. As
965 transmission capacity becomes available, frames from higher priority
966 streams might be sent before lower priority streams.
968 Explicitly setting the priority for a stream does not guarantee any
969 particular processing or transmision order for the stream relative to
970 any other stream. Nor is there any mechanism provided by which the
971 initiator of a stream can force or require a receiving endpoint to
972 process concurrent streams in a particular order.
974 Unless explicitly specified in the HEADERS frame (Section 6.2) during
975 stream creation, the default stream priority is 2^30.
977 Pushed streams (Section 8.2) have a lower priority than their
978 associated stream. The promised stream inherits the priority value
979 of the associated stream plus one, up to a maximum of 2^31-1.
981 5.4. Error Handling
983 HTTP/2.0 framing permits two classes of error:
985 o An error condition that renders the entire connection unusable is
986 a connection error.
988 o An error in an individual stream is a stream error.
990 A list of error codes is included in Section 7.
992 5.4.1. Connection Error Handling
994 A connection error is any error which prevents further processing of
995 the framing layer or which corrupts any connection state.
997 An endpoint that encounters a connection error SHOULD first send a
998 GOAWAY frame (Section 6.8) with the stream identifier of the last
999 stream that it successfully received from its peer. The GOAWAY frame
1000 includes an error code that indicates why the connection is
1001 terminating. After sending the GOAWAY frame, the endpoint MUST close
1002 the TCP connection.
1004 It is possible that the GOAWAY will not be reliably received by the
1005 receiving endpoint. In the event of a connection error, GOAWAY only
1006 provides a best-effort attempt to communicate with the peer about why
1007 the connection is being terminated.
1009 An endpoint can end a connection at any time. In particular, an
1010 endpoint MAY choose to treat a stream error as a connection error.
1011 Endpoints SHOULD send a GOAWAY frame when ending a connection, as
1012 long as circumstances permit it.
1014 5.4.2. Stream Error Handling
1016 A stream error is an error related to a specific stream identifier
1017 that does not affect processing of other streams.
1019 An endpoint that detects a stream error sends a RST_STREAM frame
1020 (Section 6.4) that contains the stream identifier of the stream where
1021 the error occurred. The RST_STREAM frame includes an error code that
1022 indicates the type of error.
1024 A RST_STREAM is the last frame that an endpoint can send on a stream.
1025 The peer that sends the RST_STREAM frame MUST be prepared to receive
1026 any frames that were sent or enqueued for sending by the remote peer.
1027 These frames can be ignored, except where they modify connection
1028 state (such as the state maintained for header compression
1029 (Section 4.3)).
1031 Normally, an endpoint SHOULD NOT send more than one RST_STREAM frame
1032 for any stream. However, an endpoint MAY send additional RST_STREAM
1033 frames if it receives frames on a closed stream after more than a
1034 round trip time. This behavior is permitted to deal with misbehaving
1035 implementations.
1037 An endpoint MUST NOT send a RST_STREAM in response to an RST_STREAM
1038 frame, to avoid looping.
1040 5.4.3. Connection Termination
1042 If the TCP connection is torn down while streams remain in open or
1043 half closed states, then the endpoint MUST assume that the stream was
1044 abnormally interrupted and could be incomplete.
1046 6. Frame Definitions
1048 This specification defines a number of frame types, each identified
1049 by a unique 8-bit type code. Each frame type serves a distinct
1050 purpose either in the establishment and management of the connection
1051 as a whole, or of individual streams.
1053 The transmission of specific frame types can alter the state of a
1054 connection. If endpoints fail to maintain a synchronized view of the
1055 connection state, successful communication within the connection will
1056 no longer be possible. Therefore, it is important that endpoints
1057 have a shared comprehension of how the state is affected by the use
1058 any given frame. Accordingly, while it is expected that new frame
1059 types will be introduced by extensions to this protocol, only frames
1060 defined by this document are permitted to alter the connection state.
1062 6.1. DATA
1064 DATA frames (type=0x0) convey arbitrary, variable-length sequences of
1065 octets associated with a stream. One or more DATA frames are used,
1066 for instance, to carry HTTP request or response payloads.
1068 The DATA frame defines the following flags:
1070 END_STREAM (0x1): Bit 1 being set indicates that this frame is the
1071 last that the endpoint will send for the identified stream.
1072 Setting this flag causes the stream to enter a "half closed" or
1073 "closed" state (Section 5.1).
1075 RESERVED (0x2): Bit 2 is reserved for future use.
1077 DATA frames MUST be associated with a stream. If a DATA frame is
1078 received whose stream identifier field is 0x0, the recipient MUST
1079 respond with a connection error (Section 5.4.1) of type
1080 PROTOCOL_ERROR.
1082 DATA frames are subject to flow control and can only be sent when a
1083 stream is in the "open" or "half closed (remote)" states.
1085 6.2. HEADERS
1087 The HEADERS frame (type=0x1) carries name-value pairs. It is used to
1088 open a stream (Section 5.1). HEADERS frames can be sent on a stream
1089 in the "open" or "half closed (remote)" states.
1091 0 1 2 3
1092 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
1093 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
1094 |X| Priority (31) |
1095 +-+-------------------------------------------------------------+
1096 | Header Block Fragment (*) ...
1097 +---------------------------------------------------------------+
1099 HEADERS Frame Payload
1101 The HEADERS frame defines the following flags:
1103 END_STREAM (0x1): Bit 1 being set indicates that this frame is the
1104 last that the endpoint will send for the identified stream.
1105 Setting this flag causes the stream to enter a "half closed" state
1106 (Section 5.1).
1108 RESERVED (0x2): Bit 2 is reserved for future use.
1110 END_HEADERS (0x4): The END_HEADERS bit indicates that this frame
1111 ends the sequence of header block fragments necessary to provide a
1112 complete set of headers.
1114 The payload for a complete header block is provided by a sequence
1115 of that starts with a HEADERS frame, followed by zero or more
1116 CONTINUATION frames. The sequence is terminated by a frame with
1117 the END_HEADERS flag set. Once the sequence terminates, the
1118 payload of all HEADERS and CONTINUATION frames are concatenated
1119 and interpreted as a single block.
1121 A HEADERS frame without the END_HEADERS flag set MUST be followed
1122 by a CONTINUATION frame for the same stream. A receiver MUST
1123 treat the receipt of any other type of frame or a frame on a
1124 different stream as a connection error (Section 5.4.1) of type
1125 PROTOCOL_ERROR.
1127 PRIORITY (0x8): Bit 4 being set indicates that the first four octets
1128 of this frame contain a single reserved bit and a 31-bit priority;
1129 see Section 5.3. If this bit is not set, the four bytes do not
1130 appear and the frame only contains a header block fragment.
1132 The payload of a HEADERS frame contains a header block fragment
1133 (Section 4.3). A header block that does not fit within a HEADERS
1134 frame is continued in a CONTINUATION frame (Section 6.10).
1136 HEADERS frames MUST be associated with a stream. If a HEADERS frame
1137 is received whose stream identifier field is 0x0, the recipient MUST
1138 respond with a connection error (Section 5.4.1) of type
1139 PROTOCOL_ERROR.
1141 The HEADERS frame changes the connection state as described in
1142 Section 4.3.
1144 6.3. PRIORITY
1146 The PRIORITY frame (type=0x2) specifies the sender-advised priority
1147 of a stream. It can be sent at any time for an existing stream.
1148 This enables reprioritisation of existing streams.
1150 0 1 2 3
1151 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
1152 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
1153 |X| Priority (31) |
1154 +-+-------------------------------------------------------------+
1156 PRIORITY Frame Payload
1158 The payload of a PRIORITY frame contains a single reserved bit and a
1159 31-bit priority.
1161 The PRIORITY frame does not define any flags.
1163 The PRIORITY frame is associated with an existing stream. If a
1164 PRIORITY frame is received with a stream identifier of 0x0, the
1165 recipient MUST respond with a connection error (Section 5.4.1) of
1166 type PROTOCOL_ERROR.
1168 The PRIORITY frame can be sent on a stream in any of the "reserved
1169 (remote)", "open", "half-closed (local)", or "half closed (remote)"
1170 states, though it cannot be sent between consecutive frames that
1171 comprise a single header block (Section 4.3). Note that this frame
1172 could arrive after processing or frame sending has completed, which
1173 would cause it to have no effect. For a stream that is in the "half
1174 closed (remote)" state, this frame can only affect processing of the
1175 stream and not frame transmission.
1177 6.4. RST_STREAM
1179 The RST_STREAM frame (type=0x3) allows for abnormal termination of a
1180 stream. When sent by the initiator of a stream, it indicates that
1181 they wish to cancel the stream or that an error condition has
1182 occurred. When sent by the receiver of a stream, it indicates that
1183 either the receiver is rejecting the stream, requesting that the
1184 stream be cancelled or that an error condition has occurred.
1186 0 1 2 3
1187 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
1188 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
1189 | Error Code (32) |
1190 +---------------------------------------------------------------+
1192 RST_STREAM Frame Payload
1194 The RST_STREAM frame contains a single unsigned, 32-bit integer
1195 identifying the error code (Section 7). The error code indicates why
1196 the stream is being terminated.
1198 The RST_STREAM frame does not define any flags.
1200 The RST_STREAM frame fully terminates the referenced stream and
1201 causes it to enter the closed state. After receiving a RST_STREAM on
1202 a stream, the receiver MUST NOT send additional frames for that
1203 stream. However, after sending the RST_STREAM, the sending endpoint
1204 MUST be prepared to receive and process additional frames sent on the
1205 stream that might have been sent by the peer prior to the arrival of
1206 the RST_STREAM.
1208 RST_STREAM frames MUST be associated with a stream. If a RST_STREAM
1209 frame is received with a stream identifier of 0x0, the recipient MUST
1210 treat this as a connection error (Section 5.4.1) of type
1211 PROTOCOL_ERROR.
1213 RST_STREAM frames MUST NOT be sent for a stream in the "idle" state.
1214 If a RST_STREAM frame identifying an idle stream is received, the
1215 recipient MUST treat this as a connection error (Section 5.4.1) of
1216 type PROTOCOL_ERROR.
1218 6.5. SETTINGS
1220 The SETTINGS frame (type=0x4) conveys configuration parameters that
1221 affect how endpoints communicate. The parameters are either
1222 constraints on peer behavior or preferences.
1224 SETTINGS frames MUST be sent at the start of a connection, and MAY be
1225 sent at any other time by either endpoint over the lifetime of the
1226 connection.
1228 Implementations MUST support all of the settings defined by this
1229 specification and MAY support additional settings defined by
1230 extensions. Unsupported or unrecognized settings MUST be ignored.
1231 New settings MUST NOT be defined or implemented in a way that
1232 requires endpoints to understand them in order to communicate
1233 successfully.
1235 Each setting in a SETTINGS frame replaces the existing value for that
1236 setting. Settings are processed in the order in which they appear,
1237 and a receiver of a SETTINGS frame does not need to maintain any
1238 state other than the current value of settings. Therefore, the value
1239 of a setting is the last value that is seen by a receiver. This
1240 permits the inclusion of the same settings multiple times in the same
1241 SETTINGS frame, though doing so does nothing other than waste
1242 connection capacity.
1244 The SETTINGS frame does not define any flags.
1246 SETTINGS frames always apply to a connection, never a single stream.
1247 The stream identifier for a settings frame MUST be zero. If an
1248 endpoint receives a SETTINGS frame whose stream identifier field is
1249 anything other than 0x0, the endpoint MUST respond with a connection
1250 error (Section 5.4.1) of type PROTOCOL_ERROR.
1252 The SETTINGS frame affects connection state. A badly formed or
1253 incomplete SETTINGS frame MUST be treated as a connection error
1254 (Section 5.4.1) of type PROTOCOL_ERROR.
1256 6.5.1. Setting Format
1258 The payload of a SETTINGS frame consists of zero or more settings.
1259 Each setting consists of an 8-bit reserved field, an unsigned 24-bit
1260 setting identifier, and an unsigned 32-bit value.
1262 0 1 2 3
1263 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
1264 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
1265 | Reserved (8) | Setting Identifier (24) |
1266 +---------------+-----------------------------------------------+
1267 | Value (32) |
1268 +---------------------------------------------------------------+
1270 Setting Format
1272 6.5.2. Defined Settings
1274 The following settings are defined:
1276 SETTINGS_MAX_CONCURRENT_STREAMS (4): indicates the maximum number of
1277 concurrent streams that the sender will allow. This limit is
1278 directional: it applies to the number of streams that the sender
1279 permits the receiver to create. By default there is no limit. It
1280 is recommended that this value be no smaller than 100, so as to
1281 not unnecessarily limit parallelism.
1283 SETTINGS_INITIAL_WINDOW_SIZE (7): indicates the sender's initial
1284 window size (in bytes) for stream level flow control.
1286 This settings affects the window size of all streams, including
1287 existing streams, see Section 6.9.2.
1289 SETTINGS_FLOW_CONTROL_OPTIONS (10): indicates flow control options.
1290 The least significant bit (0x1) of the value is set to indicate
1291 that the sender has disabled all flow control. This bit cannot be
1292 cleared once set, see Section 6.9.4.
1294 All bits other than the least significant are reserved.
1296 6.6. PUSH_PROMISE
1298 The PUSH_PROMISE frame (type=0x5) is used to notify the peer endpoint
1299 in advance of streams the sender intends to initiate. The
1300 PUSH_PROMISE frame includes the unsigned 31-bit identifier of the
1301 stream the endpoint plans to create along with a minimal set of
1302 headers that provide additional context for the stream. Section 8.2
1303 contains a thorough description of the use of PUSH_PROMISE frames.
1305 0 1 2 3
1306 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
1307 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
1308 |X| Promised-Stream-ID (31) |
1309 +-+-------------------------------------------------------------+
1310 | Header Block Fragment (*) ...
1311 +---------------------------------------------------------------+
1313 PUSH_PROMISE Payload Format
1315 The payload of a PUSH_PROMISE includes a "Promised-Stream-ID". This
1316 unsigned 31-bit integer identifies the stream the endpoint intends to
1317 start sending frames for. The promised stream identifier MUST be a
1318 valid choice for the next stream sent by the sender (see new stream
1319 identifier (Section 5.1.1)).
1321 Following the "Promised-Stream-ID" is a header block fragment
1322 (Section 4.3).
1324 PUSH_PROMISE frames MUST be associated with an existing, peer-
1325 initiated stream. If the stream identifier field specifies the value
1326 0x0, a recipient MUST respond with a connection error (Section 5.4.1)
1327 of type PROTOCOL_ERROR.
1329 The PUSH_PROMISE frame defines the following flags:
1331 END_PUSH_PROMISE (0x1): The END_PUSH_PROMISE bit indicates that this
1332 frame ends the sequence of header block fragments necessary to
1333 provide a complete set of headers.
1335 The payload for a complete header block is provided by a sequence
1336 of PUSH_PROMISE frames, terminated by a PUSH_PROMISE frame with
1337 the END_PUSH_PROMISE flag set. Once the sequence terminates, the
1338 payload of all PUSH_PROMISE frames are concatenated and
1339 interpreted as a single block.
1341 A PUSH_PROMISE frame without the END_PUSH_PROMISE flag set MUST be
1342 followed by a PUSH_PROMISE frame for the same stream. A receiver
1343 MUST treat the receipt of any other type of frame or a frame on a
1344 different stream as a connection error (Section 5.4.1) of type
1345 PROTOCOL_ERROR.
1347 Promised streams are not required to be used in order promised. The
1348 PUSH_PROMISE only reserves stream identifiers for later use.
1350 Recipients of PUSH_PROMISE frames can choose to reject promised
1351 streams by returning a RST_STREAM referencing the promised stream
1352 identifier back to the sender of the PUSH_PROMISE.
1354 The PUSH_PROMISE frame modifies the connection state as defined in
1355 Section 4.3.
1357 A PUSH_PROMISE frame modifies the connection state in two ways. The
1358 inclusion of a header block (Section 4.3) potentially modifies the
1359 compression state. PUSH_PROMISE also reserves a stream for later
1360 use, causing the promised stream to enter the "reserved" state. A
1361 sender MUST NOT send a PUSH_PROMISE on a stream unless that stream is
1362 either "open" or "half closed (remote)"; the sender MUST ensure that
1363 the promised stream is a valid choice for a new stream identifier
1364 (Section 5.1.1) (that is, the promised stream MUST be in the "idle"
1365 state).
1367 Since PUSH_PROMISE reserves a stream, ignoring a PUSH_PROMISE frame
1368 causes the stream state to become indeterminate. A receiver MUST
1369 treat the receipt of a PUSH_PROMISE on a stream that is neither
1370 "open" nor "half-closed (local)" as a connection error
1371 (Section 5.4.1) of type PROTOCOL_ERROR. Similarly, a receiver MUST
1372 treat the receipt of a PUSH_PROMISE that promises an illegal stream
1373 identifier (Section 5.1.1) (that is, an identifier for a stream that
1374 is not currently in the "idle" state) as a connection error
1375 (Section 5.4.1) of type PROTOCOL_ERROR.
1377 6.7. PING
1379 The PING frame (type=0x6) is a mechanism for measuring a minimal
1380 round-trip time from the sender, as well as determining whether an
1381 idle connection is still functional. PING frames can be sent from
1382 any endpoint.
1384 0 1 2 3
1385 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
1386 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
1387 | |
1388 | Opaque Data (64) |
1389 | |
1390 +---------------------------------------------------------------+
1392 PING Payload Format
1394 In addition to the frame header, PING frames MUST contain 8 octets of
1395 data in the payload. A sender can include any value it chooses and
1396 use those bytes in any fashion.
1398 Receivers of a PING frame that does not include a PONG flag MUST send
1399 a PING frame with the PONG flag set in response, with an identical
1400 payload. PING responses SHOULD given higher priority than any other
1401 frame.
1403 The PING frame defines the following flags:
1405 PONG (0x1): Bit 1 being set indicates that this PING frame is a PING
1406 response. An endpoint MUST set this flag in PING responses. An
1407 endpoint MUST NOT respond to PING frames containing this flag.
1409 PING frames are not associated with any individual stream. If a PING
1410 frame is received with a stream identifier field value other than
1411 0x0, the recipient MUST respond with a connection error
1412 (Section 5.4.1) of type PROTOCOL_ERROR.
1414 Receipt of a PING frame with a length field value other than 8 MUST
1415 be treated as a connection error (Section 5.4.1) of type
1416 PROTOCOL_ERROR.
1418 6.8. GOAWAY
1420 The GOAWAY frame (type=0x7) informs the remote peer to stop creating
1421 streams on this connection. It can be sent from the client or the
1422 server. Once sent, the sender will ignore frames sent on new streams
1423 for the remainder of the connection. Receivers of a GOAWAY frame
1424 MUST NOT open additional streams on the connection, although a new
1425 connection can be established for new streams. The purpose of this
1426 frame is to allow an endpoint to gracefully stop accepting new
1427 streams (perhaps for a reboot or maintenance), while still finishing
1428 processing of previously established streams.
1430 There is an inherent race condition between an endpoint starting new
1431 streams and the remote sending a GOAWAY frame. To deal with this
1432 case, the GOAWAY contains the stream identifier of the last stream
1433 which was processed on the sending endpoint in this connection. If
1434 the receiver of the GOAWAY used streams that are newer than the
1435 indicated stream identifier, they were not processed by the sender
1436 and the receiver may treat the streams as though they had never been
1437 created at all (hence the receiver may want to re-create the streams
1438 later on a new connection).
1440 Endpoints SHOULD always send a GOAWAY frame before closing a
1441 connection so that the remote can know whether a stream has been
1442 partially processed or not. For example, if an HTTP client sends a
1443 POST at the same time that a server closes a connection, the client
1444 cannot know if the server started to process that POST request if the
1445 server does not send a GOAWAY frame to indicate where it stopped
1446 working. An endpoint might choose to close a connection without
1447 sending GOAWAY for misbehaving peers.
1449 After sending a GOAWAY frame, the sender can discard frames for new
1450 streams. However, any frames that alter connection state cannot be
1451 completely ignored. For instance, HEADERS, PUSH_PROMISE and
1452 CONTINUATION frames MUST be minimally processed to ensure a
1453 consistent compression state (see Section 4.3); similarly DATA frames
1454 MUST be counted toward the connection flow control window.
1456 0 1 2 3
1457 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
1458 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
1459 |X| Last-Stream-ID (31) |
1460 +-+-------------------------------------------------------------+
1461 | Error Code (32) |
1462 +---------------------------------------------------------------+
1463 | Additional Debug Data (*) |
1464 +---------------------------------------------------------------+
1466 GOAWAY Payload Format
1468 The GOAWAY frame does not define any flags.
1470 The GOAWAY frame applies to the connection, not a specific stream.
1471 The stream identifier MUST be zero.
1473 The last stream identifier in the GOAWAY frame contains the highest
1474 numbered stream identifier for which the sender of the GOAWAY frame
1475 has received frames on and might have taken some action on. All
1476 streams up to and including the identified stream might have been
1477 processed in some way. The last stream identifier is set to 0 if no
1478 streams were processed.
1480 Note: In this case, "processed" means that some data from the
1481 stream was passed to some higher layer of software that might have
1482 taken some action as a result.
1484 If a connection terminates without a GOAWAY frame, this value is
1485 effectively the highest stream identifier.
1487 On streams with lower or equal numbered identifiers that were not
1488 closed completely prior to the connection being closed, re-attempting
1489 requests, transactions, or any protocol activity is not possible
1490 (with the exception of idempotent actions like HTTP GET, PUT, or
1491 DELETE). Any protocol activity that uses higher numbered streams can
1492 be safely retried using a new connection.
1494 Activity on streams numbered lower or equal to the last stream
1495 identifier might still complete successfully. The sender of a GOAWAY
1496 frame might gracefully shut down a connection by sending a GOAWAY
1497 frame, maintaining the connection in an open state until all in-
1498 progress streams complete.
1500 The last stream ID MUST be 0 if no streams were acted upon.
1502 The GOAWAY frame also contains a 32-bit error code (Section 7) that
1503 contains the reason for closing the connection.
1505 Endpoints MAY append opaque data to the payload of any GOAWAY frame.
1506 Additional debug data is intended for diagnostic purposes only and
1507 carries no semantic value. Debug data MUST NOT be persistently
1508 stored, since it could contain sensitive information.
1510 6.9. WINDOW_UPDATE
1512 The WINDOW_UPDATE frame (type=0x9) is used to implement flow control.
1514 Flow control operates at two levels: on each individual stream and on
1515 the entire connection.
1517 Both types of flow control are hop by hop; that is, only between the
1518 two endpoints. Intermediaries do not forward WINDOW_UPDATE frames
1519 between dependent connections. However, throttling of data transfer
1520 by any receiver can indirectly cause the propagation of flow control
1521 information toward the original sender.
1523 Flow control only applies to frames that are identified as being
1524 subject to flow control. Of the frame types defined in this
1525 document, this includes only DATA frame. Frames that are exempt from
1526 flow control MUST be accepted and processed, unless the receiver is
1527 unable to assign resources to handling the frame. A receiver MAY
1528 respond with a stream error (Section 5.4.2) or connection error
1529 (Section 5.4.1) of type FLOW_CONTROL_ERROR if it is unable accept a
1530 frame.
1532 0 1 2 3
1533 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
1534 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
1535 |X| Window Size Increment (31) |
1536 +-+-------------------------------------------------------------+
1538 WINDOW_UPDATE Payload Format
1540 The payload of a WINDOW_UPDATE frame is one reserved bit, plus an
1541 unsigned 31-bit integer indicating the number of bytes that the
1542 sender can transmit in addition to the existing flow control window.
1543 The legal range for the increment to the flow control window is 1 to
1544 2^31 - 1 (0x7fffffff) bytes.
1546 The WINDOW_UPDATE frame does not define any flags.
1548 The WINDOW_UPDATE frame can be specific to a stream or to the entire
1549 connection. In the former case, the frame's stream identifier
1550 indicates the affected stream; in the latter, the value "0" indicates
1551 that the entire connection is the subject of the frame.
1553 WINDOW_UPDATE can be sent by a peer that has sent a frame bearing the
1554 END_STREAM flag. This means that a receiver could receive a
1555 WINDOW_UPDATE frame on a "half closed (remote)" or "closed" stream.
1556 A receiver MUST NOT treat this as an error, see Section 5.1.
1558 A receiver that receives a flow controlled frame MUST always account
1559 for its contribution against the connection flow control window,
1560 unless the receiver treats this as a connection error
1561 (Section 5.4.1). This is necessary even if the frame is in error.
1562 Since the sender counts the frame toward the flow control window, if
1563 the receiver does not, the flow control window at sender and receiver
1564 can become different.
1566 6.9.1. The Flow Control Window
1568 Flow control in HTTP/2.0 is implemented using a window kept by each
1569 sender on every stream. The flow control window is a simple integer
1570 value that indicates how many bytes of data the sender is permitted
1571 to transmit; as such, its size is a measure of the buffering
1572 capability of the receiver.
1574 Two flow control windows are applicable: the stream flow control
1575 window and the connection flow control window. The sender MUST NOT
1576 send a flow controlled frame with a length that exceeds the space
1577 available in either of the flow control windows advertised by the
1578 receiver. Frames with zero length with the END_STREAM flag set (for
1579 example, an empty data frame) MAY be sent if there is no available
1580 space in either flow control window.
1582 For flow control calculations, the 8 byte frame header is not
1583 counted.
1585 After sending a flow controlled frame, the sender reduces the space
1586 available in both windows by the length of the transmitted frame.
1588 The receiver of a frame sends a WINDOW_UPDATE frame as it consumes
1589 data and frees up space in flow control windows. Separate
1590 WINDOW_UPDATE frames are sent for the stream and connection level
1591 flow control windows.
1593 A sender that receives a WINDOW_UPDATE frame updates the
1594 corresponding window by the amount specified in the frame.
1596 A sender MUST NOT allow a flow control window to exceed 2^31 - 1
1597 bytes. If a sender receives a WINDOW_UPDATE that causes a flow
1598 control window to exceed this maximum it MUST terminate either the
1599 stream or the connection, as appropriate. For streams, the sender
1600 sends a RST_STREAM with the error code of FLOW_CONTROL_ERROR code;
1601 for the connection, a GOAWAY frame with a FLOW_CONTROL_ERROR code.
1603 Flow controlled frames from the sender and WINDOW_UPDATE frames from
1604 the receiver are completely asynchronous with respect to each other.
1605 This property allows a receiver to aggressively update the window
1606 size kept by the sender to prevent streams from stalling.
1608 6.9.2. Initial Flow Control Window Size
1610 When a HTTP/2.0 connection is first established, new streams are
1611 created with an initial flow control window size of 65535 bytes. The
1612 connection flow control window is 65535 bytes. Both endpoints can
1613 adjust the initial window size for new streams by including a value
1614 for SETTINGS_INITIAL_WINDOW_SIZE in the SETTINGS frame that forms
1615 part of the connection header.
1617 Prior to receiving a SETTINGS frame that sets a value for
1618 SETTINGS_INITIAL_WINDOW_SIZE, an endpoint can only use the default
1619 initial window size when sending flow controlled frames. Similarly,
1620 the connection flow control window is set to the default initial
1621 window size until a WINDOW_UPDATE frame is received.
1623 A SETTINGS frame can alter the initial flow control window size for
1624 all current streams. When the value of SETTINGS_INITIAL_WINDOW_SIZE
1625 changes, a receiver MUST adjust the size of all stream flow control
1626 windows that it maintains by the difference between the new value and
1627 the old value. A SETTINGS frame cannot alter the connection flow
1628 control window.
1630 A change to SETTINGS_INITIAL_WINDOW_SIZE could cause the available
1631 space in a flow control window to become negative. A sender MUST
1632 track the negative flow control window, and MUST NOT send new flow
1633 controlled frames until it receives WINDOW_UPDATE frames that cause
1634 the flow control window to become positive.
1636 For example, if the client sends 60KB immediately on connection
1637 establishment, and the server sets the initial window size to be
1638 16KB, the client will recalculate the available flow control window
1639 to be -44KB on receipt of the SETTINGS frame. The client retains a
1640 negative flow control window until WINDOW_UPDATE frames restore the
1641 window to being positive, after which the client can resume sending.
1643 6.9.3. Reducing the Stream Window Size
1645 A receiver that wishes to use a smaller flow control window than the
1646 current size can send a new SETTINGS frame. However, the receiver
1647 MUST be prepared to receive data that exceeds this window size, since
1648 the sender might send data that exceeds the lower limit prior to
1649 processing the SETTINGS frame.
1651 A receiver has two options for handling streams that exceed flow
1652 control limits:
1654 1. The receiver can immediately send RST_STREAM with
1655 FLOW_CONTROL_ERROR error code for the affected streams.
1657 2. The receiver can accept the streams and tolerate the resulting
1658 head of line blocking, sending WINDOW_UPDATE frames as it
1659 consumes data.
1661 If a receiver decides to accept streams, both sides MUST recompute
1662 the available flow control window based on the initial window size
1663 sent in the SETTINGS.
1665 6.9.4. Ending Flow Control
1667 After a receiver reads in a frame that marks the end of a stream (for
1668 example, a data stream with a END_STREAM flag set), it MUST cease
1669 transmission of WINDOW_UPDATE frames for that stream. A sender is
1670 not obligated to maintain the available flow control window for
1671 streams that it is no longer sending on.
1673 Flow control can be disabled the entire connection using the
1674 SETTINGS_FLOW_CONTROL_OPTIONS setting. This setting ends all forms
1675 of flow control. An implementation that does not wish to perform
1676 flow control can use this in the initial SETTINGS exchange.
1678 Flow control cannot be enabled again once disabled. Any attempt to
1679 re-enable flow control - by sending a WINDOW_UPDATE or by clearing
1680 the bits on the SETTINGS_FLOW_CONTROL_OPTIONS setting - MUST be
1681 rejected with a FLOW_CONTROL_ERROR error code.
1683 6.10. CONTINUATION
1685 The CONTINUATION frame (type=0xA) is used to continue a sequence of
1686 header block fragments (Section 4.3). Any number of CONTINUATION
1687 frames can be sent on an existing stream, as long as the preceding
1688 frame on the same stream is one of HEADERS, PUSH_PROMISE or
1689 CONTINUATION.
1691 0 1 2 3
1692 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
1693 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
1694 | Header Block Fragment (*) ...
1695 +---------------------------------------------------------------+
1697 CONTINUATION Frame Payload
1699 The CONTINUATION frame defines the following flags:
1701 END_STREAM (0x1): Bit 1 being set indicates that this frame is the
1702 last that the endpoint will send for the identified stream.
1703 Setting this flag causes the stream to enter a "half closed" or
1704 "closed" state (Section 5.1).
1706 END_HEADERS (0x2): The END_HEADERS bit indicates that this frame
1707 ends the sequence of header block fragments necessary to provide a
1708 complete set of headers.
1710 The payload for a complete header block is provided by a sequence
1711 that starts with a HEADERS or PUSH_PROMISE frame and zero or more
1712 CONTINUATION frames, terminated by a HEADERS, PUSH_PROMISE, or
1713 CONTINUATION frame with the END_HEADERS flag set. Once the
1714 sequence terminates, the payload of all frames in the sequence are
1715 concatenated and interpreted as a single block.
1717 A HEADERS, PUSH_PROMISE, or CONTINUATION frame without the
1718 END_HEADERS flag set MUST be followed by a CONTINUATION frame for
1719 the same stream. A receiver MUST treat the receipt of any other
1720 type of frame or a frame on a different stream as a connection
1721 error (Section 5.4.1) of type PROTOCOL_ERROR.
1723 The payload of a CONTINUATION frame contains a header block fragment
1724 (Section 4.3).
1726 The CONTINUATION frame changes the connection state as defined in
1727 Section 4.3.
1729 CONTINUATION frames MUST be associated with a stream. If a
1730 CONTINUATION frame is received whose stream identifier field is 0x0,
1731 the recipient MUST respond with a connection error (Section 5.4.1) of
1732 type PROTOCOL_ERROR.
1734 header block fragments (Section 4.3). A CONTINUATION frame MUST be
1735 preceded by one of HEADERS, PUSH_PROMISE or CONTINUATION frame. A
1736 recipient that observes violation of this rule MUST respond with a
1737 connection error (Section 5.4.1) of type PROTOCOL_ERROR.
1739 7. Error Codes
1741 Error codes are 32-bit fields that are used in RST_STREAM and GOAWAY
1742 frames to convey the reasons for the stream or connection error.
1744 Error codes share a common code space. Some error codes only apply
1745 to specific conditions and have no defined semantics in certain frame
1746 types.
1748 The following error codes are defined:
1750 NO_ERROR (0): The associated condition is not as a result of an
1751 error. For example, a GOAWAY might include this code to indicate
1752 graceful shutdown of a connection.
1754 PROTOCOL_ERROR (1): The endpoint detected an unspecific protocol
1755 error. This error is for use when a more specific error code is
1756 not available.
1758 INTERNAL_ERROR (2): The endpoint encountered an unexpected internal
1759 error.
1761 FLOW_CONTROL_ERROR (3): The endpoint detected that its peer violated
1762 the flow control protocol.
1764 STREAM_CLOSED (5): The endpoint received a frame after a stream was
1765 half closed.
1767 FRAME_TOO_LARGE (6): The endpoint received a frame that was larger
1768 than the maximum size that it supports.
1770 REFUSED_STREAM (7): The endpoint refuses the stream prior to
1771 performing any application processing, see Section 8.1.3 for
1772 details.
1774 CANCEL (8): Used by the endpoint to indicate that the stream is no
1775 longer needed.
1777 COMPRESSION_ERROR (9): The endpoint is unable to maintain the
1778 compression context for the connection.
1780 8. HTTP Message Exchanges
1782 HTTP/2.0 is intended to be as compatible as possible with current
1783 web-based applications. This means that, from the perspective of the
1784 server business logic or application API, the features of HTTP are
1785 unchanged. To achieve this, all of the application request and
1786 response header semantics are preserved, although the syntax of
1787 conveying those semantics has changed. Thus, the rules from HTTP/1.1
1788 ([HTTP-p1], [HTTP-p2], [HTTP-p4], [HTTP-p5], [HTTP-p6], and
1789 [HTTP-p7]) apply with the changes in the sections below.
1791 8.1. HTTP Request/Response Exchange
1793 A client sends an HTTP request on a new stream, using a previously
1794 unused stream identifier (Section 5.1.1). A server sends an HTTP
1795 response on the same stream as the request.
1797 An HTTP request or response each consist of:
1799 1. a HEADERS frame;
1801 2. one contiguous sequence of zero or more CONTINUATION frames;
1803 3. zero or more DATA frames; and
1805 4. optionally, a contiguous sequence that starts with a HEADERS
1806 frame, followed by zero or more CONTINUATION frames.
1808 The last frame in the sequence bears an END_STREAM flag.
1810 Other frames MAY be interspersed with these frames, but those frames
1811 do not carry HTTP semantics. In particular, HEADERS frames (and any
1812 CONTINUATION frames that follow) other than the first and optional
1813 last frames in this sequence do not carry HTTP semantics.
1815 Trailing header fields are carried in a header block that also
1816 terminates the stream. That is, a sequence starting with a HEADERS
1817 frame, followed by zero or more CONTINUATION frames, that carries an
1818 END_STREAM flag on the last frame. Header blocks after the first
1819 that do not terminate the stream are not part of an HTTP request or
1820 response.
1822 An HTTP request/response exchange fully consumes a single stream. A
1823 request starts with the HEADERS frame that puts the stream into an
1824 "open" state and ends with a frame bearing END_STREAM, which causes
1825 the stream to become "half closed" for the client. A response starts
1826 with a HEADERS frame and ends with a frame bearing END_STREAM, which
1827 places the stream in the "closed" state.
1829 8.1.1. Examples
1831 For example, an HTTP GET request that includes request header fields
1832 and no body, is transmitted as a single contiguous sequence of
1833 HEADERS frames containing the serialized block of request header
1834 fields. The last HEADERS frame in the sequence has both the
1835 END_HEADERS and END_STREAM flag set:
1837 GET /resource HTTP/1.1 HEADERS
1838 Host: example.org ==> + END_STREAM
1839 Accept: image/jpeg + END_HEADERS
1840 :method = GET
1841 :scheme = https
1842 :host = example.org
1843 :path = /resource
1844 accept = image/jpeg
1846 Similarly, a response that includes only response header fields is
1847 transmitted as a sequence of HEADERS frames containing the serialized
1848 block of response header fields. The last HEADERS frame in the
1849 sequence has both the END_HEADERS and END_STREAM flag set:
1851 HTTP/1.1 204 No Content HEADERS
1852 Content-Length: 0 ===> + END_STREAM
1853 + END_HEADERS
1854 :status = 204
1855 content-length: 0
1857 An HTTP POST request that includes request header fields and payload
1858 data is transmitted as one HEADERS frame, followed by zero or more
1859 CONTINUATION frames, containing the request headers followed by one
1860 or more DATA frames, with the last CONTINUATION (or HEADERS) frame
1861 having the END_HEADERS flag set and the final DATA frame having the
1862 END_STREAM flag set:
1864 POST /resource HTTP/1.1 HEADERS
1865 Host: example.org ==> - END_STREAM
1866 Content-Type: image/jpeg + END_HEADERS
1867 Content-Length: 123 :method = POST
1868 :scheme = https
1869 {binary data} :host = example.org
1870 :path = /resource
1871 content-type = image/jpeg
1872 content-length = 123
1874 DATA
1875 + END_STREAM
1876 {binary data}
1878 A response that includes header fields and payload data is
1879 transmitted as a HEADERS frame, followed by zero or more CONTINUATION
1880 frames, followed by one or more DATA frames, with the last DATA frame
1881 in the sequence having the END_STREAM flag set:
1883 HTTP/1.1 200 OK HEADERS
1884 Content-Type: image/jpeg ==> - END_STREAM
1885 Content-Length: 123 + END_HEADERS
1886 :status = 200
1887 {binary data} content-type = image/jpeg
1888 content-length = 123
1890 DATA
1891 + END_STREAM
1892 {binary data}
1894 Trailing header fields are sent as a header block after both the
1895 request or response header block and all the DATA frames have been
1896 sent. The sequence of HEADERS/CONTINUATION frames that bears the
1897 trailers includes a terminal frame that has both END_HEADERS and
1898 END_STREAM flags set.
1900 HTTP/1.1 200 OK HEADERS
1901 Content-Type: image/jpeg ===> - END_STREAM
1902 Content-Length: 123 + END_HEADERS
1903 TE: trailers :status = 200
1904 123 content-type = image/jpeg
1905 {binary data} content-length = 123
1906 0
1907 Foo: bar DATA
1908 - END_STREAM
1909 {binary data}
1911 HEADERS
1912 + END_STREAM
1913 + END_HEADERS
1914 foo: bar
1916 8.1.2. HTTP Header Fields
1918 HTTP/2.0 request and response header fields carry information as a
1919 series of key-value pairs. This includes the target URI for the
1920 request, the status code for the response, as well as HTTP header
1921 fields.
1923 HTTP header field names are strings of ASCII characters that are
1924 compared in a case-insensitive fashion. Note that header compression
1925 could cause case information to be lost.
1927 The semantics of HTTP header fields are not altered by this
1928 specification, though header fields relating to connection management
1929 or request framing are no longer necessary. An HTTP/2.0 request MUST
1930 NOT include any of the following header fields: Connection, Host,
1931 Keep-Alive, Proxy-Connection, TE, Transfer-Encoding, and Upgrade. A
1932 server MUST treat the presence of any of these header fields as a
1933 stream error (Section 5.4.2) of type PROTOCOL_ERROR.
1935 8.1.2.1. Request Header Fields
1937 HTTP/2.0 defines a number of headers starting with a ':' character
1938 that carry information about the request target:
1940 o The ":method" header field includes the HTTP method ([HTTP-p2],
1941 Section 4).
1943 o The ":scheme" header field includes the scheme portion of the
1944 target URI ([RFC3986], Section 3.1).
1946 o The ":host" header field includes the authority portion of the
1947 target URI ([RFC3986], Section 3.2).
1949 o The ":path" header field includes the path and query parts of the
1950 target URI (the "path-absolute" production from [RFC3986] and
1951 optionally a '?' character followed by the "query" production, see
1952 [RFC3986], Section 3.3 and [RFC3986], Section 3.4). This field
1953 MUST NOT be empty; URIs that do not contain a path component MUST
1954 include a value of '/', unless the request is an OPTIONS request
1955 for '*', in which case the ":path" header field MUST include '*'.
1957 All HTTP/2.0 requests MUST include exactly one valid value for all of
1958 these header fields. An intermediary MUST ensure that requests that
1959 it forwards are correct. A server MUST treat the absence of any of
1960 these header fields, presence of multiple values, or an invalid value
1961 as a stream error (Section 5.4.2) of type PROTOCOL_ERROR.
1963 HTTP/2.0 does not define a way to carry the version identifier that
1964 is included in the HTTP/1.1 request line.
1966 All HTTP Requests that include a body can include a "content-length"
1967 header field. If a server receives a request where the sum of the
1968 DATA frame payload lengths does not equal the value of the
1969 "content-length" header field, the server MUST return a 400 (Bad
1970 Request) error.
1972 8.1.2.2. Response Header Fields
1974 A single ":status" header field is defined that carries the HTTP
1975 status code field (see [HTTP-p2], Section 6). This header field MUST
1976 be included in all responses. An intermediary MUST ensure that it
1977 does not forward responses with absent or invalid values. A client
1978 MUST treat the absence of the ":status"" header field, the presence
1979 of multiple values, or an invalid value as a stream error
1980 (Section 5.4.2) of type PROTOCOL_ERROR.
1982 HTTP/2.0 does not define a way to carry the version or reason phrase
1983 that is included in an HTTP/1.1 status line.
1985 8.1.3. Request Reliability Mechanisms in HTTP/2.0
1987 In HTTP/1.1, an HTTP client is unable to retry a non-idempotent
1988 request when an error occurs, because there is no means to determine
1989 the nature of the error. It is possible that some server processing
1990 occurred prior to the error, which could result in undesirable
1991 effects if the request were reattempted.
1993 HTTP/2.0 provides two mechanisms for providing a guarantee to a
1994 client that a request has not been processed:
1996 o The GOAWAY frame indicates the highest stream number that might
1997 have been processed. Requests on streams with higher numbers are
1998 therefore guaranteed to be safe to retry.
2000 o The REFUSED_STREAM error code can be included in a RST_STREAM
2001 frame to indicate that the stream is being closed prior to any
2002 processing having occurred. Any request that was sent on the
2003 reset stream can be safely retried.
2005 In both cases, clients MAY automatically retry all requests,
2006 including those with non-idempotent methods.
2008 A server MUST NOT indicate that a stream has not been processed
2009 unless it can guarantee that fact. If frames that are on a stream
2010 are passed to the application layer for any stream, then
2011 REFUSED_STREAM MUST NOT be used for that stream, and a GOAWAY frame
2012 MUST include a stream identifier that is greater than or equal to the
2013 given stream identifier.
2015 In addition to these mechanisms, the PING frame provides a way for a
2016 client to easily test a connection. Connections that remain idle can
2017 become broken as some middleboxes (for instance, network address
2018 translators, or load balancers) silently discard connection bindings.
2019 The PING frame allows a client to safely test whether a connection is
2020 still active without sending a request.
2022 8.2. Server Push
2024 HTTP/2.0 enables a server to pre-emptively send (or "push") multiple
2025 associated resources to a client in response to a single request.
2026 This feature becomes particularly helpful when the server knows the
2027 client will need to have those resources available in order to fully
2028 process the originally requested resource.
2030 Pushing additional resources is optional, and is negotiated only
2031 between individual endpoints. For instance, an intermediary could
2032 receive pushed resources from the server but is not required to
2033 forward those on to the client. How to make use of the pushed
2034 resources is up to that intermediary. Equally, the intermediary
2035 might choose to push additional resources to the client, without any
2036 action taken by the server.
2038 8.2.1. Push Requests
2040 Server push is semantically equivalent to a server responding to a
2041 request. The PUSH_PROMISE frame, or frames, sent by the server
2042 includes a header block that contains a complete set of request
2043 headers that the server attributes to the request. It is not
2044 possible to push a response to a request that includes a request
2045 body.
2047 Pushed resources are always associated with an explicit request from
2048 a client. The PUSH_PROMISE frames sent by the server are sent on the
2049 stream created for the original request. The PUSH_PROMISE frame
2050 includes a promised stream identifier, chosen from the stream
2051 identifiers available to the server (see Section 5.1.1).
2053 The header fields in PUSH_PROMISE and any subsequent CONTINUATION
2054 frames MUST be a valid and complete set of request headers
2055 (Section 8.1.2.1). The server MUST include a method in the ":method"
2056 header field that is safe (see [HTTP-p2], Section 4.2.1). If a
2057 client receives a PUSH_PROMISE that does not include a complete and
2058 valid set of header fields, or the ":method" header field identifies
2059 a method that is not safe, it MUST respond with a stream error
2060 (Section 5.4.2) of type PROTOCOL_ERROR.
2062 The server SHOULD send PUSH_PROMISE (Section 6.6) frames prior to
2063 sending any frames that reference the promised resources. This
2064 avoids a race where clients issue requests for resources prior to
2065 receiving any PUSH_PROMISE frames.
2067 For example, if the server receives a request for a document
2068 containing embedded links to multiple image files, and the server
2069 chooses to push those additional images to the client, sending push
2070 promises before the DATA frames that contain the image links ensure
2071 that the client is able to see the promises before discovering the
2072 resources. Similarly, if the server pushes resources referenced by
2073 the header block (for instance, in Link header fields), sending the
2074 push promises before sending the header block ensures that clients do
2075 not request those resources.
2077 PUSH_PROMISE frames MUST NOT be sent by the client. PUSH_PROMISE
2078 frames can be sent by the server on any stream that was opened by the
2079 client. They MUST be sent on a stream that is in either the "open"
2080 or "half closed (remote)" to the server. PUSH_PROMISE frames are
2081 interspersed with the frames that comprise a response, though they
2082 cannot be interspersed with HEADERS and CONTINUATION frames that
2083 comprise a single header block.
2085 8.2.2. Push Responses
2087 After sending the PUSH_PROMISE frame, the server can begin delivering
2088 the pushed resource as a response (Section 8.1.2.2) on a server-
2089 initiated stream that uses the promised stream identifier. The
2090 server uses this stream to transmit an HTTP response, using the same
2091 sequence of frames as defined in Section 8.1. This stream becomes
2092 "half closed" to the client (Section 5.1) after the initial HEADERS
2093 frame is sent.
2095 Once a client receives a PUSH_PROMISE frame and chooses to accept the
2096 pushed resource, the client SHOULD NOT issue any requests for the
2097 promised resource until after the promised stream has closed.
2099 If the client determines, for any reason, that it does not wish to
2100 receive the pushed resource from the server, or if the server takes
2101 too long to begin sending the promised resource, the client can send
2102 an RST_STREAM frame, using either the CANCEL or REFUSED_STREAM codes,
2103 and referencing the pushed stream's identifier.
2105 A client can use the SETTINGS_MAX_CONCURRENT_STREAMS setting to limit
2106 the number of resources that can be concurrently pushed by a server.
2107 Advertising a SETTINGS_MAX_CONCURRENT_STREAMS value of zero disables
2108 server push by preventing the server from creating the necessary
2109 streams. This does not prohibit a server from sending PUSH_PROMISE
2110 frames; clients need to reset any promised streams that are not
2111 wanted.
2113 Clients receiving a pushed response MUST validate that the server is
2114 authorized to push the resource using the same-origin policy
2115 ([RFC6454], Section 3). For example, a HTTP/2.0 connection to
2116 "example.com" is generally [[anchor15: Ed: weaselly use of
2117 "generally", needs better definition]] not permitted to push a
2118 response for "www.example.org".
2120 9. Additional HTTP Requirements/Considerations
2122 This section outlines attributes of the HTTP protocol that improve
2123 interoperability, reduce exposure to known security vulnerabilities,
2124 or reduce the potential for implementation variation.
2126 9.1. Connection Management
2128 HTTP/2.0 connections are persistent. For best performance, it is
2129 expected clients will not close connections until it is determined
2130 that no further communication with a server is necessary (for
2131 example, when a user navigates away from a particular web page), or
2132 until the server closes the connection.
2134 Clients SHOULD NOT open more than one HTTP/2.0 connection to a given
2135 origin ([RFC6454]) concurrently. A client can create additional
2136 connections as replacements, either to replace connections that are
2137 near to exhausting the available stream identifiers (Section 5.1.1),
2138 or to replace connections that have encountered errors
2139 (Section 5.4.1).
2141 Servers are encouraged to maintain open connections for as long as
2142 possible, but are permitted to terminate idle connections if
2143 necessary. When either endpoint chooses to close the transport-level
2144 TCP connection, the terminating endpoint MUST first send a GOAWAY
2145 (Section 6.8) frame so that both endpoints can reliably determine
2146 whether previously sent frames have been processed and gracefully
2147 complete or terminate any necessary remaining tasks.
2149 9.2. Use of TLS Features
2151 Implementations of HTTP/2.0 MUST support TLS 1.1 [TLS11]. [[anchor18:
2152 The working group intends to require at least the use of TLS 1.2
2153 [TLS12] prior to publication of this document; negotiating TLS 1.1 is
2154 permitted to enable the creation of interoperable implementations of
2155 early drafts.]]
2157 The TLS implementation MUST support the Server Name Indication (SNI)
2158 [TLS-EXT] extension to TLS. HTTP/2.0 clients MUST indicate the
2159 target domain name when negotiating TLS.
2161 A server that receives a TLS handshake that does not include either
2162 TLS 1.1 or SNI, MUST NOT negotiate HTTP/2.0. Removing HTTP/2.0
2163 protocols from consideration could result in the removal of all
2164 protocols from the set of protocols offered by the client. This
2165 causes protocol negotiation failure, as described in Section 3.2 of
2166 [TLSALPN].
2168 Implementations are encouraged not to negotiate TLS cipher suites
2169 with known vulnerabilities, such as [RC4].
2171 9.3. Frame Size Limits for HTTP
2173 Frames used for HTTP messages MUST NOT exceed 2^14-1 (16383) octets
2174 in length, not counting the 8 octet frame header. An endpoint MUST
2175 treat the receipt of a larger frame as a FRAME_TOO_LARGE error (see
2176 Section 4.2).
2178 9.4. GZip Content-Encoding
2180 Clients MUST support gzip compression for HTTP response bodies.
2181 Regardless of the value of the accept-encoding header field, a server
2182 MAY send responses with gzip or deflate encoding. A compressed
2183 response MUST still bear an appropriate content-encoding header
2184 field.
2186 10. Security Considerations
2188 10.1. Server Authority and Same-Origin
2190 This specification uses the same-origin policy ([RFC6454], Section 3)
2191 to determine whether an origin server is permitted to provide
2192 content.
2194 A server that is contacted using TLS is authenticated based on the
2195 certificate that it offers in the TLS handshake (see [RFC2818],
2196 Section 3). A server is considered authoritative for an "https"
2197 resource if it has been successfully authenticated for the domain
2198 part of the origin of the resource that it is providing.
2200 A server is considered authoritative for an "http" resource if the
2201 connection is established to a resolved IP address for the domain in
2202 the origin of the resource.
2204 A client MUST NOT use, in any way, resources provided by a server
2205 that is not authoritative for those resources.
2207 10.2. Cross-Protocol Attacks
2209 When using TLS, we believe that HTTP/2.0 introduces no new cross-
2210 protocol attacks. TLS encrypts the contents of all transmission
2211 (except the handshake itself), making it difficult for attackers to
2212 control the data which could be used in a cross-protocol attack.
2213 [[anchor23: Issue: This is no longer true]]
2215 10.3. Cacheability of Pushed Resources
2217 Pushed resources are responses without an explicit request; the
2218 request for a pushed resource is synthesized from the request that
2219 triggered the push, plus resource identification information provided
2220 by the server. Request header fields are necessary for HTTP cache
2221 control validations (such as the Vary header field) to work. For
2222 this reason, caches MUST inherit request header fields from the
2223 associated stream for the push. This includes the Cookie header
2224 field.
2226 Caching resources that are pushed is possible, based on the guidance
2227 provided by the origin server in the Cache-Control header field.
2228 However, this can cause issues if a single server hosts more than one
2229 tenant. For example, a server might offer multiple users each a
2230 small portion of its URI space.
2232 Where multiple tenants share space on the same server, that server
2233 MUST ensure that tenants are not able to push representations of
2234 resources that they do not have authority over. Failure to enforce
2235 this would allow a tenant to provide a representation that would be
2236 served out of cache, overriding the actual representation that the
2237 authoritative tenant provides.
2239 Pushed resources for which an origin server is not authoritative are
2240 never cached or used.
2242 11. Privacy Considerations
2244 HTTP/2.0 aims to keep connections open longer between clients and
2245 servers in order to reduce the latency when a user makes a request.
2246 The maintenance of these connections over time could be used to
2247 expose private information. For example, a user using a browser
2248 hours after the previous user stopped using that browser may be able
2249 to learn about what the previous user was doing. This is a problem
2250 with HTTP in its current form as well, however the short lived
2251 connections make it less of a risk.
2253 12. IANA Considerations
2255 This document establishes registries for frame types, error codes and
2256 settings. These new registries are entered in a new "Hypertext
2257 Transfer Protocol (HTTP) 2.0 Parameters" section.
2259 This document also registers the "HTTP2-Settings" header field for
2260 use in HTTP.
2262 12.1. Frame Type Registry
2264 This document establishes a registry for HTTP/2.0 frame types. The
2265 "HTTP/2.0 Frame Type" registry operates under the "IETF Review"
2266 policy [RFC5226].
2268 Frame types are an 8-bit value. When reviewing new frame type
2269 registrations, special attention is advised for any frame type-
2270 specific flags that are defined. Frame flags can interact with
2271 existing flags and could prevent the creation of globally applicable
2272 flags.
2274 Initial values for the "HTTP/2.0 Frame Type" registry are shown in
2275 Table 1.
2277 +--------+---------------+---------------------------+--------------+
2278 | Frame | Name | Flags | Section |
2279 | Type | | | |
2280 +--------+---------------+---------------------------+--------------+
2281 | 0 | DATA | END_STREAM(1) | Section 6.1 |
2282 | 1 | HEADERS | END_STREAM(1), | Section 6.2 |
2283 | | | END_HEADERS(4), | |
2284 | | | PRIORITY(8) | |
2285 | 2 | PRIORITY | - | Section 6.3 |
2286 | 3 | RST_STREAM | - | Section 6.4 |
2287 | 4 | SETTINGS | - | Section 6.5 |
2288 | 5 | PUSH_PROMISE | END_PUSH_PROMISE(1) | Section 6.6 |
2289 | 6 | PING | PONG(1) | Section 6.7 |
2290 | 7 | GOAWAY | - | Section 6.8 |
2291 | 9 | WINDOW_UPDATE | - | Section 6.9 |
2292 | 10 | CONTINUATION | END_STREAM(1), | Section 6.10 |
2293 | | | END_HEADERS(4) | |
2294 +--------+---------------+---------------------------+--------------+
2296 Table 1
2298 12.2. Error Code Registry
2300 This document establishes a registry for HTTP/2.0 error codes. The
2301 "HTTP/2.0 Error Code" registry manages a 32-bit space. The "HTTP/2.0
2302 Error Code" registry operates under the "Expert Review" policy
2303 [RFC5226].
2305 Registrations for error codes are required to include a description
2306 of the error code. An expert reviewer is advised to examine new
2307 registrations for possible duplication with existing error codes.
2308 Use of existing registrations is to be encouraged, but not mandated.
2310 New registrations are advised to provide the following information:
2312 Error Code: The 32-bit error code value.
2314 Name: A name for the error code. Specifying an error code name is
2315 optional.
2317 Description: A description of the conditions where the error code is
2318 applicable.
2320 Specification: An optional reference for a specification that
2321 defines the error code.
2323 An initial set of error code registrations can be found in Section 7.
2325 12.3. Settings Registry
2327 This document establishes a registry for HTTP/2.0 settings. The
2328 "HTTP/2.0 Settings" registry manages a 24-bit space. The "HTTP/2.0
2329 Settings" registry operates under the "Expert Review" policy
2330 [RFC5226].
2332 Registrations for settings are required to include a description of
2333 the setting. An expert reviewer is advised to examine new
2334 registrations for possible duplication with existing settings. Use
2335 of existing registrations is to be encouraged, but not mandated.
2337 New registrations are advised to provide the following information:
2339 Setting: The 24-bit setting value.
2341 Name: A name for the setting. Specifying a name is optional.
2343 Flags: Any setting-specific flags that apply, including their value
2344 and semantics.
2346 Description: A description of the setting. This might include the
2347 range of values, any applicable units and how to act upon a value
2348 when it is provided.
2350 Specification: An optional reference for a specification that
2351 defines the setting.
2353 An initial set of settings registrations can be found in
2354 Section 6.5.2.
2356 12.4. HTTP2-Settings Header Field Registration
2358 This section registers the "HTTP2-Settings" header field in the
2359 Permanent Message Header Field Registry [BCP90].
2361 Header field name: HTTP2-Settings
2363 Applicable protocol: http
2365 Status: standard
2367 Author/Change controller: IETF
2369 Specification document(s): Section 3.2.1 of this document
2371 Related information: This header field is only used by an HTTP/2.0
2372 client for Upgrade-based negotiation.
2374 13. Acknowledgements
2376 This document includes substantial input from the following
2377 individuals:
2379 o Adam Langley, Wan-Teh Chang, Jim Morrison, Mark Nottingham, Alyssa
2380 Wilk, Costin Manolache, William Chan, Vitaliy Lvin, Joe Chan, Adam
2381 Barth, Ryan Hamilton, Gavin Peters, Kent Alstad, Kevin Lindsay,
2382 Paul Amer, Fan Yang, Jonathan Leighton (SPDY contributors).
2384 o Gabriel Montenegro and Willy Tarreau (Upgrade mechanism)
2386 o William Chan, Salvatore Loreto, Osama Mazahir, Gabriel Montenegro,
2387 Jitu Padhye, Roberto Peon, Rob Trace (Flow control)
2389 o Mark Nottingham, Julian Reschke, James Snell, Jeff Pinner
2390 (Substantial editorial contributions)
2392 14. References
2394 14.1. Normative References
2396 [COMPRESSION] Ruellan, H. and R. Peon, "HTTP Header Compression",
2397 draft-ietf-httpbis-header-compression-00 (work in
2398 progress), June 2013.
2400 [HTTP-p1] Fielding, R. and J. Reschke, "Hypertext Transfer
2401 Protocol (HTTP/1.1): Message Syntax and Routing",
2402 draft-ietf-httpbis-p1-messaging-23 (work in progress),
2403 July 2013.
2405 [HTTP-p2] Fielding, R. and J. Reschke, "Hypertext Transfer
2406 Protocol (HTTP/1.1): Semantics and Content",
2407 draft-ietf-httpbis-p2-semantics-23 (work in progress),
2408 July 2013.
2410 [HTTP-p4] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext
2411 Transfer Protocol (HTTP/1.1): Conditional Requests",
2412 draft-ietf-httpbis-p4-conditional-23 (work in
2413 progress), July 2013.
2415 [HTTP-p5] Fielding, R., Ed., Lafon, Y., Ed., and J. Reschke,
2416 Ed., "Hypertext Transfer Protocol (HTTP/1.1): Range
2417 Requests", draft-ietf-httpbis-p5-range-23 (work in
2418 progress), July 2013.
2420 [HTTP-p6] Fielding, R., Ed., Nottingham, M., Ed., and J.
2421 Reschke, Ed., "Hypertext Transfer Protocol (HTTP/1.1):
2422 Caching", draft-ietf-httpbis-p6-cache-23 (work in
2423 progress), July 2013.
2425 [HTTP-p7] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext
2426 Transfer Protocol (HTTP/1.1): Authentication",
2427 draft-ietf-httpbis-p7-auth-23 (work in progress),
2428 July 2013.
2430 [RFC0793] Postel, J., "Transmission Control Protocol", STD 7,
2431 RFC 793, September 1981.
2433 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
2434 Requirement Levels", BCP 14, RFC 2119, March 1997.
2436 [RFC2818] Rescorla, E., "HTTP Over TLS", RFC 2818, May 2000.
2438 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter,
2439 "Uniform Resource Identifier (URI): Generic Syntax",
2440 STD 66, RFC 3986, January 2005.
2442 [RFC4648] Josefsson, S., "The Base16, Base32, and Base64 Data
2443 Encodings", RFC 4648, October 2006.
2445 [RFC5226] Narten, T. and H. Alvestrand, "Guidelines for Writing
2446 an IANA Considerations Section in RFCs", BCP 26,
2447 RFC 5226, May 2008.
2449 [RFC5234] Crocker, D. and P. Overell, "Augmented BNF for Syntax
2450 Specifications: ABNF", STD 68, RFC 5234, January 2008.
2452 [RFC6454] Barth, A., "The Web Origin Concept", RFC 6454,
2453 December 2011.
2455 [TLS-EXT] Eastlake, D., "Transport Layer Security (TLS)
2456 Extensions: Extension Definitions", RFC 6066,
2457 January 2011.
2459 [TLS11] Dierks, T. and E. Rescorla, "The Transport Layer
2460 Security (TLS) Protocol Version 1.1", RFC 4346,
2461 April 2006.
2463 [TLS12] Dierks, T. and E. Rescorla, "The Transport Layer
2464 Security (TLS) Protocol Version 1.2", RFC 5246,
2465 August 2008.
2467 [TLSALPN] Friedl, S., Popov, A., Langley, A., and E. Stephan,
2468 "Transport Layer Security (TLS) Application Layer
2469 Protocol Negotiation Extension",
2470 draft-ietf-tls-applayerprotoneg-01 (work in progress),
2471 April 2013.
2473 14.2. Informative References
2475 [BCP90] Klyne, G., Nottingham, M., and J. Mogul, "Registration
2476 Procedures for Message Header Fields", BCP 90,
2477 RFC 3864, September 2004.
2479 [RC4] Rivest, R., "The RC4 encryption algorithm", RSA Data
2480 Security, Inc. , March 1992.
2482 [RFC1323] Jacobson, V., Braden, B., and D. Borman, "TCP
2483 Extensions for High Performance", RFC 1323, May 1992.
2485 [TALKING] Huang, L-S., Chen, E., Barth, A., Rescorla, E., and C.
2486 Jackson, "Talking to Yourself for Fun and Profit",
2487 2011, .
2489 Appendix A. Change Log (to be removed by RFC Editor before publication)
2491 A.1. Since draft-ietf-httpbis-http2-04
2493 Added CONTINUATION frame for HEADERS and PUSH_PROMISE.
2495 PUSH_PROMISE is no longer implicitly prohibited if
2496 SETTINGS_MAX_CONCURRENT_STREAMS is zero.
2498 Push expanded to allow all safe methods without a request body.
2500 Clarified the use of HTTP header fields in requests and responses.
2502 Prohibited HTTP/1.1 hop-by-hop header fields.
2504 Requiring that intermediaries not forward requests with missing or
2505 illegal routing :-headers.
2507 Clarified requirements around handling different frames after stream
2508 close, stream reset and GOAWAY.
2510 Added more specific prohibitions for sending of different frame types
2511 in various stream states.
2513 Making the last received setting value the effective value.
2515 Clarified requirements on TLS version, extension and ciphers.
2517 A.2. Since draft-ietf-httpbis-http2-03
2519 Committed major restructuring atrocities.
2521 Added reference to first header compression draft.
2523 Added more formal description of frame lifecycle.
2525 Moved END_STREAM (renamed from FINAL) back to HEADERS/DATA.
2527 Removed HEADERS+PRIORITY, added optional priority to HEADERS frame.
2529 Added PRIORITY frame.
2531 A.3. Since draft-ietf-httpbis-http2-02
2533 Added continuations to frames carrying header blocks.
2535 Replaced use of "session" with "connection" to avoid confusion with
2536 other HTTP stateful concepts, like cookies.
2538 Removed "message".
2540 Switched to TLS ALPN from NPN.
2542 Editorial changes.
2544 A.4. Since draft-ietf-httpbis-http2-01
2546 Added IANA considerations section for frame types, error codes and
2547 settings.
2549 Removed data frame compression.
2551 Added PUSH_PROMISE.
2553 Added globally applicable flags to framing.
2555 Removed zlib-based header compression mechanism.
2557 Updated references.
2559 Clarified stream identifier reuse.
2561 Removed CREDENTIALS frame and associated mechanisms.
2563 Added advice against naive implementation of flow control.
2565 Added session header section.
2567 Restructured frame header. Removed distinction between data and
2568 control frames.
2570 Altered flow control properties to include session-level limits.
2572 Added note on cacheability of pushed resources and multiple tenant
2573 servers.
2575 Changed protocol label form based on discussions.
2577 A.5. Since draft-ietf-httpbis-http2-00
2579 Changed title throughout.
2581 Removed section on Incompatibilities with SPDY draft#2.
2583 Changed INTERNAL_ERROR on GOAWAY to have a value of 2 .
2586 Replaced abstract and introduction.
2588 Added section on starting HTTP/2.0, including upgrade mechanism.
2590 Removed unused references.
2592 Added flow control principles (Section 5.2.1) based on .
2595 A.6. Since draft-mbelshe-httpbis-spdy-00
2597 Adopted as base for draft-ietf-httpbis-http2.
2599 Updated authors/editors list.
2601 Added status note.
2603 Authors' Addresses
2605 Mike Belshe
2606 Twist
2608 EMail: mbelshe@chromium.org
2610 Roberto Peon
2611 Google, Inc
2613 EMail: fenix@google.com
2615 Martin Thomson (editor)
2616 Microsoft
2617 3210 Porter Drive
2618 Palo Alto 94304
2619 US
2621 EMail: martin.thomson@skype.net
2623 Alexey Melnikov (editor)
2624 Isode Ltd
2625 5 Castle Business Village
2626 36 Station Road
2627 Hampton, Middlesex TW12 2BX
2628 UK
2630 EMail: Alexey.Melnikov@isode.com