forked from httpwg/http2-spec
-
Notifications
You must be signed in to change notification settings - Fork 0
/
Copy pathdraft-ietf-httpbis-http2.xml
2679 lines (2479 loc) · 127 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.0">Hypertext Transfer Protocol version 2.0</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>Microsoft</organization>
<address>
<postal>
<street>3210 Porter Drive</street>
<city>Palo Alto</city>
<code>94043</code>
<country>US</country>
</postal>
<email>martin.thomson@skype.net</email>
</address>
</author>
<author initials="A." surname="Melnikov" fullname="Alexey Melnikov" role="editor">
<organization>Isode Ltd</organization>
<address>
<postal>
<street>5 Castle Business Village</street>
<street>36 Station Road</street>
<city>Hampton</city>
<region>Middlesex</region>
<code>TW12 2BX</code>
<country>UK</country>
</postal>
<email>Alexey.Melnikov@isode.com</email>
</address>
</author>
<date year="2013" />
<area>Applications</area>
<workgroup>HTTPbis Working Group</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). The HTTP/2.0 encapsulation enables more efficient use of
network resources and reduced perception of latency by allowing header field
compression and 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 format
or protocol. 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 and related documents can be found
at <eref target="http://tools.ietf.org/wg/httpbis/"/> (Wiki) and
<eref target="https://github.com/http2/http2-spec"/> (source code
and issues tracker).
</t>
<t>
The changes in this draft are summarized in <xref
target="changes.since.draft-ietf-httpbis-http2-02"/>.
</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
encapsulation (<xref target="HTTP-p1" x:fmt="," x:rel="#http.message"/>) is optimized for
implementation simplicity and accessibility, not application performance. As such it has
several characteristics that have a negative overall effect on application performance.
</t>
<t>
In particular, HTTP/1.0 only allows one request to be delivered at a time on a given
connection. HTTP/1.1 pipelining only partially addressed request concurrency, and is not
widely deployed. Therefore, clients that need to make many requests (as is common on the
Web) typically use multiple connections to a server in order to reduce perceived 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. This can result in excessive latency when multiple
requests are made on a 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 perceived
performance.
</t>
<t>
The resulting protocol is designed to have 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 title="Document Organization">
<t>
The HTTP/2.0 Specification is split into three parts: <xref target="starting">starting
HTTP/2.0</xref>, which covers how a HTTP/2.0 connection is initiated; <xref target="FramingLayer">a
framing layer</xref>, which multiplexes a single TCP connection into independent
frames of various types; and <xref target="HTTPLayer">an HTTP layer</xref>, which specifies the mechanism
for expressing HTTP interactions using the framing layer. While some of the
framing layer concepts are isolated from HTTP, building a generic framing layer
has not been a goal. The framing layer is 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 connection.
</t>
<t hangText="connection:">
A transport-level connection between two endpoints.
</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.0 connection,
consisting of a header and a variable-length sequence of bytes
structured according to the frame type.
</t>
<t hangText="message:">
A complete sequence of frames.
</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 connection.
</t>
<t hangText="connection error:">
An error on the HTTP/2.0 connection.
</t>
<t hangText="stream:">
A bi-directional flow of frames across a virtual channel within
the HTTP/2.0 connection.
</t>
<t hangText="stream error:">
An error on the individual HTTP/2.0 stream.
</t>
</list>
</t>
</section>
</section>
<section anchor="starting" title="Starting HTTP/2.0">
<t>HTTP/2.0 uses the same "http:" and "https:" URI schemes used by
HTTP/1.1. As a result, implementations processing requests for
target resource URIs like "http://example.org/foo" or
"https://example.com/bar" are required to first discover whether
the upstream server (the immediate peer to which the client wishes
to establish a connection) supports HTTP/2.0.</t>
<t>The means by which support for HTTP/2.0 is determined is different
for "http" and "https" URIs. Discovery for "https:" URIs is
described in <xref target="discover-https"/>. Discovery for
"http" URIs is described here.</t>
<section anchor="versioning" title="HTTP/2.0 Version Identification">
<t>
The protocol defined in this document is identified using the string "HTTP/2.0". This identification is used in the
HTTP/1.1 Upgrade header field, in the <xref target="TLSNPN">TLS-NPN</xref>
<cref>TBD</cref> field and other places where protocol identification is required.
</t>
<t>
Negotiating "HTTP/2.0" implies the use of the transport, security, framing and message
semantics described in this document.
</t>
<t>
<cref>Editor's Note: please remove the following text 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 "HTTP/2.0".
Until such an RFC exists, implementations MUST NOT identify themselves using "HTTP/2.0".
</t>
<t>
Examples and text throughout the rest of this document use "HTTP/2.0" 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 "-draft-" and the
corresponding draft number to the identifier before the separator ('/'). For example,
draft-ietf-httpbis-http2-03 is identified using the string "HTTP-draft-03/2.0".
</t>
<t>
Non-compatible experiments that are based on these draft versions MUST instead replace the
string "draft" with a different identifier. For example, an experimental implementation
of packet mood-based encoding based on draft-ietf-httpbis-http2-07 might identify itself
as "HTTP-emo-07/2.0". 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.0 for "http:" URIs">
<t>
A client that makes a request to an "http:" URI without prior knowledge about support for
HTTP/2.0 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.0.
</t>
<t>
For example:
</t>
<figure>
<artwork type="message/http; msgtype="request"" x:indent-with=" ">
GET /default.htm HTTP/1.1
Host: server.example.com
Connection: Upgrade
Upgrade: HTTP/2.0
</artwork>
</figure>
<t>
A server that does not support HTTP/2.0 can respond to the request as though the Upgrade
header field were absent:
</t>
<figure>
<artwork type="message/http; msgtype="responset"" x:indent-with=" ">
HTTP/1.1 200 OK
Content-length: 243
Content-type: text/html
...
</artwork>
</figure>
<t>
A server that supports HTTP/2.0 can accept the upgrade with a 101 (Switching Protocols)
status code. After the empty line that terminates the 101 response, the server can begin
sending HTTP/2.0 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: HTTP/2.0
[ HTTP/2.0 connection ...
</artwork>
</figure>
<t>
The first HTTP/2.0 frame sent by the server is a <xref target="SETTINGS">SETTINGS
frame</xref>. Upon receiving the 101 response, the client sends a <xref
target="ConnectionHeader">connection header</xref>, which includes a SETTINGS frame.
</t>
</section>
<section anchor="discover-https" title="Starting HTTP/2.0 for "https:" URIs">
<t>
A client that makes a request to an "https:" URI without prior knowledge about support for
HTTP/2.0 uses <xref target="RFC5246">TLS</xref> with <xref target="TLSNPN">TLS-NPN</xref>
extension. <cref>TBD, maybe ALPN</cref>
</t>
<t>
Once TLS negotiation is complete, both the client and the server send a <xref
target="ConnectionHeader">connection header</xref>.
</t>
</section>
<section anchor="known-http" title="Starting HTTP/2.0 with Prior Knowledge">
<t>
A client can learn that a particular server supports HTTP/2.0 by other means. A client
MAY immediately send HTTP/2.0 frames to a server that is known to support HTTP/2.0. This
only affects the resolution of "http:" URIs, servers supporting HTTP/2.0 are required to
support <xref target="TLSNPN">protocol negotiation in TLS</xref> for "https:" URIs.
</t>
<t>
Prior support for HTTP/2.0 is not a strong signal that a given server will support
HTTP/2.0 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>
<section anchor="FramingLayer" title="HTTP/2.0 Framing Layer">
<section title="Connection">
<t>
The HTTP/2.0 connection is an Application Level protocol running on top
of a TCP connection (<xref target="RFC0793"/>). The client is the TCP
connection initiator.
</t>
<t>HTTP/2.0 connections are persistent. That is, for best performance,
it is expected a clients will not close connections until it is
determined that no further communication with a server is necessary
(for example, when a user navigates away from a particular web page),
or until the server closes the connection.</t>
<t>Servers are encouraged to maintain open connections for as long as
possible, but are permitted to terminate idle connections if
necessary. When either endpoint chooses to close the transport-level
TCP connection, the terminating endpoint MUST first send a
<xref target="GOAWAY">GOAWAY</xref> frame so that both endpoints can
reliably determine whether previously sent frames have been processed
and gracefully complete or terminate any necessary remaining tasks.
</t>
</section>
<section anchor="ConnectionHeader" title="Connection Header">
<t>Upon establishment of a TCP connection and determination
that HTTP/2.0 will be used by both peers to communicate, each
endpoint MUST send a connection header as a final confirmation
and to establish the default parameters for the HTTP/2.0 connection.</t>
<t>
The client connection header is a sequence of 25 octets (in hex notation)
</t>
<figure><artwork type="inline">
464f4f202a20485454502f322e300d0a0d0a4241520d0a0d0a</artwork></figure>
<t>
(the string <spanx style="verb">FOO * HTTP/2.0\r\n\r\nBAR\r\n\r\n</spanx>) followed by a
<xref target="SETTINGS">SETTINGS frame</xref>. The client sends the client connection header
immediately upon receipt of a 101 Switching Protocols response (indicating a successful
upgrade), or after receiving a TLS Finished message from the server. If starting an
HTTP/2.0 connection with prior knowledge of server support for the protocol, the client
connection header is sent upon connection establishment.
</t>
<t>
<list>
<t>
The client connection header 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 header consists of just
a <xref target="SETTINGS">SETTINGS frame</xref> that MUST be the
first frame the server sends in the HTTP/2.0 connection.
</t>
<t>
To avoid unnecessary latency, clients are permitted to send
additional frames to the server immediately after sending the client
connection header, without waiting to receive the server connection header.
It is important to note, however, that the server connection header
SETTINGS frame might include parameters that necessarily alter
how a client is expected to communicate with the server. Upon
receiving the SETTINGS 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 header. A
<xref target="GOAWAY">GOAWAY frame</xref> MAY be omitted if it is
clear that the peer is not using HTTP/2.0.
</t>
</section>
<section title="Framing">
<t>Once the HTTP/2.0 connection is established, clients and servers
can begin exchanging frames.</t>
<section anchor="FrameHeader" title="Frame Header">
<t>
HTTP/2.0 frames share a common base format consisting of
an 8-byte header followed by 0 to 65535 bytes of data.
</t>
<figure title="Frame Header">
<artwork type="inline">
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
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Length (16) | Type (8) | Flags (8) |
+-+-------------+---------------+-------------------------------+
|R| Stream Identifier (31) |
+-+-------------------------------------------------------------+
| Frame Data (0...) ...
+---------------------------------------------------------------+
</artwork>
</figure>
<t>
The fields of the frame header are defined as:
<list style="hanging">
<t hangText="Length:">
The length of the frame data expressed as an unsigned 16-bit
integer. The 8 bytes of the frame header are not included
in this value.
</t>
<t hangText="Type:">
The 8-bit type of the frame. The frame type determines how the remainder of the
frame header and data are interpreted. Implementations MUST ignore unsupported
and unrecognized frame types.
</t>
<t hangText="Flags:">
An 8-bit field reserved for frame-type specific boolean flags.
<vspace blankLines="1"/>
The least significant bit (0x1) -- referred to generally as
the "FINAL flag" -- is defined for all frame types as an
indication that this frame is the last the endpoint will send
for the identified stream. Setting this flag causes the stream
to enter the <xref target="StreamHalfClose">half-closed state</xref>.
Implementations MUST process this flag for all frames whose
stream identifier field is not 0x0.
<vspace blankLines="1"/>
The remaining flags can be 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>
<t hangText="R:">
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>
<t hangText="Stream Identifier:">
A 31-bit stream identifier (see <xref target="StreamCreation"/>). A value 0 is
reserved for frames that are associated with the connection as a
whole as opposed to an individual stream.
</t>
</list>
</t>
<t>The structure and content of the remaining frame data is
dependent entirely on the frame type.</t>
</section>
<section anchor="FrameSize" title="Frame Size">
<t>Implementations with limited resources might not be capable of
processing large frame sizes. Such implementations MAY choose
to place additional limits on the maximum frame size. However,
all implementations MUST be capable of receiving and processing
frames containing at least 8192 octets of data.
<cref>Ed. Question: Does this minimum include the 8-byte header
or just the frame data?</cref></t>
<t>An implementation MUST terminate a stream immediately if it is
unable to process a frame due it's size. This is done by sending
an <xref target="RST_STREAM">RST_STREAM frame</xref> containing
the FRAME_TOO_LARGE error code.
</t>
<t>
<cref><eref target="https://github.com/http2/http2-spec/issues/28">Issue 28</eref>: Need
a way to signal the maximum frame size; no way to RST_STREAM on non-stream-related
frames.</cref>
</t>
</section>
</section>
<section title="Streams">
<t>
A "stream" is an independent, bi-directional sequence of frames
exchanged between the client and server within an HTTP/2.0 connection.
Streams have several important characteristics:
<list style="symbols">
<t>
Streams can be established and used unilaterally or shared by
either the client or server.
</t>
<t>
Streams can be rejected or cancelled by either endpoint.
</t>
<t>
Multiple types of frames can be sent by either endpoint within
a single stream.
</t>
<t>
The order in which frames are sent within a stream is
significant. Recipients are required to process frames
in the order they are received.
</t>
<t>
Streams optionally carry a set of name-value header pairs
that are expressed within the headers block of HEADERS+PRIORITY,
HEADERS, or PUSH_PROMISE frames.
</t>
<t>
A single HTTP/2.0 connection can contain multiple concurrently
active streams, with either endpoint interleaving frames from
multiple streams.
</t>
</list>
</t>
<section anchor="StreamCreation" title="Stream Creation">
<t>
There is no coordination or shared action between the client and
server required to create a stream. Rather, new streams are
established by sending a frame whose stream identifier field
references a previously unused stream identifier.
</t>
<t>
All streams are identified by an unsigned 31-bit integer. Streams
initiated by a client use odd numbered stream identifiers; those
initiated by the server use even numbered stream identifiers.
A stream identifier of zero MUST NOT be used to establish a new
stream.
</t>
<t>
The identifier of a newly established stream MUST be numerically
greater than all previously established streams from that endpoint
within the HTTP/2.0 connection, unless the identifier has been reserved
using a <xref target="PUSH_PROMISE">PUSH_PROMISE</xref> frame.
An endpoint that receives an unexpected stream identifier MUST
respond with a <xref target="ConnectionErrorHandler">connection error</xref> of type
PROTOCOL_ERROR.
</t>
<t>
A peer can limit the total number of concurrently active streams
using the SETTINGS_MAX_CONCURRENT_STREAMS parameters within a
SETTINGS frame. The maximum concurrent streams setting is specific
to each endpoint and applies only to the peer. That is, clients
specify the maximum number of concurrent streams the server can
initiate, and servers specify the maximum number of concurrent
streams the client can initiate. Peer endpoints MUST NOT
exceed this limit. All concurrently active
streams initiated by an endpoint, including streams that are
<xref target="StreamHalfClose">half-open</xref> in any direction,
count toward that endpoint's limit.
</t>
<t>
Stream identifiers cannot be reused within a connection. Long-lived
connections can cause an endpoint to exhaust the available range of stream
identifiers. An endpoint that is unable to establish a new stream identifier can
establish a new connection for any new streams.
</t>
<t>
Either endpoint can request the early termination of an unwanted
stream by sending an <xref target="StreamErrorHandler">RST_STREAM
frame</xref> with an error code of either REFUSED_STREAM (if no
frames have been processed) or CANCEL (if at least one frame has
been processed). Such termination might not take effect immediately
as the peer might have sent additional frames on the stream prior
to receiving the termination request.
</t>
</section>
<section anchor="StreamPriority" title="Stream priority">
<t>
The endpoint establishing a new stream can assign a priority for
the stream. Priority is represented as an unsigned 31-bit integer.
0 represents the highest priority and 2<x:sup>31</x:sup>-1 represents
the lowest priority.
</t>
<t>
The purpose of this value is to allow the initiating
endpoint to request that frames for the stream be processed with
higher priority relative to any other concurrently active
streams. That is, if an endpoint receives interleaved frames
for multiple streams, the endpoint ought to make a best-effort
attempt at processing frames for higher priority streams before
processing those for lower priority streams.
</t>
<t>
Explicitly setting the priority for a stream does not
guarantee any particular processing order for the stream
relative to any other stream. Nor is there is any mechanism
provided by which the initiator of a stream can force or require
a receiving endpoint to process frames from one stream before
processing frames from another.
</t>
</section>
<section anchor="StreamHalfClose" title="Stream half-close">
<t>
When an endpoint sends a frame for a stream with the FINAL flag
set, the stream is considered to be half-closed for that endpoint.
Subsequent frames MUST NOT be sent by that endpoint for the half
closed stream for the remaining duration of the HTTP/2.0 connection.
When both endpoints have sent frames with the FINAL flag set, the
stream is considered to be fully closed.
</t>
<t>
If an endpoint receives additional frames for a stream that was
previously half-closed by the sending peer, the recipient MUST
respond with a <xref target="StreamErrorHandler">stream error</xref>
of type STREAM_CLOSED.
</t>
<t>
An endpoint that has not yet half-closed a stream by sending the
FINAL flag can continue sending frames on the stream.
</t>
<t>
It is not necessary for an endpoint to half-close a stream
for which it has not sent any frames. This allows endpoints to
use fully unidirectional streams that do not require explicit
action or acknowledgement from the receiver.
</t>
</section>
<section anchor="StreamClose" title="Stream close">
<t>
Streams can be terminated in the following ways:
<list style="hanging">
<t hangText="Normal termination:">
Normal stream termination occurs when both client and server have half-closed the
stream by sending a frame containing a <xref target="FrameHeader">FINAL flag</xref>.
</t>
<t hangText="Half-close on unidirectional stream:">
A stream that only has frames sent in one direction can be tentatively considered to
be closed once a frame containing a FINAL flag is sent. The active sender on the
stream MUST be prepared to receive frames after closing the stream.
</t>
<t hangText="Abrupt termination:">
Either peer can send a RST_STREAM control frame at any time to terminate an
active stream. RST_STREAM contains an error code to indicate the reason for
termination. A RST_STREAM indicates that the sender will transmit no further data
on the stream and that the receiver is advised to cease transmission on it.
<vspace blankLines="1"/>
The sender of a RST_STREAM frame MUST allow for frames that have already been sent
by the peer prior to the RST_STREAM being processed. If in-transit frames alter
connection state, these frames cannot be safely discarded. See <xref
target="StreamErrorHandler">Stream Error Handling</xref> for more details.
</t>
<t hangText="TCP connection teardown:">
If the TCP connection is torn down while un-closed streams
exist, then the endpoint MUST assume that the stream was abnormally interrupted and
may be incomplete.
</t>
</list>
</t>
</section>
</section>
<section title="Error Handling">
<t>
HTTP/2.0 framing permits two classes of error:
<list style="symbols">
<t>
An error condition that renders the entire connection unusable is a connection error.
</t>
<t>
An error in an individual stream is a stream error.
</t>
</list>
</t>
<section anchor="ConnectionErrorHandler" title="Connection Error Handling">
<t>
A connection error is any error which prevents further processing of the framing layer or
which corrupts any connection state.
</t>
<t>
An endpoint that encounters a connection error MUST first send a <xref
target="GOAWAY">GOAWAY</xref> frame with the stream identifier of the last stream that
it successfully received from its peer. The GOAWAY frame includes an error code that
indicates why the connection is terminating. After sending the GOAWAY frame, the endpoint
MUST close the TCP connection.
</t>
<t>
It is possible that the GOAWAY will not be reliably received by the receiving endpoint.
In the event of a connection error, GOAWAY only provides a best-effort attempt to
communicate with the peer about why the connection is being terminated.
</t>
<t>
An endpoint can end a connection at any time. In particular, an endpoint MAY choose to
treat a stream error as a connection error if the error is recurrent. Endpoints SHOULD
send a GOAWAY frame when ending a connection, as long as circumstances permit it.
</t>
</section>
<section anchor="StreamErrorHandler" title="Stream Error Handling">
<t>
A stream error is an error related to a specific stream identifier that does not affect
processing of other streams at the framing layer.
</t>
<t>
An endpoint that detects a stream error sends a <xref
target="RST_STREAM">RST_STREAM</xref> frame that contains the stream identifier of the
stream where the error occurred. The RST_STREAM frame includes an error code that
indicates the type of error.
</t>
<t>
A RST_STREAM is the last frame that an endpoint can send on a stream. The peer that
sends the RST_STREAM frame MUST be prepared to receive any frames that were sent or
enqueued for sending by the remote peer. These frames can be ignored, except where they
modify connection state (such as that for header compression).
</t>
<t>
Normally, an endpoint SHOULD NOT send more than one RST_STREAM frame for any stream. However, an endpoint
MAY send additional RST_STREAM frames if it receives frames on a closed stream after
more than a round trip time. This behavior is permitted to deal with misbehaving
implementations.
</t>
<t>
An endpoint MUST NOT send a RST_STREAM in response to an RST_STREAM frame, to avoid looping.
</t>
</section>
<section anchor="ErrorCodes" title="Error Codes">
<t>
Error codes are 32-bit fields that are used in RST_STREAM and GOAWAY frames to convey
the reasons for the stream or connection error.
</t>
<t>
Error codes share a common code space. Some error codes only apply to specific
conditions and have no defined semantics in certain frame types.
</t>
<t>
The following error codes are defined:
<list style="hanging">
<t hangText="NO_ERROR (0):">
The associated condition is not as a result of an error. For example, a GOAWAY
might include this code to indicate graceful shutdown of a connection.
</t>
<t hangText="PROTOCOL_ERROR (1):">
The endpoint detected an unspecific protocol error. This error is for use when a more
specific error code is not available.
</t>
<t hangText="INTERNAL_ERROR (2):">
The endpoint encountered an unexpected internal error.
</t>
<t hangText="FLOW_CONTROL_ERROR (3):">
The endpoint detected that its peer violated the flow control protocol.
</t>
<t hangText="INVALID_STREAM (4):">
The endpoint received a frame for an inactive stream.
</t>
<t hangText="STREAM_CLOSED (5):">
The endpoint received a frame after a stream was half-closed.
</t>
<t hangText="FRAME_TOO_LARGE (6):">
The endpoint received a frame that was larger than the maximum size that it
supports.
</t>
<t hangText="REFUSED_STREAM (7):">
The endpoint is refusing the stream before processing its payload.
</t>
<t hangText="CANCEL (8):">
Used by the creator of a stream to indicate that the stream is no longer needed.
</t>
</list>
</t>
</section>
</section>
<section anchor="flowcontrol" title="Stream Flow Control">
<t>
Using streams for multiplexing introduces contention over use of the TCP connection,
resulting in blocked streams. A flow control
scheme ensures that streams on the same connection do not destructively interfere with each other.
</t>
<t>
HTTP/2.0 provides for flow control through use of the
<xref target="WINDOW_UPDATE">WINDOW_UPDATE</xref> frame type.
</t>
<section anchor="fc-principles" title="Flow Control Principles">
<t>
Experience with TCP congestion control has shown that algorithms can evolve over time to
become more sophisticated without requiring protocol changes. TCP congestion control
and its evolution is clearly different from HTTP/2.0 flow control, though the evolution
of TCP congestion control algorithms shows that a similar approach could be feasible for
HTTP/2.0 flow control.
</t>
<t>
HTTP/2.0 stream flow control aims to allow for future improvements to flow control
algorithms without requiring protocol changes. Flow control in HTTP/2.0 has the
following characteristics:
<list style="numbers">
<t>
Flow control is hop-by-hop, not end-to-end.
</t>
<t>
Flow control is based on window update messages. Receivers advertise how many
octets they are prepared to receive on a stream. This is a credit-based scheme.
</t>
<t>
Flow control is directional with overall control provided by the receiver. A
receiver MAY choose to set any window size that it desires for each stream and for
the entire connection. A sender MUST respect flow control limits imposed by a
receiver. Clients, servers and intermediaries all independently advertise their
flow control preferences as a receiver and abide by the flow control limits set by
their peer when sending.
</t>
<t>
The initial value for the flow control window is 65536 bytes for both new streams
and the overall connection.
</t>
<t>
The frame type determines whether flow control applies to a frame. Of the frames
specified in this document, only data frames are subject to flow control; all other
frame types do not consume space in the advertised flow control window. This
ensures that important control frames are not blocked by flow control.
</t>
<t>
Flow control can be disabled by a receiver. A receiver can choose to either disable
flow control for a stream or connection by declaring an infinite flow control limit.
</t>
<t>
HTTP/2.0 standardizes only the format of the <xref target="WINDOW_UPDATE">window
update message</xref>. This does not stipulate how a receiver decides when to send
this message or the value that it sends. Nor does it specify how a sender chooses
to send packets. Implementations are able to select any algorithm that suits their
needs.
</t>
</list>
</t>
<t>
Implementations are also responsible for managing how requests and responses are sent
based on priority; choosing how to avoid head of line blocking for requests; and
managing the creation of new streams. Algorithm choices for these could interact with
any flow control algorithm.
</t>
</section>
<section title="Appropriate Use of Flow Control">
<t>
Flow control is defined to protect endpoints (client, server or intermediary) that are
operating under resource constraints. For example, a proxy needs to share memory between many
connections, and also might have a slow upstream connection and a fast downstream one.
Flow control addresses cases where the receiver is unable process data on
one stream, yet wants to continue to process other streams in the same connection.
</t>
<t>
Deployments that do not require this capability SHOULD disable flow control for data
that is being received. Note that flow control cannot be disabled for sending.
Sending data is always subject to the flow control window advertised by the receiver.
</t>
<t>
Deployments with constrained resources (for example, memory) MAY employ flow control to
limit the amount of memory a peer can consume. Note, however, that this can lead to suboptimal use of
available network resources if flow control is enabled without knowledge of the
bandwidth-delay product (see <xref target="RFC1323"/>).
</t>
<t>
Even with full awareness of the current bandwidth-delay product, implementation of flow control
is difficult. However, it can ensure that constrained resources are protected without any
reduction in connection utilization.
</t>
</section>
</section>
<section anchor="HeaderBlock" title="Header Blocks">
<t>
The header block is found in the HEADERS, HEADERS+PRIORITY and PUSH_PROMISE frames. The
header block consists of a set of header fields, which are name-value pairs. Headers
are compressed using black magic.
</t>
<t>
Compression of header fields is a work in progress, as is the format of this block.
</t>
</section>
<section title="Frame Types" anchor="frame-types">
<t>
This specification defines a number of frame types,
each identified by a unique 8-bit type code. Each frame
type serves a distinct purpose either in the establishment and
management of the connection as a whole, or of individual streams.
</t>
<t>
The transmission of specific frame types can alter the state of
a connection. If endpoints fail to maintain a synchronized view
of the connection state, successful communication within the connection
will no longer be possible. Therefore, it is important that endpoints
have a shared comprehension of how the state is affected by the use
any given frame. Accordingly, while it is expected that new frame
types will be introduced by extensions to this protocol, only frames
defined by this document are permitted to alter the connection state.
</t>
<section anchor="DataFrames" title="DATA Frames">
<t>
DATA frames (type=0x0) convey arbitrary, variable-length
sequences of octets associated with a stream. One or more
DATA frames are used, for instance, to carry HTTP request
or response message payloads.
</t>
<t>
The DATA frame does not define any type-specific flags.
</t>
<t>
DATA frames MUST be associated with a stream. If a DATA frame is
received whose stream identifier field is 0x0, the recipient MUST
respond with a <xref target="ConnectionErrorHandler">connection error</xref>
of type PROTOCOL_ERROR.
</t>
</section>
<section anchor="HEADERS_PRIORITY" title="HEADERS+PRIORITY">
<t>
The HEADERS+PRIORITY frame (type=0x1) allows the sender to
set header fields and stream priority at the same time.
</t>
<figure title="HEADERS+PRIORITY Frame Payload">
<artwork type="inline">
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
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|X| Priority (31) |
+-+-------------------------------------------------------------+
| Header Block (*) ...
+---------------------------------------------------------------+
</artwork>
</figure>
<t>
The HEADERS+PRIORITY frame is identical to the <xref target="HEADERS">HEADERS
frame</xref>, preceded by a single reserved bit and a 31-bit priority; see
<xref target="StreamPriority"/>.
</t>
<t>HEADERS+PRIORITY uses exactly the same flags as the HEADERS frame.
See <xref target="HEADERS">HEADERS frame</xref> for any flags.</t>
<t>
HEADERS+PRIORITY frames MUST be associated with a stream. If a
HEADERS+PRIORITY frame is received whose stream
identifier field is 0x0, the recipient MUST respond with a