Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Integers #877

Merged
merged 11 commits into from Oct 30, 2017
Merged

Integers #877

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
11 commits
Select commit Hold shift + click to select a range
473d9e7
Transport integer encoding proposal
martinthomson Oct 13, 2017
06112c6
Review comments
martinthomson Oct 15, 2017
66c5285
Add a length field to ACK
martinthomson Oct 15, 2017
fd78bcc
Use a count rather than a length
martinthomson Oct 17, 2017
5c120d0
Subtract one from ranges
martinthomson Oct 19, 2017
7be15c0
Editorial fixup
martinthomson Oct 19, 2017
12d0946
Maximal change for HTTP integer encoding
martinthomson Oct 18, 2017
cdae8c3
Missed a few fixed-size integers
martinthomson Oct 18, 2017
8aaa5e0
More fixed-size integer residue
martinthomson Oct 19, 2017
89c9963
Redundant duplication is unnecessary
MikeBishop Oct 30, 2017
149b2b8
Merge remote-tracking branch 'origin/master' into integers
MikeBishop Oct 30, 2017
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
118 changes: 71 additions & 47 deletions draft-ietf-quic-http.md
View file
Open in desktop
Expand Up @@ -85,6 +85,9 @@ defined in {{!RFC2119}}.
Field definitions are given in Augmented Backus-Naur Form (ABNF), as defined in
{{!RFC5234}}.

This document uses the variable-length integer encoding from
{{QUIC-TRANSPORT}}.


# QUIC Advertisement

Expand Down Expand Up @@ -355,21 +358,21 @@ allows a server to fulfill promises in the order that best suits its needs.
The server push response is conveyed on a push stream. A push stream is a
server-initiated stream. A push stream includes a header (see
{{fig-push-stream-header}}) that identifies the PUSH_PROMISE that it fulfills.
This header consists of a 32-bit Push ID, which identifies a server push (see
{{frame-push-promise}}).
This header consists of a Push ID, encoded as a variable-length integer. The
Push ID identifies a server push (see {{frame-push-promise}}).

