forked from fex-team/http2-spec
-
Notifications
You must be signed in to change notification settings - Fork 0
/
draft-ietf-httpbis-http2.xml
executable file
·4188 lines (3989 loc) · 210 KB
/
draft-ietf-httpbis-http2.xml
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
<?xml version="1.0"?>
<?xml-stylesheet type="text/xsl" href="lib/rfc2629.xslt"?>
<?rfc toc="yes" ?>
<?rfc symrefs="yes" ?>
<?rfc sortrefs="yes" ?>
<?rfc compact="yes"?>
<?rfc subcompact="no" ?>
<?rfc linkmailto="no" ?>
<?rfc editing="no" ?>
<?rfc comments="yes" ?>
<?rfc inline="yes"?>
<?rfc rfcedstyle="yes"?>
<?rfc-ext allow-markup-in-artwork="yes" ?>
<?rfc-ext include-index="no" ?>
<rfc ipr="trust200902"
category="std"
docName="draft-ietf-httpbis-http2-latest"
x:maturity-level="proposed"
xmlns:x="http://purl.org/net/xml2rfc/ext">
<x:feedback template="mailto:ietf-http-wg@w3.org?subject={docname},%20%22{section}%22&body=<{ref}>:"/>
<front>
<title abbrev="HTTP/2">Hypertext Transfer Protocol version 2</title>
<author initials="M." surname="Belshe" fullname="Mike Belshe">
<organization>Twist</organization>
<address>
<email>mbelshe@chromium.org</email>
</address>
</author>
<author initials="R." surname="Peon" fullname="Roberto Peon">
<organization>Google, Inc</organization>
<address>
<email>fenix@google.com</email>
</address>
</author>
<author initials="M." surname="Thomson" fullname="Martin Thomson" role="editor">
<organization>Mozilla</organization>
<address>
<postal>
<street>Suite 300</street>
<street>650 Castro Street</street>
<city>Mountain View</city>
<region>CA</region>
<code>94041</code>
<country>US</country>
</postal>
<email>martin.thomson@gmail.com</email>
</address>
</author>
<date year="2014" />
<area>Applications</area>
<workgroup>HTTPbis</workgroup>
<keyword>HTTP</keyword>
<keyword>SPDY</keyword>
<keyword>Web</keyword>
<abstract>
<t>
This specification describes an optimized expression of the syntax of the Hypertext Transfer
Protocol (HTTP). HTTP/2 enables a more efficient use of network resources and a reduced
perception of latency by introducing header field compression and allowing multiple
concurrent messages on the same connection. It also introduces unsolicited push of
representations from servers to clients.
</t>
<t>
This document is an alternative to, but does not obsolete, the HTTP/1.1 message syntax.
HTTP's existing semantics remain unchanged.
</t>
</abstract>
<note title="Editorial Note (To be removed by RFC Editor)">
<t>
Discussion of this draft takes place on the HTTPBIS working group mailing list
(ietf-http-wg@w3.org), which is archived at <eref
target="http://lists.w3.org/Archives/Public/ietf-http-wg/"/>.
</t>
<t>
Working Group information can be found at <eref
target="http://tools.ietf.org/wg/httpbis/"/>; that specific to HTTP/2 are at <eref
target="http://http2.github.io/"/>.
</t>
<t>
The changes in this draft are summarized in <xref
target="change.log"/>.
</t>
</note>
</front>
<middle>
<section anchor="intro" title="Introduction">
<t>
The Hypertext Transfer Protocol (HTTP) is a wildly successful protocol. However, the
HTTP/1.1 message format (<xref target="HTTP-p1" x:fmt="," x:rel="#http.message"/>) was
designed to be implemented with the tools at hand in the 1990s, not modern Web application
performance. As such it has several characteristics that have a negative overall effect on
application performance today.
</t>
<t>
In particular, HTTP/1.0 only allows one request to be outstanding at a time on a given
connection. HTTP/1.1 pipelining only partially addressed request concurrency and
suffers from head-of-line blocking. Therefore, clients that need to make many requests
typically use multiple connections to a server in order to reduce latency.
</t>
<t>
Furthermore, HTTP/1.1 header fields are often repetitive and verbose, which, in addition to
generating more or larger network packets, can cause the small initial TCP congestion window
to quickly fill. This can result in excessive latency when multiple requests are made on a
single new TCP connection.
</t>
<t>
This document addresses these issues by defining an optimized mapping of HTTP's semantics to
an underlying connection. Specifically, it allows interleaving of request and response
messages on the same connection and uses an efficient coding for HTTP header fields. It
also allows prioritization of requests, letting more important requests complete more
quickly, further improving performance.
</t>
<t>
The resulting protocol is designed to be more friendly to the network, because fewer TCP
connections can be used in comparison to HTTP/1.x. This means less competition with other
flows, and longer-lived connections, which in turn leads to better utilization of available
network capacity.
</t>
<t>
Finally, this encapsulation also enables more scalable processing of messages through use of
binary message framing.
</t>
</section>
<section anchor="Overview" title="HTTP/2 Protocol Overview">
<t>
HTTP/2 provides an optimized transport for HTTP semantics. HTTP/2 supports all of the core
features of HTTP/1.1, but aims to be more efficient in several ways.
</t>
<t>
The basic protocol unit in HTTP/2 is a <xref target="FrameHeader">frame</xref>. Each frame
has a different type and purpose. For example, <x:ref>HEADERS</x:ref> and
<x:ref>DATA</x:ref> frames form the basis of <xref target="HttpSequence">HTTP requests and
responses</xref>; other frame types like <x:ref>SETTINGS</x:ref>,
<x:ref>WINDOW_UPDATE</x:ref>, and <x:ref>PUSH_PROMISE</x:ref> are used in support of other
HTTP/2 features.
</t>
<t>
Multiplexing of requests is achieved by having each HTTP request-response exchanged assigned
to a single <xref target="StreamsLayer">stream</xref>. Streams are largely independent of
each other, so a blocked or stalled request does not prevent progress on other requests.
</t>
<t>
Flow control and prioritization ensure that it is possible to properly use multiplexed
streams. <xref target="FlowControl">Flow control</xref> helps to ensure that only data that
can be used by a receiver is transmitted. <xref
target="StreamPriority">Prioritization</xref> ensures that limited resources can be directed
to the most important requests first.
</t>
<t>
HTTP/2 adds a new interaction mode, whereby a server can <xref target="PushResources">push
responses to a client</xref>. Server push allows a server to speculatively send a client
data that the server anticipates the client will need, trading off some network usage
against a potential latency gain. The server does this by synthesizing a request, which it
sends as a <x:ref>PUSH_PROMISE</x:ref> frame. The server is then able to send a response to
the synthetic request on an separate stream.
</t>
<t>
Frames that contain HTTP header fields are <xref target="HeaderBlock">compressed</xref>.
HTTP requests can be highly redundant, so compression can reduce the size of requests and
responses significantly.
</t>
<section title="Document Organization">
<t>
The HTTP/2 specification is split into four parts:
<list style="symbols">
<t>
<xref target="starting">Starting HTTP/2</xref> covers how an HTTP/2 connection is
initiated.
</t>
<t>
The <xref target="FramingLayer">framing</xref> and <xref
target="StreamsLayer">streams</xref> layers describe the way HTTP/2 frames are
structured and formed into multiplexed streams.
</t>
<t>
<xref target="frame-types">Frame</xref> and <xref target="ErrorCodes">error</xref>
definitions include details of the frame and error types used in HTTP/2.
</t>
<t>
<xref target="HTTPLayer">HTTP mappings</xref> and <xref target="HttpExtra">additional
requirements</xref> describe how HTTP semantics are expressed using frames and
streams.
</t>
</list>
</t>
<t>
While some of the frame and stream layer concepts are isolated from HTTP, the intent is
not to define a completely generic framing layer. The framing and streams layers are
tailored to the needs of the HTTP protocol and server push.
</t>
</section>
<section title="Conventions and Terminology">
<t>
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD
NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as
described in <xref target="RFC2119">RFC 2119</xref>.
</t>
<t>
All numeric values are in network byte order. Values are unsigned unless otherwise
indicated. Literal values are provided in decimal or hexadecimal as appropriate.
Hexadecimal literals are prefixed with <spanx style="verb">0x</spanx> to distinguish them
from decimal literals.
</t>
<t>
The following terms are used:
<list style="hanging">
<t hangText="client:">
The endpoint initiating the HTTP/2 connection.
</t>
<t hangText="connection:">
A transport-level connection between two endpoints.
</t>
<t hangText="connection error:">
An error that affects the entire HTTP/2 connection.
</t>
<t hangText="endpoint:">
Either the client or server of the connection.
</t>
<t hangText="frame:">
The smallest unit of communication within an HTTP/2 connection, consisting of a header
and a variable-length sequence of bytes structured according to the frame type.
</t>
<t hangText="peer:">
An endpoint. When discussing a particular endpoint, "peer" refers to the endpoint
that is remote to the primary subject of discussion.
</t>
<t hangText="receiver:">
An endpoint that is receiving frames.
</t>
<t hangText="sender:">
An endpoint that is transmitting frames.
</t>
<t hangText="server:">
The endpoint which did not initiate the HTTP/2 connection.
</t>
<t hangText="stream:">
A bi-directional flow of frames across a virtual channel within the HTTP/2 connection.
</t>
<t hangText="stream error:">
An error on the individual HTTP/2 stream.
</t>
</list>
</t>
</section>
</section>
<section anchor="starting" title="Starting HTTP/2">
<t>
An HTTP/2 connection is an application level protocol running on top of a TCP connection
(<xref target="TCP"/>). The client is the TCP connection initiator.
</t>
<t>
HTTP/2 uses the same "http" and "https" URI schemes used by HTTP/1.1. HTTP/2 shares the same
default port numbers: 80 for "http" URIs and 443 for "https" URIs. As a result,
implementations processing requests for target resource URIs like <spanx
style="verb">http://example.org/foo</spanx> or <spanx
style="verb">https://example.com/bar</spanx> are required to first discover whether the
upstream server (the immediate peer to which the client wishes to establish a connection)
supports HTTP/2.
</t>
<t>
The means by which support for HTTP/2 is determined is different for "http" and "https"
URIs. Discovery for "http" URIs is described in <xref target="discover-http"/>. Discovery
for "https" URIs is described in <xref target="discover-https"/>.
</t>
<section anchor="versioning" title="HTTP/2 Version Identification">
<t>
The protocol defined in this document is identified using the string "h2". This
identification is used in the HTTP/1.1 Upgrade header field, in the <xref
target="TLSALPN">TLS application layer protocol negotiation extension</xref> field, and
other places where protocol identification is required. When serialised into an ALPN
protocol identifier (which is a sequence of octets), the "h2" string is encoded using
<xref target="UTF-8">UTF-8</xref>.
</t>
<t>
Negotiating "h2" implies the use of the transport, security, framing and message
semantics described in this document.
</t>
<t>
<cref>Editor's Note: please remove the remainder of this section prior to the publication
of a final version of this document.</cref>
</t>
<t>
Only implementations of the final, published RFC can identify themselves as "h2".
Until such an RFC exists, implementations MUST NOT identify themselves using "h2".
</t>
<t>
Examples and text throughout the rest of this document use "h2" as a matter of
editorial convenience only. Implementations of draft versions MUST NOT identify using
this string.
</t>
<t>
Implementations of draft versions of the protocol MUST add the string "-" and the
corresponding draft number to the identifier. For example, draft-ietf-httpbis-http2-09
is identified using the string "h2-09".
</t>
<t>
Non-compatible experiments that are based on these draft versions MUST append the string
"-" and an experiment name to the identifier. For example, an experimental implementation
of packet mood-based encoding based on draft-ietf-httpbis-http2-09 might identify itself
as "h2-09-emo". Note that any label MUST conform to the "token" syntax defined in
<xref target="HTTP-p1" x:fmt="of" x:rel="#field.components"/>. Experimenters are
encouraged to coordinate their experiments on the ietf-http-wg@w3.org mailing list.
</t>
</section>
<section anchor="discover-http" title="Starting HTTP/2 for "http" URIs">
<t>
A client that makes a request to an "http" URI without prior knowledge about support for
HTTP/2 uses the HTTP Upgrade mechanism (<xref target="HTTP-p1" x:fmt="of"
x:rel="#header.upgrade"/>). The client makes an HTTP/1.1 request that includes an Upgrade
header field identifying HTTP/2 with the h2 token. The HTTP/1.1 request MUST include
exactly one <xref target="Http2SettingsHeader">HTTP2-Settings</xref> header field.
</t>
<figure>
<preamble>For example:</preamble>
<artwork type="message/http; msgtype="request"" x:indent-with=" "><![CDATA[
GET /default.htm HTTP/1.1
Host: server.example.com
Connection: Upgrade, HTTP2-Settings
Upgrade: h2
HTTP2-Settings: <base64url encoding of HTTP/2 SETTINGS payload>
]]></artwork>
</figure>
<t>
Requests that contain an entity body MUST be sent in their entirety before the client can
send HTTP/2 frames. This means that a large request entity can block the use of the
connection until it is completely sent.
</t>
<t>
If concurrency of an initial request with subsequent requests is important, a small
request can be used to perform the upgrade to HTTP/2, at the cost of an additional
round-trip.
</t>
<t>
A server that does not support HTTP/2 can respond to the request as though the Upgrade
header field were absent:
</t>
<figure>
<artwork type="message/http; msgtype="response"" x:indent-with=" ">
HTTP/1.1 200 OK
Content-Length: 243
Content-Type: text/html
...
</artwork>
</figure>
<t>
A server that supports HTTP/2 can accept the upgrade with a 101 (Switching Protocols)
response. After the empty line that terminates the 101 response, the server can begin
sending HTTP/2 frames. These frames MUST include a response to the request that initiated
the Upgrade.
</t>
<figure>
<artwork type="message/http; msgtype="response"" x:indent-with=" ">
HTTP/1.1 101 Switching Protocols
Connection: Upgrade
Upgrade: h2
[ HTTP/2 connection ...
</artwork>
</figure>
<t>
The first HTTP/2 frame sent by the server is a <x:ref>SETTINGS</x:ref> frame (<xref
target="SETTINGS"/>). Upon receiving the 101 response, the client sends a <xref
target="ConnectionHeader">connection preface</xref>, which includes a
<x:ref>SETTINGS</x:ref> frame.
</t>
<t>
The HTTP/1.1 request that is sent prior to upgrade is assigned stream identifier 1 and is
assigned the highest possible priority. Stream 1 is implicitly half closed from the
client toward the server, since the request is completed as an HTTP/1.1 request. After
commencing the HTTP/2 connection, stream 1 is used for the response.
</t>
<section anchor="Http2SettingsHeader" title="HTTP2-Settings Header Field">
<t>
A request that upgrades from HTTP/1.1 to HTTP/2 MUST include exactly one <spanx
style="verb">HTTP2-Settings</spanx> header field. The <spanx
style="verb">HTTP2-Settings</spanx> header field is a hop-by-hop header field that
includes parameters that govern the HTTP/2 connection, provided in anticipation of the
server accepting the request to upgrade. A server MUST reject an attempt to upgrade if
this header field is not present.
</t>
<figure>
<artwork type="abnf" x:indent-with=" "><![CDATA[
HTTP2-Settings = token68
]]></artwork>
</figure>
<t>
The content of the <spanx style="verb">HTTP2-Settings</spanx> header field is the
payload of a <x:ref>SETTINGS</x:ref> frame (<xref target="SETTINGS"/>), encoded as a
base64url string (that is, the URL- and filename-safe Base64 encoding described in <xref
target="RFC4648" x:fmt="of" x:sec="5"/>, with any trailing '=' characters omitted). The
<xref target="RFC5234">ABNF</xref> production for <spanx style="verb">token68</spanx> is
defined in <xref target="HTTP-p7" x:fmt="of" x:rel="#challenge.and.response"/>.
</t>
<t>
The client MUST include values for the following <xref
target="SettingFormat">SETTINGS parameters</xref>:
<list style="symbols">
<t><x:ref>SETTINGS_MAX_CONCURRENT_STREAMS</x:ref></t>
<t><x:ref>SETTINGS_INITIAL_WINDOW_SIZE</x:ref></t>
</list>
</t>
<t>
As a hop-by-hop header field, the <spanx style="verb">Connection</spanx> header field
MUST include a value of <spanx style="verb">HTTP2-Settings</spanx> in addition to <spanx
style="verb">Upgrade</spanx> when upgrading to HTTP/2.
</t>
<t>
A server decodes and interprets these values as it would any other
<x:ref>SETTINGS</x:ref> frame. <xref target="SettingsSync">Acknowledgement of the
SETTINGS parameters</xref> is not necessary, since a 101 response serves as implicit
acknowledgment. Providing these values in the Upgrade request ensures that the protocol
does not require default values for the above SETTINGS parameters, and gives a client an
opportunity to provide other parameters prior to receiving any frames from the server.
</t>
</section>
</section>
<section anchor="discover-https" title="Starting HTTP/2 for "https" URIs">
<t>
A client that makes a request to an "https" URI without prior knowledge about support for
HTTP/2 uses <xref target="TLS12">TLS</xref> with the <xref target="TLSALPN">application
layer protocol negotiation extension</xref>.
</t>
<t>
Once TLS negotiation is complete, both the client and the server send a <xref
target="ConnectionHeader">connection preface</xref>.
</t>
</section>
<section anchor="known-http" title="Starting HTTP/2 with Prior Knowledge">
<t>
A client can learn that a particular server supports HTTP/2 by other means. For example,
<xref target="AltSvc"/> describes a mechanism for advertising this capability in an HTTP
header field. A client MAY immediately send HTTP/2 frames to a server that is known to
support HTTP/2, after the <xref target="ConnectionHeader">connection preface</xref>. A
server can identify such a connection by the use of the "PRI" method in the connection
preface. This only affects the resolution of "http" URIs; servers supporting HTTP/2 are
required to support <xref target="TLSALPN">protocol negotiation in TLS</xref> for "https"
URIs.
</t>
<t>
Prior support for HTTP/2 is not a strong signal that a given server will support HTTP/2
for future connections. It is possible for server configurations to change or for
configurations to differ between instances in clustered server. Interception proxies
(a.k.a. "transparent" proxies) are another source of variability.
</t>
</section>
<section anchor="ConnectionHeader" title="HTTP/2 Connection Preface">
<t>
Upon establishment of a TCP connection and determination that HTTP/2 will be used by both
peers, each endpoint MUST send a connection preface as a final confirmation and to
establish the initial SETTINGS parameters for the HTTP/2 connection.
</t>
<t>
The client connection preface starts with a sequence of 24 octets, which in hex notation
are:
</t>
<figure>
<artwork type="inline" x:indent-with=" "><![CDATA[
0x505249202a20485454502f322e300d0a0d0a534d0d0a0d0a
]]></artwork>
</figure>
<t>
(the string <spanx style="verb">PRI * HTTP/2.0\r\n\r\nSM\r\n\r\n</spanx>). This sequence
is followed by a <x:ref>SETTINGS</x:ref> frame (<xref target="SETTINGS"/>). The client
sends the client connection preface immediately upon receipt of a 101 Switching Protocols
response (indicating a successful upgrade), or as the first application data octets of a
TLS connection. If starting an HTTP/2 connection with prior knowledge of server support
for the protocol, the client connection preface is sent upon connection establishment.
</t>
<t>
<list>
<t>
The client connection preface is selected so that a large proportion of HTTP/1.1 or
HTTP/1.0 servers and intermediaries do not attempt to process further frames. Note
that this does not address the concerns raised in <xref target="TALKING"/>.
</t>
</list>
</t>
<t>
The server connection preface consists of just a <x:ref>SETTINGS</x:ref> frame (<xref
target="SETTINGS"/>) that MUST be the first frame the server sends in the HTTP/2
connection.
</t>
<t>
To avoid unnecessary latency, clients are permitted to send additional frames to the
server immediately after sending the client connection preface, without waiting to receive
the server connection preface. It is important to note, however, that the server
connection preface <x:ref>SETTINGS</x:ref> frame might include parameters that necessarily
alter how a client is expected to communicate with the server. Upon receiving the
<x:ref>SETTINGS</x:ref> frame, the client is expected to honor any parameters established.
</t>
<t>
Clients and servers MUST terminate the TCP connection if either peer does not begin with a
valid connection preface. A <x:ref>GOAWAY</x:ref> frame (<xref target="GOAWAY"/>) MAY be
omitted if it is clear that the peer is not using HTTP/2.
</t>
</section>
</section>
<section anchor="FramingLayer" title="HTTP Frames">
<t>
Once the HTTP/2 connection is established, endpoints can begin exchanging frames.
</t>
<section anchor="FrameHeader" title="Frame Format">
<t>
All frames begin with an 8-octet header followed by a payload of between 0 and 16,383
octets.
</t>
<figure title="Frame Header">
<artwork type="inline"><![CDATA[
0 1 2 3
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
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| R | Length (14) | Type (8) | Flags (8) |
+-+-+-----------+---------------+-------------------------------+
|R| Stream Identifier (31) |
+-+-------------------------------------------------------------+
| Frame Payload (0...) ...
+---------------------------------------------------------------+
]]></artwork>
</figure>
<t>
The fields of the frame header are defined as:
<list style="hanging">
<x:lt hangText="R:">
<t>
A reserved 2-bit field. The semantics of these bits are undefined and the bits MUST
remain unset (0) when sending and MUST be ignored when receiving.
</t>
</x:lt>
<x:lt hangText="Length:">
<t>
The length of the frame payload expressed as an unsigned 14-bit integer. The 8 octets
of the frame header are not included in this value.
</t>
</x:lt>
<x:lt hangText="Type:">
<t>
The 8-bit type of the frame. The frame type determines how the remainder of the
frame header and payload are interpreted. Implementations MUST treat the receipt of
an unknown frame type (any frame types not defined in this document) as a <xref
target="ConnectionErrorHandler">connection error</xref> of type
<x:ref>PROTOCOL_ERROR</x:ref>.
</t>
</x:lt>
<x:lt hangText="Flags:">
<t>
An 8-bit field reserved for frame-type specific boolean flags.
</t>
<t>
Flags are assigned semantics specific to the indicated frame type.
Flags that have no defined semantics for a particular frame type
MUST be ignored, and MUST be left unset (0) when sending.
</t>
</x:lt>
<x:lt hangText="R:">
<t>
A reserved 1-bit field. The semantics of this bit are undefined and the bit MUST
remain unset (0) when sending and MUST be ignored when receiving.
</t>
</x:lt>
<x:lt hangText="Stream Identifier:">
<t>
A 31-bit stream identifier (see <xref target="StreamIdentifiers"/>). The value 0 is
reserved for frames that are associated with the connection as a whole as opposed to
an individual stream.
</t>
</x:lt>
</list>
</t>
<t>
The structure and content of the frame payload is dependent entirely on the frame type.
</t>
</section>
<section anchor="FrameSize" title="Frame Size">
<t>
The maximum size of a frame payload varies by frame type. The absolute maximum size of a
frame payload is 2<x:sup>14</x:sup>-1 (16,383) octets, meaning that the maximum frame
size is 16,391 octets. All implementations SHOULD be capable of receiving and minimally
processing frames up to this maximum size.
</t>
<t>
Certain frame types, such as <x:ref>PING</x:ref> (see <xref target="PING"/>), impose
additional limits on the amount of payload data allowed. Likewise, additional size limits
can be set by specific application uses (see <xref target="HttpExtra" />).
</t>
<t>
If a frame size exceeds any defined limit, or is too small to contain mandatory frame
data, the endpoint MUST send a <x:ref>FRAME_SIZE_ERROR</x:ref> error. A frame size error
in a frame that could alter the state of the entire connection MUST be treated as a <xref
target="ConnectionErrorHandler">connection error</xref>; this includes any frame carrying
a <xref target="HeaderBlock">header block</xref> (that is, <x:ref>HEADERS</x:ref>,
<x:ref>PUSH_PROMISE</x:ref>, and <x:ref>CONTINUATION</x:ref>), <x:ref>SETTINGS</x:ref>,
and any <x:ref>WINDOW_UPDATE</x:ref> frame with a stream identifier of 0.
</t>
</section>
<section anchor="HeaderBlock" title="Header Compression and Decompression">
<t>
A header field in HTTP/2 is a name-value pair with one or more associated values. They are
used within HTTP request and response messages as well as server push operations (see
<xref target="PushResources" />).
</t>
<t>
Header sets are collections of zero or more header fields. When transmitted over a
connection, a header set is serialized into a header block using <xref
target="COMPRESSION">HTTP Header Compression</xref>. The serialized header block is then
divided into one or more octet sequences, called header block fragments, and transmitted
within the payload of <xref target="HEADERS">HEADERS</xref>, <xref
target="PUSH_PROMISE">PUSH_PROMISE</xref> or <xref
target="CONTINUATION">CONTINUATION</xref> frames.
</t>
<t>
HTTP Header Compression does not preserve the relative ordering of header fields. Header
fields with multiple values are encoded into a single header field using a special
delimiter; see <xref target="HeaderOrdering"/>.
</t>
<t>
The <xref target="COOKIE">Cookie header field</xref> is treated specially by the HTTP
mapping; see <xref target="CompressCookie"/>.
</t>
<t>
A receiving endpoint reassembles the header block by concatenating its fragments, then
decompresses the block to reconstruct the header set.
</t>
<t>
A complete header block consists of either:
<list style="symbols">
<t>
a single <x:ref>HEADERS</x:ref> or <x:ref>PUSH_PROMISE</x:ref> frame,
with the END_HEADERS flag set, or
</t>
<t>
a <x:ref>HEADERS</x:ref> or <x:ref>PUSH_PROMISE</x:ref> frame with the END_HEADERS
flag cleared and one or more <x:ref>CONTINUATION</x:ref> frames,
where the last <x:ref>CONTINUATION</x:ref> frame has the END_HEADERS flag set.
</t>
</list>
</t>
<t>
Header blocks MUST be transmitted as a contiguous sequence of frames, with no interleaved
frames of any other type or from any other stream. The last frame in a sequence of
<x:ref>HEADERS</x:ref> or <x:ref>CONTINUATION</x:ref> frames MUST have the END_HEADERS
flag set. The last frame in a sequence of <x:ref>PUSH_PROMISE</x:ref> or
<x:ref>CONTINUATION</x:ref> frames MUST have the END_HEADERS flag set.
</t>
<t>
Header block fragments can only be sent as the payload of <x:ref>HEADERS</x:ref>,
<x:ref>PUSH_PROMISE</x:ref> or <x:ref>CONTINUATION</x:ref> frames, because these frames
carry data that can modify the compression context maintained by a receiver. An endpoint
receiving <x:ref>HEADERS</x:ref>, <x:ref>PUSH_PROMISE</x:ref> or
<x:ref>CONTINUATION</x:ref> frames MUST reassemble header blocks and perform decompression
even if the frames are to be discarded. A receiver MUST terminate the connection with a
<xref target="ConnectionErrorHandler">connection error</xref> of type
<x:ref>COMPRESSION_ERROR</x:ref> if it does not decompress a header block.
</t>
</section>
</section>
<section anchor="StreamsLayer" title="Streams and Multiplexing">
<t>
A "stream" is an independent, bi-directional sequence of <x:ref>HEADERS</x:ref> and
<x:ref>DATA</x:ref> frames exchanged between the client and server within an HTTP/2
connection. Streams have several important characteristics:
<list style="symbols">
<t>
A single HTTP/2 connection can contain multiple concurrently open streams, with either
endpoint interleaving frames from multiple streams.
</t>
<t>
Streams can be established and used unilaterally or shared by either the client or
server.
</t>
<t>
Streams can be closed by either endpoint.
</t>
<t>
The order in which frames are sent within a stream is significant. Recipients process
frames in the order they are received.
</t>
<t>
Streams are identified by an integer. Stream identifiers are assigned to streams by
the endpoint initiating the stream.
</t>
</list>
</t>
<section anchor="StreamStates" title="Stream States">
<t>
The lifecycle of a stream is shown in <xref target="StreamStatesFigure"/>.
</t>
<figure anchor="StreamStatesFigure" title="Stream States">
<artwork type="drawing">
<![CDATA[
+--------+
PP | | PP
,--------| idle |--------.
/ | | \
v +--------+ v
+----------+ | +----------+
| | | H | |
,---| reserved | | | reserved |---.
| | (local) | v | (remote) | |
| +----------+ +--------+ +----------+ |
| | ES | | ES | |
| | H ,-------| open |-------. | H |
| | / | | \ | |
| v v +--------+ v v |
| +----------+ | +----------+ |
| | half | | | half | |
| | closed | | R | closed | |
| | (remote) | | | (local) | |
| +----------+ | +----------+ |
| | v | |
| | ES / R +--------+ ES / R | |
| `----------->| |<-----------' |
| R | closed | R |
`-------------------->| |<--------------------'
+--------+
H: HEADERS frame (with implied CONTINUATIONs)
PP: PUSH_PROMISE frame (with implied CONTINUATIONs)
ES: END_STREAM flag
R: RST_STREAM frame
]]>
</artwork>
</figure>
<t>
Both endpoints have a subjective view of the state of a stream that could be different
when frames are in transit. Endpoints do not coordinate the creation of streams; they are
created unilaterally by either endpoint. The negative consequences of a mismatch in
states are limited to the "closed" state after sending <x:ref>RST_STREAM</x:ref>, where
frames might be received for some time after closing.
</t>
<t>
Streams have the following states:
<list style="hanging">
<x:lt hangText="idle:">
<t>
<vspace blankLines="0"/>
All streams start in the "idle" state. In this state, no frames have been
exchanged.
</t>
<t>
The following transitions are valid from this state:
<list style="symbols">
<t>
Sending or receiving a <x:ref>HEADERS</x:ref> frame causes the stream to become
"open". The stream identifier is selected as described in <xref
target="StreamIdentifiers"/>. The same <x:ref>HEADERS</x:ref> frame can also
cause a stream to immediately become "half closed".
</t>
<t>
Sending a <x:ref>PUSH_PROMISE</x:ref> frame marks the associated stream for
later use. The stream state for the reserved stream transitions to "reserved
(local)".
</t>
<t>
Receiving a <x:ref>PUSH_PROMISE</x:ref> frame marks the associated stream as
reserved by the remote peer. The state of the stream becomes "reserved
(remote)".
</t>
</list>
</t>
</x:lt>
<x:lt hangText="reserved (local):">
<t>
<vspace blankLines="0"/>
A stream in the "reserved (local)" state is one that has been promised by sending a
<x:ref>PUSH_PROMISE</x:ref> frame. A <x:ref>PUSH_PROMISE</x:ref> frame reserves an
idle stream by associating the stream with an open stream that was initiated by the
remote peer (see <xref target="PushResources"/>).
</t>
<t>
In this state, only the following transitions are possible:
<list style="symbols">
<t>
The endpoint can send a <x:ref>HEADERS</x:ref> frame. This causes the stream to
open in a "half closed (remote)" state.
</t>
<t>
Either endpoint can send a <x:ref>RST_STREAM</x:ref> frame to cause the stream
to become "closed". This releases the stream reservation.
</t>
</list>
</t>
<t>
An endpoint MUST NOT send frames other than <x:ref>HEADERS</x:ref> or
<x:ref>RST_STREAM</x:ref> in this state.
</t>
<t>
A <x:ref>PRIORITY</x:ref> frame MAY be received in this state. Receiving any frames
other than <x:ref>RST_STREAM</x:ref>, or <x:ref>PRIORITY</x:ref> MUST be treated as
a <xref target="ConnectionErrorHandler">connection error</xref> of type
<x:ref>PROTOCOL_ERROR</x:ref>.
</t>
</x:lt>
<x:lt hangText="reserved (remote):">
<t>
<vspace blankLines="0"/>
A stream in the "reserved (remote)" state has been reserved by a remote peer.
</t>
<t>
In this state, only the following transitions are possible:
<list style="symbols">
<t>
Receiving a <x:ref>HEADERS</x:ref> frame causes the stream to transition to
"half closed (local)".
</t>
<t>
Either endpoint can send a <x:ref>RST_STREAM</x:ref> frame to cause the stream
to become "closed". This releases the stream reservation.
</t>
</list>
</t>
<t>
An endpoint MAY send a <x:ref>PRIORITY</x:ref> frame in this state to reprioritize
the reserved stream. An endpoint MUST NOT send any other type of frame other than
<x:ref>RST_STREAM</x:ref> or <x:ref>PRIORITY</x:ref>.
</t>
<t>
Receiving any other type of frame other than <x:ref>HEADERS</x:ref> or
<x:ref>RST_STREAM</x:ref> MUST be treated as a <xref
target="ConnectionErrorHandler">connection error</xref> of type
<x:ref>PROTOCOL_ERROR</x:ref>.
</t>
</x:lt>
<x:lt hangText="open:">
<t>
<vspace blankLines="0"/>
A stream in the "open" state may be used by both peers to send frames of any type.
In this state, sending peers observe advertised <xref target="FlowControl">stream
level flow control limits</xref>.
</t>
<t>
From this state either endpoint can send a frame with an END_STREAM flag set, which
causes the stream to transition into one of the "half closed" states: an endpoint
sending an END_STREAM flag causes the stream state to become "half closed (local)"; an
endpoint receiving an END_STREAM flag causes the stream state to become "half closed
(remote)". A <x:ref>HEADERS</x:ref> frame bearing an END_STREAM flag can be followed
by <x:ref>CONTINUATION</x:ref> frames.
</t>
<t>
Either endpoint can send a <x:ref>RST_STREAM</x:ref> frame from this state, causing it
to transition immediately to "closed".
</t>
</x:lt>
<x:lt hangText="half closed (local):">
<t>
<vspace blankLines="0"/>
A stream that is in the "half closed (local)" state cannot be used for sending frames.
</t>
<t>
A stream transitions from this state to "closed" when a frame that contains an
END_STREAM flag is received, or when either peer sends a <x:ref>RST_STREAM</x:ref>
frame. A <x:ref>HEADERS</x:ref> frame bearing an END_STREAM flag can be followed by
<x:ref>CONTINUATION</x:ref> frames.
</t>
<t>
A receiver can ignore <x:ref>WINDOW_UPDATE</x:ref> or <x:ref>PRIORITY</x:ref> frames
in this state. These frame types might arrive for a short period after a frame
bearing the END_STREAM flag is sent.
</t>
</x:lt>
<x:lt hangText="half closed (remote):">
<t>
<vspace blankLines="0"/>
A stream that is "half closed (remote)" is no longer being used by the peer to send
frames. In this state, an endpoint is no longer obligated to maintain a receiver
flow control window if it performs flow control.
</t>
<t>
If an endpoint receives additional frames for a stream that is in this state, other
than <x:ref>CONTINUATION</x:ref> frames, it MUST respond with a <xref
target="StreamErrorHandler">stream error</xref> of type
<x:ref>STREAM_CLOSED</x:ref>.
</t>
<t>
A stream can transition from this state to "closed" by sending a frame that contains
an END_STREAM flag, or when either peer sends a <x:ref>RST_STREAM</x:ref> frame.
</t>
</x:lt>
<x:lt hangText="closed:">
<t>
<vspace blankLines="0"/>
The "closed" state is the terminal state.
</t>
<t>
An endpoint MUST NOT send frames on a closed stream. An endpoint that receives any
frame after receiving a <x:ref>RST_STREAM</x:ref> MUST treat that as a <xref
target="StreamErrorHandler">stream error</xref> of type
<x:ref>STREAM_CLOSED</x:ref>. Similarly, an endpoint that receives any frames after
receiving a <x:ref>DATA</x:ref> frame with the END_STREAM flag set, or any frames
except a <x:ref>CONTINUATION</x:ref> frame after receiving a <x:ref>HEADERS</x:ref>
frame with an END_STREAM flag set MUST treat that as a <xref
target="StreamErrorHandler">stream error</xref> of type
<x:ref>STREAM_CLOSED</x:ref>.
</t>
<t>
<x:ref>WINDOW_UPDATE</x:ref>, <x:ref>PRIORITY</x:ref>, or <x:ref>RST_STREAM</x:ref>
frames can be received in this state for a short period after a <x:ref>DATA</x:ref>
or <x:ref>HEADERS</x:ref> frame containing an END_STREAM flag is sent. Until the
remote peer receives and processes the frame bearing the END_STREAM flag, it might
send frame of any of these types. Endpoints MUST ignore
<x:ref>WINDOW_UPDATE</x:ref>, <x:ref>PRIORITY</x:ref>, or <x:ref>RST_STREAM</x:ref>
frames received in this state, though endpoints MAY choose to treat frames that
arrive a significant time after sending END_STREAM as a <xref
target="ConnectionErrorHandler">connection error</xref> of type
<x:ref>PROTOCOL_ERROR</x:ref>.
</t>
<t>
If this state is reached as a result of sending a <x:ref>RST_STREAM</x:ref> frame,
the peer that receives the <x:ref>RST_STREAM</x:ref> might have already sent - or
enqueued for sending - frames on the stream that cannot be withdrawn. An endpoint
MUST ignore frames that it receives on closed streams after it has sent a
<x:ref>RST_STREAM</x:ref> frame. An endpoint MAY choose to limit the period over
which it ignores frames and treat frames that arrive after this time as being in
error.
</t>
<t>
Flow controlled frames (i.e., <x:ref>DATA</x:ref>) received after sending
<x:ref>RST_STREAM</x:ref> are counted toward the connection flow control window.
Even though these frames might be ignored, because they are sent before the sender
receives the <x:ref>RST_STREAM</x:ref>, the sender will consider the frames to count
against the flow control window.
</t>
<t>
An endpoint might receive a <x:ref>PUSH_PROMISE</x:ref> frame after it sends
<x:ref>RST_STREAM</x:ref>. <x:ref>PUSH_PROMISE</x:ref> causes a stream to become
"reserved" even if the associated stream has been reset. Therefore, a
<x:ref>RST_STREAM</x:ref> is needed to close an unwanted promised streams.
</t>
</x:lt>
</list>
</t>
<t>
In the absence of more specific guidance elsewhere in this document, implementations
SHOULD treat the receipt of a message that is not expressly permitted in the description
of a state as a <xref target="ConnectionErrorHandler">connection error</xref> of type
<x:ref>PROTOCOL_ERROR</x:ref>.
</t>
<section anchor="StreamIdentifiers" title="Stream Identifiers">
<t>
Streams are identified with an unsigned 31-bit integer. Streams initiated by a client
MUST use odd-numbered stream identifiers; those initiated by the server MUST use
even-numbered stream identifiers. A stream identifier of zero (0x0) is used for
connection control messages; the stream identifier zero MUST NOT be used to establish a
new stream.
</t>
<t>
HTTP/1.1 requests that are upgraded to HTTP/2 (see <xref target="discover-http"/>) are
responded to with a stream identifier of one (0x1). After the upgrade
completes, stream 0x1 is "half closed (local)" to the client. Therefore, stream 0x1
cannot be selected as a new stream identifier by a client that upgrades from HTTP/1.1.
</t>
<t>
The identifier of a newly established stream MUST be numerically greater than all
streams that the initiating endpoint has opened or reserved. This governs streams that
are opened using a <x:ref>HEADERS</x:ref> frame and streams that are reserved using
<x:ref>PUSH_PROMISE</x:ref>. An endpoint that receives an unexpected stream identifier
MUST respond with a <xref target="ConnectionErrorHandler">connection error</xref> of
type <x:ref>PROTOCOL_ERROR</x:ref>.
</t>
<t>