forked from httpwg/http2-spec
-
Notifications
You must be signed in to change notification settings - Fork 0
/
Copy pathdraft-ietf-httpbis-http2.xml
5096 lines (4881 loc) · 259 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" ?>
<!DOCTYPE rfc [
<!ENTITY mdash "—">
]>
<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 (HTTP/2)</title>
<author initials="M." surname="Belshe" fullname="Mike Belshe">
<organization>BitGo</organization>
<address>
<email>mike@belshe.com</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>331 E Evelyn Street</street>
<city>Mountain View</city>
<region>CA</region>
<code>94041</code>
<country>United States</country>
</postal>
<email>martin.thomson@gmail.com</email>
</address>
</author>
<date year="2015" month="May"/>
<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 semantics of the Hypertext
Transfer Protocol (HTTP), referred to as HTTP version 2 (HTTP/2). 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 exchanges on the same connection. It also introduces unsolicited push of
representations from servers to clients.
</t>
<t>
This specification is an alternative to, but does not obsolete, the HTTP/1.1 message syntax.
HTTP's existing semantics remain unchanged.
</t>
</abstract>
</front>
<middle>
<section anchor="intro" title="Introduction">
<t>
The Hypertext Transfer Protocol (HTTP) is a wildly successful protocol. However, the way
HTTP/1.1 uses the underlying transport (<xref target="RFC7230" x:fmt=","
x:rel="#connection.management"/>) has several characteristics that have a negative overall
effect on application performance today.
</t>
<t>
In particular, HTTP/1.0 allowed only one request to be outstanding at a time on a given TCP
connection. HTTP/1.1 added request pipelining, but this only partially addressed request
concurrency and still suffers from head-of-line blocking. Therefore, HTTP/1.0 and HTTP/1.1
clients that need to make many requests use multiple connections to a server in order to
achieve concurrency and thereby reduce latency.
</t>
<t>
Furthermore, HTTP header fields are often repetitive and verbose, causing unnecessary
network traffic as well as causing the initial <xref target="TCP">TCP</xref> congestion
window to quickly fill. This can result in excessive latency when multiple requests are
made on a new TCP connection.
</t>
<t>
HTTP/2 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 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 lead to better utilization of available network
capacity.
</t>
<t>
Finally, HTTP/2 also enables more efficient 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
type serves a different 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 exchange
associated with its own <xref target="StreamsLayer">stream</xref>. Streams are largely
independent of each other, so a blocked or stalled request or response does not prevent
progress on other streams.
</t>
<t>
Flow control and prioritization ensure that it is possible to efficiently 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 streams 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 data to a
client 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 a separate stream.
</t>
<t>
Because HTTP header fields used in a connection can contain large amounts of redundant
data, frames that contain them are <xref target="HeaderBlock">compressed</xref>. This has
especially advantageous impact upon request sizes in the common case, allowing many
requests to be compressed into one packet.
</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">frame</xref> and <xref
target="StreamsLayer">stream</xref> layers describe the way HTTP/2 frames are
structured and formed into multiplexed streams.
</t>
<t>
<xref target="FrameTypes">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, this
specification does not define a completely generic frame layer. The frame and stream
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 that initiates an HTTP/2 connection. Clients send HTTP requests and
receive HTTP responses.
</t>
<t hangText="connection:">
A transport-layer 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 octets 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 that accepts an HTTP/2 connection. Servers receive HTTP requests and
send HTTP responses.
</t>
<t hangText="stream:">
A bidirectional flow of frames within the HTTP/2 connection.
</t>
<t hangText="stream error:">
An error on the individual HTTP/2 stream.
</t>
</list>
</t>
<t>
Finally, the terms "gateway", "intermediary", "proxy", and "tunnel" are defined in <xref
target="RFC7230" x:fmt="of" x:rel="#intermediaries"/>. Intermediaries act as both client
and server at different times.
</t>
<t>
The term "payload body" is defined in <xref target="RFC7230" x:fmt="of"
x:rel="#message.body"/>.
</t>
</section>
</section>
<section anchor="starting" title="Starting HTTP/2">
<t>
An HTTP/2 connection is an application-layer 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 has two identifiers.
<list style="symbols">
<x:lt>
<t>
The string "h2" identifies the protocol where HTTP/2 uses <xref
target="TLS12">Transport Layer Security (TLS)</xref>. This identifier is used in the <xref
target="TLS-ALPN">TLS application-layer protocol negotiation (ALPN) extension</xref>
field and in any place where HTTP/2 over TLS is identified.
</t>
<t>
The "h2" string is serialized into an ALPN protocol identifier as the two-octet
sequence: 0x68, 0x32.
</t>
</x:lt>
<x:lt>
<t>
The string "h2c" identifies the protocol where HTTP/2 is run over cleartext TCP.
This identifier is used in the HTTP/1.1 Upgrade header field and in any place where
HTTP/2 over TCP is identified.
</t>
<t>
The "h2c" string is reserved from the ALPN identifier space but describes a
protocol that does not use TLS.
</t>
</x:lt>
</list>
</t>
<t>
Negotiating "h2" or "h2c" implies the use of the transport, security, framing, and message
semantics described in this document.
</t>
</section>
<section anchor="discover-http" title="Starting HTTP/2 for "http" URIs">
<t>
A client that makes a request for an "http" URI without prior knowledge about support for
HTTP/2 on the next hop uses the HTTP Upgrade mechanism (<xref target="RFC7230" x:fmt="of"
x:rel="#header.upgrade"/>). The client does so by making an HTTP/1.1 request that
includes an Upgrade header field with the "h2c" token. Such an 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 / HTTP/1.1
Host: server.example.com
Connection: Upgrade, HTTP2-Settings
Upgrade: h2c
HTTP2-Settings: <base64url encoding of HTTP/2 SETTINGS payload>
]]></artwork>
</figure>
<t>
Requests that contain a payload body MUST be sent in their entirety before the client can
send HTTP/2 frames. This means that a large request 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, an OPTIONS
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 MUST ignore an "h2" token in an Upgrade header field. Presence of a token with
"h2" implies HTTP/2 over TLS, which is instead negotiated as described in <xref
target="discover-https"/>.
</t>
<t>
A server that supports HTTP/2 accepts 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>
<preamble>
For example:
</preamble>
<artwork type="message/http; msgtype="response"" x:indent-with=" ">
HTTP/1.1 101 Switching Protocols
Connection: Upgrade
Upgrade: h2c
[ HTTP/2 connection ...
</artwork>
</figure>
<t>
The first HTTP/2 frame sent by the server MUST be a server connection preface
(<xref target="ConnectionHeader"/>) consisting of a <x:ref>SETTINGS</x:ref>
frame (<xref target="SETTINGS"/>). Upon receiving the 101 response, the client MUST send 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 a stream identifier of 1
(see <xref target="StreamIdentifiers"/>) with <xref target="pri-default">default priority
values</xref>. Stream 1 is implicitly "half-closed" from the client toward the server
(see <xref target="StreamStates"/>), 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="vbare">HTTP2-Settings</spanx> header field is a connection-specific header field
that includes parameters that govern the HTTP/2 connection, provided in anticipation of
the server accepting the request to upgrade.
</t>
<figure>
<artwork type="abnf" x:indent-with=" "><![CDATA[
HTTP2-Settings = token68
]]></artwork>
</figure>
<t>
A server MUST NOT upgrade the connection to HTTP/2 if this header field is not present
or if more than one is present. A server MUST NOT send this header field.
</t>
<t>
The content of the <spanx style="vbare">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="RFC7235" x:fmt="of" x:rel="#challenge.and.response"/>.
</t>
<t>
Since the upgrade is only intended to apply to the immediate connection, a client
sending the <spanx style="vbare">HTTP2-Settings</spanx> header field MUST also send <spanx
style="verb">HTTP2-Settings</spanx> as a connection option in the <spanx
style="vbare">Connection</spanx> header field to prevent it from being forwarded (see
<xref target="RFC7230" x:fmt="of" x:rel="#header.connection"/>).
</t>
<t>
A server decodes and interprets these values as it would any other
<x:ref>SETTINGS</x:ref> frame. Explicit <xref target="SettingsSync">acknowledgement of
these settings</xref> is not necessary, since a 101 response serves as implicit
acknowledgement. Providing these values in the upgrade request gives a client an
opportunity to provide 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 uses <xref target="TLS12">TLS</xref> with
the <xref target="TLS-ALPN">application-layer protocol negotiation (ALPN)
extension</xref>.
</t>
<t>
HTTP/2 over TLS uses the "h2" protocol identifier. The "h2c" protocol identifier MUST NOT
be sent by a client or selected by a server; the "h2c" protocol identifier describes a
protocol that does not use TLS.
</t>
<t>
Once TLS negotiation is complete, both the client and the server MUST 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="ALT-SVC"/> describes a mechanism for advertising this capability.
</t>
<t>
A client MUST send the <xref target="ConnectionHeader">connection preface</xref> and
then MAY immediately send HTTP/2 frames to such a server; servers can identify these
connections by the presence of the connection preface. This only affects the
establishment of HTTP/2 connections over cleartext TCP; implementations that support
HTTP/2 over TLS MUST use <xref target="TLS-ALPN">protocol negotiation in TLS</xref>.
</t>
<t>
Likewise, the server MUST send a <xref target="ConnectionHeader">connection preface</xref>.
</t>
<t>
Without additional information, prior support for HTTP/2 is not a strong signal that a
given server will support HTTP/2 for future connections. For example, it is possible for
server configurations to change, for configurations to differ between instances in
clustered servers, or for network conditions to change.
</t>
</section>
<section anchor="ConnectionHeader" title="HTTP/2 Connection Preface">
<t>
In HTTP/2, each endpoint is required to send a connection preface as a final confirmation
of the protocol in use and to establish the initial settings for the HTTP/2 connection.
The client and server each send a different connection preface.
</t>
<t>
The client connection preface starts with a sequence of 24 octets, which in hex notation
is:
</t>
<figure>
<artwork type="inline" x:indent-with=" "><![CDATA[
0x505249202a20485454502f322e300d0a0d0a534d0d0a0d0a
]]></artwork>
</figure>
<t>
That is, the connection preface starts with the string <spanx style="verb">PRI *
HTTP/2.0\r\n\r\nSM\r\n\r\n</spanx>). This sequence
MUST be followed by a <x:ref>SETTINGS</x:ref> frame (<xref target="SETTINGS"/>), which
MAY be empty. 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>
<x:note>
<t>
<x:h>Note:</x:h>
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>
</x:note>
<t>
The server connection preface consists of a potentially empty <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>
The <x:ref>SETTINGS</x:ref> frames received from a peer as part of the connection preface
MUST be acknowledged (see <xref target="SettingsSync"/>) after sending the connection
preface.
</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.
In some configurations, it is possible for the server to transmit <x:ref>SETTINGS</x:ref>
before the client sends additional frames, providing an opportunity to avoid this issue.
</t>
<t>
Clients and servers MUST treat an invalid connection preface as a <xref
target="ConnectionErrorHandler">connection error</xref> of type
<x:ref>PROTOCOL_ERROR</x:ref>. A <x:ref>GOAWAY</x:ref> frame (<xref target="GOAWAY"/>)
MAY be omitted in this case, since an invalid preface indicates 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 a fixed 9-octet header followed by a variable-length payload.
</t>
<figure anchor="FrameLayout" title="Frame Layout">
<artwork type="inline"><![CDATA[
+-----------------------------------------------+
| Length (24) |
+---------------+---------------+---------------+
| 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="Length:">
<t>
The length of the frame payload expressed as an unsigned 24-bit integer. Values
greater than 2<x:sup>14</x:sup> (16,384) MUST NOT be sent unless the receiver has
set a larger value for <x:ref>SETTINGS_MAX_FRAME_SIZE</x:ref>.
</t>
<t>
The 9 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 the format and semantics of
the frame. Implementations MUST ignore and discard any frame that has a type that
is unknown.
</t>
</x:lt>
<x:lt hangText="Flags:">
<t>
An 8-bit field reserved for boolean flags specific to the frame type.
</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 (0x0) 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 (0x0) when sending and MUST be ignored when receiving.
</t>
</x:lt>
<x:lt hangText="Stream Identifier:">
<t>
A stream identifier (see <xref target="StreamIdentifiers"/>) expressed as an
unsigned 31-bit integer. The value 0x0 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 size of a frame payload is limited by the maximum size that a receiver advertises in
the <x:ref>SETTINGS_MAX_FRAME_SIZE</x:ref> setting. This setting can have any value
between 2<x:sup>14</x:sup> (16,384) and 2<x:sup>24</x:sup>-1 (16,777,215) octets,
inclusive.
</t>
<t>
All implementations MUST be capable of receiving and minimally processing frames up to
2<x:sup>14</x:sup> octets in length, plus the 9-octet <xref target="FrameHeader">frame
header</xref>. The size of the frame header is not included when describing frame sizes.
</t>
<x:note>
<t>
<x:h>Note:</x:h> Certain frame types, such as <xref target="PING">PING</xref>, impose additional limits
on the amount of payload data allowed.
</t>
</x:note>
<t>
An endpoint MUST send an error code of <x:ref>FRAME_SIZE_ERROR</x:ref> if a frame exceeds the size
defined in <x:ref>SETTINGS_MAX_FRAME_SIZE</x:ref>, exceeds any limit defined for the frame type,
or is too small to contain mandatory frame data. 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 frame with a stream identifier of 0.
</t>
<t>
Endpoints are not obligated to use all available space in a frame. Responsiveness can be
improved by using frames that are smaller than the permitted maximum size. Sending large
frames can result in delays in sending time-sensitive frames (such as
<x:ref>RST_STREAM</x:ref>, <x:ref>WINDOW_UPDATE</x:ref>, or <x:ref>PRIORITY</x:ref>),
which, if blocked by the transmission of a large frame, could affect performance.
</t>
</section>
<section anchor="HeaderBlock" title="Header Compression and Decompression">
<t>
Just as in HTTP/1, a header field in HTTP/2 is a name with one or more associated values.
Header fields are used within HTTP request and response messages as well as in server push operations
(see <xref target="PushResources" />).
</t>
<t>
Header lists are collections of zero or more header fields. When transmitted over a
connection, a header list 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>
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 and then
decompresses the block to reconstruct the header list.
</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 compression is stateful. One compression context and one decompression context are
used for the entire connection. A decoding error in a header block MUST be treated as a
<xref target="ConnectionErrorHandler">connection error</xref> of type
<x:ref>COMPRESSION_ERROR</x:ref>.
</t>
<t>
Each header block is processed as a discrete unit.
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 has 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 has the END_HEADERS flag set. This allows a header block to be logically
equivalent to a single frame.
</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 needs to 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, bidirectional sequence of 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 on a stream is significant. Recipients process frames
in the order they are received. In particular, the order of <x:ref>HEADERS</x:ref>
and <x:ref>DATA</x:ref> frames is semantically significant.
</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[
+--------+
send PP | | recv PP
,--------| idle |--------.
/ | | \
v +--------+ v
+----------+ | +----------+
| | | send H / | |
,------| reserved | | recv H | reserved |------.
| | (local) | | | (remote) | |
| +----------+ v +----------+ |
| | +--------+ | |
| | recv ES | | send ES | |
| send H | ,-------| open |-------. | recv H |
| | / | | \ | |
| v v +--------+ v v |
| +----------+ | +----------+ |
| | half | | | half | |
| | closed | | send R / | closed | |
| | (remote) | | recv R | (local) | |
| +----------+ | +----------+ |
| | | | |
| | send ES / | recv ES / | |
| | send R / v send R / | |
| | recv R +--------+ recv R | |
| send R / `----------->| |<-----------' send R / |
| recv R | closed | recv R |
`----------------------->| |<----------------------'
+--------+
send: endpoint sends this frame
recv: endpoint receives this frame
H: HEADERS frame (with implied CONTINUATIONs)
PP: PUSH_PROMISE frame (with implied CONTINUATIONs)
ES: END_STREAM flag
R: RST_STREAM frame
]]>
</artwork>
</figure>
<t>
Note that this diagram shows stream state transitions and the frames and flags that affect
those transitions only. In this regard, <x:ref>CONTINUATION</x:ref> frames do not result
in state transitions; they are effectively part of the <x:ref>HEADERS</x:ref> or
<x:ref>PUSH_PROMISE</x:ref> that they follow. For the purpose of state transitions, the
END_STREAM flag is processed as a separate event to the frame that bears it; a
<x:ref>HEADERS</x:ref> frame with the END_STREAM flag set can cause two state transitions.
</t>
<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.
</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 on another stream reserves the idle
stream that is identified 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 on another stream reserves an idle
stream that is identified for later use. The stream state for the reserved
stream transitions to "reserved (remote)".
</t>
<t>
Note that the <x:ref>PUSH_PROMISE</x:ref> frame is not sent on the idle
stream but references the newly reserved stream in the Promised Stream ID
field.
</t>
</list>
</t>
<t>
Receiving any frame other than <x:ref>HEADERS</x:ref> or <x:ref>PRIORITY</x:ref> on
a stream in this state 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 (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 any type of frame other than <x:ref>HEADERS</x:ref>,
<x:ref>RST_STREAM</x:ref>, or <x:ref>PRIORITY</x:ref> in this state.
</t>
<t>
A <x:ref>PRIORITY</x:ref> or <x:ref>WINDOW_UPDATE</x:ref> frame MAY be received in
this state. Receiving any type of frame other than <x:ref>RST_STREAM</x:ref>,
<x:ref>PRIORITY</x:ref>, or <x:ref>WINDOW_UPDATE</x:ref> on a stream in this state
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 type of frame other than
<x:ref>RST_STREAM</x:ref>, <x:ref>WINDOW_UPDATE</x:ref>, or <x:ref>PRIORITY</x:ref>
in this state.
</t>
<t>
Receiving any type of frame other than <x:ref>HEADERS</x:ref>,
<x:ref>RST_STREAM</x:ref>, or <x:ref>PRIORITY</x:ref> on a stream in this state 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)".
</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 other than <x:ref>WINDOW_UPDATE</x:ref>, <x:ref>PRIORITY</x:ref>, and
<x:ref>RST_STREAM</x:ref>.
</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.
</t>
<t>
An endpoint can receive any type of frame in this state. Providing flow-control
credit using <x:ref>WINDOW_UPDATE</x:ref> frames is necessary to continue receiving
flow-controlled frames. In this state, a receiver can ignore <x:ref>WINDOW_UPDATE</x:ref> frames,
which might arrive for a short period after a frame bearing the
END_STREAM flag is sent.
</t>
<t>
<x:ref>PRIORITY</x:ref> frames received in this state are used to reprioritize
streams that depend on the identified stream.
</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.
</t>
<t>
If an endpoint receives additional frames, other
than <x:ref>WINDOW_UPDATE</x:ref>, <x:ref>PRIORITY</x:ref>, or
<x:ref>RST_STREAM</x:ref>, for a stream that is in this state, it MUST respond with a <xref
target="StreamErrorHandler">stream error</xref> of type
<x:ref>STREAM_CLOSED</x:ref>.
</t>
<t>
A stream that is "half-closed (remote)" can be used by the endpoint to send frames
of any type. In this state, the endpoint continues to observe advertised <xref
target="FlowControl">stream-level flow-control limits</xref>.
</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 other than <x:ref>PRIORITY</x:ref> on a closed
stream. An endpoint that receives any frame other than <x:ref>PRIORITY</x:ref>
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 frame with the END_STREAM flag set MUST treat that as a <xref
target="ConnectionErrorHandler">connection error</xref> of type
<x:ref>STREAM_CLOSED</x:ref>, unless the frame is permitted as described below.
</t>