~~~~~
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
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Push ID (32) |
| Push ID (i) |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
~~~~~
{: #fig-push-stream-header title="Push Stream Header"}

A push stream always starts with a 32-bit Push ID. A client MUST treat
receiving a push stream that contains fewer than 4 octets as a connection error
of type HTTP_MALFORMED_PUSH.
A push stream always starts with a Push ID. A client MUST treat receiving a
push stream that contains a truncated variable-length integer as a connection
error of type HTTP_MALFORMED_PUSH.

A server SHOULD use Push IDs sequentially, starting at 0. A client uses the
MAX_PUSH_ID frame ({{frame-max-push-id}}) to limit the number of pushes that a
Expand Down Expand Up @@ -415,6 +418,9 @@ All frames have the following format:
~~~~~~~~~~
{: #fig-frame title="HTTP/QUIC frame format"}

Note that the first four octets of the frame use a fixed-size encoding; a
variable-length integer encoding is used for the contents of frames.

## Frame Definitions {#frames}

### DATA {#frame-data}
Expand Down Expand Up @@ -485,9 +491,9 @@ The flags defined are:
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
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Prioritized Request ID (32) |
| Prioritized Request ID (i) |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Stream Dependency ID (32) |
| Stream Dependency ID (i) |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Weight (8) |
+-+-+-+-+-+-+-+-+
Expand All @@ -497,16 +503,16 @@ The flags defined are:
The PRIORITY frame payload has the following fields:

Prioritized Request ID:
: A 32-bit identifier for a request. This contains the stream ID of a request
stream when the PUSH_PRIORITIZED flag is clear, or a Push ID when the
PUSH_PRIORITIZED flag is set.
: A variable-length integer that identifies a request. This contains
the Stream ID of a request stream when the PUSH_PRIORITIZED flag is clear,
or a Push ID when the PUSH_PRIORITIZED flag is set.

Stream Dependency ID:
: A 32-bit stream identifier for a dependent request. This contains the
stream ID of a request stream when the PUSH_DEPENDENT flag is clear, or a
Push ID when the PUSH_DEPENDENT flag is set. A request stream ID of 0
indicates a dependency on the root stream. For details of dependencies,
see {{priority}} and {{!RFC7540}}, Section 5.3.
: A variable length integer that identifies a dependent request. This
contains the Stream ID of a request stream when the PUSH_DEPENDENT flag is
clear, or a Push ID when the PUSH_DEPENDENT flag is set. A request Stream
ID of 0 indicates a dependency on the root stream. For details of
dependencies, see {{priority}} and {{!RFC7540}}, Section 5.3.

Weight:
: An unsigned 8-bit integer representing a priority weight for the stream (see
Expand Down Expand Up @@ -534,15 +540,18 @@ HTTP_MALFORMED_PRIORITY error, unless it references stream ID 0. A PRIORITY
that sets a PUSH_PRIORITIZED or PUSH_DEPENDENT flag, but then references a
non-existent Push ID MUST be treated as a HTTP_MALFORMED_PRIORITY error.

The length of a PRIORITY frame is 9 octets. A PRIORITY frame with any other
length MUST be treated as a connection error of type HTTP_MALFORMED_PRIORITY.
A PRIORITY frame MUST contain only the identified fields. A PRIORITY frame that
contains more or fewer fields, or a PRIORITY frame that includes a truncated
integer encoding MUST be treated as a connection error of type
HTTP_MALFORMED_PRIORITY.


### CANCEL_PUSH {#frame-cancel-push}

The CANCEL_PUSH frame (type=0x3) is used to request cancellation of server push
prior to the push stream being created. The CANCEL_PUSH frame identifies a
server push request by Push ID (see {{frame-push-promise}}).
server push request by Push ID (see {{frame-push-promise}}) using a
variable-length integer.

When a server receives this frame, it aborts sending the response for the
identified server push. If the server has not yet started to send the server
Expand All @@ -563,14 +572,16 @@ type HTTP_WRONG_STREAM.

The CANCEL_PUSH frame has no defined flags.

The CANCEL_PUSH frame carries a 32-bit Push ID that identifies the server push
that is being cancelled (see {{frame-push-promise}}).
The CANCEL_PUSH frame carries a Push ID encoded as a variable-length integer.
The Push ID identifies the server push that is being cancelled (see
{{frame-push-promise}}).

If the client receives a CANCEL_PUSH frame, that frame might identify a Push ID
that has not yet been mentioned by a PUSH_PROMISE frame.

A server MUST treat a CANCEL_PUSH frame payload that is other than 4 octets in
length as a connection error of type HTTP_MALFORMED_CANCEL_PUSH.
A server MUST treat a CANCEL_PUSH frame payload does not contain exactly one
variable-length integer as a connection error of type
HTTP_MALFORMED_CANCEL_PUSH.


### SETTINGS {#frame-settings}
Expand Down Expand Up @@ -605,7 +616,7 @@ value.
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
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Identifier (16) | Length (16) |
| Identifier (16) | Length (i) ...
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Contents (?) ...
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
Expand Down Expand Up @@ -638,20 +649,17 @@ HTTP_MALFORMED_SETTINGS.

#### Integer encoding

Settings which are integers are transmitted in network byte order. Leading
zero octets are permitted, but implementations SHOULD use only as many bytes as
are needed to represent the value. An integer MUST NOT be represented in more
bytes than would be used to transfer the maximum permitted value.
Settings which are integers use the QUIC variable-length integer encoding.

#### Defined SETTINGS Parameters {#settings-parameters}

The following settings are defined in HTTP/QUIC:

SETTINGS_HEADER_TABLE_SIZE (0x1):
: An integer with a maximum value of 2^32 - 1. This value MUST be zero.
: An integer with a maximum value of 2^30 - 1. This value MUST be zero.

SETTINGS_MAX_HEADER_LIST_SIZE (0x6):
: An integer with a maximum value of 2^32 - 1
: An integer with a maximum value of 2^30 - 1

#### Usage in 0-RTT

Expand Down Expand Up @@ -691,7 +699,7 @@ server to client, as in HTTP/2. The PUSH_PROMISE frame defines no flags.
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
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Push ID (32) |
| Push ID (i) ...
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Header Block (*) ...
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
Expand All @@ -701,9 +709,9 @@ server to client, as in HTTP/2. The PUSH_PROMISE frame defines no flags.
The payload consists of:

Push ID:
: A 32-bit identifier for the server push request. A push ID is used in push
stream header ({{server-push}}), CANCEL_PUSH frames ({{frame-cancel-push}}),
and PRIORITY frames ({{frame-priority}}).
: A variable-length integer that identifies the server push request. A push ID
is used in push stream header ({{server-push}}), CANCEL_PUSH frames
({{frame-cancel-push}}), and PRIORITY frames ({{frame-priority}}).

Header Block:
: HPACK-compressed request headers for the promised response.
Expand Down Expand Up @@ -743,10 +751,12 @@ administrative actions, like server maintenance. GOAWAY by itself does not
close a connection. (Note that clients do not need to send GOAWAY to gracefully
close a connection; they simply stop making new requests.)

The GOAWAY frame does not define any flags, and the payload is a QUIC stream
identifier. The GOAWAY frame applies to the connection, not a specific stream.
An endpoint MUST treat a GOAWAY frame on a stream other than the control stream
as a connection error ({{errors}}) of type HTTP_WRONG_STREAM.
The GOAWAY frame does not define any flags, and the payload is a QUIC Stream ID
encoded as a variable-length integer.

The GOAWAY frame applies to the connection, not a specific stream. An endpoint
MUST treat a GOAWAY frame on a stream other than the control stream as a
connection error ({{errors}}) of type HTTP_WRONG_STREAM.

New client requests might already have been sent before the client receives the
server's GOAWAY frame. The GOAWAY frame contains the stream identifier of the
Expand Down Expand Up @@ -841,14 +851,15 @@ sending a MAX_PUSH_ID frame as the server fulfills or cancels server pushes.

The MAX_PUSH_ID frame has no defined flags.

The MAX_PUSH_ID frame carries a 32-bit Push ID that identifies the maximum value
for a Push ID that the server can use (see {{frame-push-promise}}). A
MAX_PUSH_ID frame cannot reduce the maximum Push ID; receipt of a MAX_PUSH_ID
that contains a smaller value than previously received MUST be treated as a
connection error of type HTTP_MALFORMED_MAX_PUSH_ID.
The MAX_PUSH_ID frame carries a single variable-length integer that identifies
the maximum value for a Push ID that the server can use (see
{{frame-push-promise}}). A MAX_PUSH_ID frame cannot reduce the maximum Push ID;
receipt of a MAX_PUSH_ID that contains a smaller value than previously received
MUST be treated as a connection error of type HTTP_MALFORMED_MAX_PUSH_ID.

A server MUST treat a MAX_PUSH_ID frame payload that is other than 4 octets in
length as a connection error of type HTTP_MALFORMED_MAX_PUSH_ID.
A server MUST treat a MAX_PUSH_ID frame payload that does not contain a single
variable-length integer as a connection error of type
HTTP_MALFORMED_MAX_PUSH_ID.


# Connection Management
Expand Down Expand Up @@ -966,6 +977,13 @@ applicable to both protocols at once.

These departures are noted in this section.

## Streams {#h2-streams}

HTTP/QUIC permits use of a larger number of streams (2^62-1) then HTTP/2. The
considerations about exhaustion of stream identifier space apply, though the
space is significantly larger such that it is likely that other limits in QUIC
are reached first, such as the limit on the connection flow control window.

## HTTP Frame Types {#h2-frames}

Many framing concepts from HTTP/2 can be elided away on QUIC, because the
Expand Down Expand Up @@ -999,7 +1017,13 @@ HEADERS frames. To achieve in-order delivery of priority changes in HTTP/QUIC,
PRIORITY frames are sent on the control stream and the PRIORITY section is
removed from the HEADERS frame.

Other than this issue, frame type HTTP/2 extensions are typically portable to
Frame type definitions in HTTP/QUIC often use the QUIC variable-length integer
encoding. In particular, Stream IDs use this encoding, which allow for a larger
range of possible values than the encoding used in HTTP/2. Redefinition of the
encoding of extension frame types might be necessary if the encoding includes a
Stream ID.

Other than these issues, frame type HTTP/2 extensions are typically portable to
QUIC simply by replacing Stream 0 in HTTP/2 with Stream 1 in HTTP/QUIC.
HTTP/QUIC extensions will not assume ordering, but would not be harmed by
ordering, and would be portable to HTTP/2 in the same manner.
Expand Down Expand Up @@ -1342,7 +1366,7 @@ The original authors of this specification were Robbie Shade and Mike Warres.

## Since draft-ietf-quic-http-06

Nothing yet.
- Changes for integer encodings in QUIC (#595)

## Since draft-ietf-quic-http-05

Expand Down