wdiff draft-ietf-masque-h3-datagram-00.txt draft-ietf-masque-h3-datagram-01.txt

Network Working Group
MASQUE D. Schinazi
Internet-Draft Google LLC
Intended status: Standards Track L. Pardue
Expires: 2 August 14 November 2021 Cloudflare
29 January
13 May 2021

Using QUIC Datagrams with HTTP/3
draft-ietf-masque-h3-datagram-00
draft-ietf-masque-h3-datagram-01

Abstract

The QUIC DATAGRAM extension provides application protocols running
over QUIC with a mechanism to send unreliable data while leveraging
the security and congestion-control properties of QUIC. However,
QUIC DATAGRAM frames do not provide a means to demultiplex
application contexts. This document defines describes how to use QUIC
DATAGRAM frames when the application protocol running over QUIC is HTTP/3 by
adding an identifier at the start of the frame payload. This allows
HTTP messages to convey related information using unreliable DATAGRAM
frames, ensuring those frames are properly associated
HTTP/3. It associates datagrams with client-initiated bidirectional
streams and defines an HTTP
message. optional additional demultiplexing layer.

Discussion of this work is encouraged to happen on the MASQUE IETF
mailing list (masque@ietf.org (mailto:masque@ietf.org)) or on the
GitHub repository which contains the draft: https://github.com/ietf-
wg-masque/draft-ietf-masque-h3-datagram.

Status of This Memo

This Internet-Draft is submitted in full conformance with the
provisions of BCP 78 and BCP 79.

Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF). Note that other groups may also distribute
working documents as Internet-Drafts. The list of current Internet-
Drafts is at https://datatracker.ietf.org/drafts/current/.

Internet-Drafts are draft documents valid for a maximum of six months
and may be updated, replaced, or obsoleted by other documents at any
time. It is inappropriate to use Internet-Drafts as reference
material or to cite them other than as "work in progress."

This Internet-Draft will expire on 2 August 14 November 2021.

This document is subject to BCP 78 and the IETF Trust's Legal
Provisions Relating to IETF Documents (https://trustee.ietf.org/
license-info) in effect on the date of publication of this document.
Please review these documents carefully, as they describe your rights
and restrictions with respect to this document. Code Components
extracted from this document must include Simplified BSD License text
as described in Section 4.e of the Trust Legal Provisions and are
provided without warranty as described in the Simplified BSD License.

Table of Contents

1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 3
1.1. Conventions and Definitions . . . . . . . . . . . . . . . 3
2. Flow Identifiers Multiplexing . . . . . . . . . . . . . . . . . . . . . . . . 3
3. Flow Identifier Allocation
2.1. Datagram Contexts . . . . . . . . . . . . . . . . . . . . 3
4.
2.2. Context ID Allocation . . . . . . . . . . . . . . . . . . 4
3. HTTP/3 DATAGRAM Frame Format . . . . . . . . . . . . . . . . 4
4. CAPSULE HTTP/3 Frame Definition . . . . . . . . . . . . . . . 5
4.1. The REGISTER_DATAGRAM_CONTEXT Capsule . . . . . . . . . . 6
4.2. The CLOSE_DATAGRAM_CONTEXT Capsule . . . . . . . . . . . 7
4.3. The DATAGRAM Capsule . . . . . . . . . . . . . . . . . . 8
5. The H3_DATAGRAM HTTP/3 SETTINGS Parameter . . . . . . . . . . 4 9
6. Datagram-Flow-Id Header Field Definition HTTP/1.x and HTTP/2 Support . . . . . . . . . . . . 5
7. HTTP Intermediaries . . . . . 9
7. Security Considerations . . . . . . . . . . . . . . . . 7 . . . 10
8. Security IANA Considerations . . . . . . . . . . . . . . . . . . . 7
9. IANA Considerations . . . 10
8.1. HTTP/3 CAPSULE Frame . . . . . . . . . . . . . . . . . . 7
9.1. 10
8.2. HTTP SETTINGS Parameter . . . . . . . . . . . . . . . . . 7
9.2. HTTP Header Field 10
8.3. Capsule Types . . . . . . . . . . . . . . . . . . . . 8
9.3. Flow Identifier Parameters . . 10
8.4. Context Extension Keys . . . . . . . . . . . . . . . 8
10. . . 11
9. Normative References . . . . . . . . . . . . . . . . . . . . 8
Acknowledgments 11
Appendix A. Examples . . . . . . . . . . . . . . . . . . . . . . 12
A.1. CONNECT-UDP . . . 10
Authors' Addresses . . . . . . . . . . . . . . . . . . . . 12
A.2. CONNECT-UDP with Timestamp Extension . . . 10

1. Introduction

The QUIC DATAGRAM extension [DGRAM] provides application protocols
running over QUIC [QUIC] . . . . . . . 13
A.3. CONNECT-IP with a mechanism to send unreliable data
while leveraging the security and congestion-control properties of
QUIC. However, QUIC DATAGRAM frames do not provide a means to
demultiplex application contexts. This document defines how to use
QUIC DATAGRAM frames when the application protocol running over QUIC
is HTTP/3 [H3] by adding an identifier at IP compression . . . . . . . . . . . . . 14
A.4. WebTransport . . . . . . . . . . . . . . . . . . . . . . 15
Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . . . 16
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 16

1. Introduction

The QUIC DATAGRAM extension [DGRAM] provides application protocols
running over QUIC [QUIC] with a mechanism to send unreliable data
while leveraging the start security and congestion-control properties of the frame
payload.
QUIC. However, QUIC DATAGRAM frames do not provide a means to
demultiplex application contexts. This allows HTTP messages document describes how to convey related information
using unreliable use
QUIC DATAGRAM frames, ensuring those frames are properly
associated when the application protocol running over QUIC
is HTTP/3 [H3]. It associates datagrams with client-initiated
bidirectional streams and defines an HTTP message.

This design mimics the use of Stream Types in HTTP/3, which provide a optional additional
demultiplexing identifier at the start of each unidirectional stream. layer.

1.1. Conventions and Definitions

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
"SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and
"OPTIONAL" in this document are to be interpreted as described in BCP
14 [RFC2119] [RFC8174] when, and only when, they appear in all
capitals, as shown here.

2. Flow Identifiers

Flow identifiers represent bidirectional flows Multiplexing

In order to allow multiple exchanges of datagrams within to coexist on a
single
given QUIC connection. These are conceptually similar to streams in connection, HTTP datagrams contain two layers of
multiplexing. First, the sense QUIC DATAGRAM frame payload starts with an
encoded stream identifier that they allow associates the datagram with a given
QUIC stream. Second, datagrams carry a context identifier (see
Section 2.1) that allows multiplexing multiple datagram contexts
related to a given HTTP request. Conceptually, the first layer of application data. Flows
lack any of
multiplexing is per-hop, while the ordering or reliability guarantees second is end-to-end.

2.1. Datagram Contexts

Within the scope of streams.

Beyond this, a sender SHOULD ensure that DATAGRAM frames within a
single flow are transmitted in order relative given HTTP request, contexts provide an
additional demultiplexing layer. Contexts determine the encoding of
datagrams, and can be used to one another. If
multiple DATAGRAM frames implicitly convey metadata. For
example, contexts can be packed into a single QUIC packet, used for compression to elide some parts of
the
sender SHOULD group them by flow datagram: the context identifier then maps to promote fate-sharing
within a specific flow and improve compression
context that the ability receiver can use to process batches reconstruct the elided data.

Contexts are identified within the scope of a given request by a
numeric value, referred to as the context ID. A context ID is a
62-bit integer (0 to 2^62-1).

While stream IDs are a per-hop concept, context IDs are an end-to-end
concept. In other words, if a datagram messages efficiently travels through one or more
intermediaries on its way from client to server, the receiver.

3. Flow Identifier stream ID will
most likely change from hop to hop, but the context ID will remain
the same. Context IDs are opaque to intermediaries.

2.2. Context ID Allocation

Implementations of HTTP/3 that support the DATAGRAM extension MUST
provide a flow identifier context ID allocation service. That service will allow
applications co-located with HTTP/3 to request a unique flow
identifier context ID
that they can subsequently use for their own purposes. The HTTP/3
implementation will then parse the flow identifier context ID of incoming DATAGRAM
frames and use it to deliver the frame to the appropriate application. application
context.

Even-numbered flow identifiers context IDs are client-initiated, while odd-
numbered flow identifiers odd-numbered
context IDs are server-initiated. This means that an HTTP/3 client
implementation of the flow identifier context ID allocation service MUST only provide
even-numbered identifiers, IDs, while a server implementation MUST only provide
odd-numbered identifiers. IDs. Note that, once allocated, any flow identifier context ID can be
used by both client and server - only allocation carries separate
namespaces to avoid requiring synchronization.

The flow allocation service SHOULD also provide a mechanism for
applications to indicate they have completed their usage of a flow
identifier and will no longer be using Additionally, note
that flow identifier, this
process the context ID namespace is called "retiring" a flow identifier. Applications MUST
NOT retire tied to a flow identifier until after they have received
confirmation that given HTTP request: it is
possible for the peer has also stopped using that flow
identifier. The flow identifier allocation service MAY reuse
previously retired flow identifiers once they have ascertained that
there are no packets with DATAGRAM frames using that flow identifier
still same numeral context ID to be used simultaneously in flight. Reusing flow identifiers can improve performance by
transmitting the flow identifier using a shorter variable-length
integer encoding.

4.
distinct requests.

3. HTTP/3 DATAGRAM Frame Format

When used with HTTP/3, the Datagram Data field of QUIC DATAGRAM
frames uses the following format (using the notation from the
"Notational Conventions" section of [QUIC]):

HTTP/3 DATAGRAM Frame Datagram {
Flow Identifier
Quarter Stream ID (i),
Context ID (i),
HTTP/3 Datagram Payload (..),
}

Figure 1: HTTP/3 DATAGRAM Frame Format

Flow Identifier:

Quarter Stream ID: A variable-length integer that contains the value
of the client-initiated bidirectional stream that this datagram is
associated with, divided by four. (The division by four stems
from the fact that HTTP requests are sent on client-initiated
bidirectional streams, and those have stream IDs that are
divisible by four.)

Context ID: A variable-length integer indicating the Flow
Identifier context ID of
the datagram (see Section 2). 2.1).

HTTP/3 Datagram Payload: The payload of the datagram, whose
semantics are defined by individual applications. Note that this
field can be empty.

Endpoints MUST treat receipt of

Intermediaries parse the Quarter Stream ID field in order to
associate the QUIC DATAGRAM frame with a stream. If an intermediary
receives a QUIC DATAGRAM frame whose payload is too short to parse allow
parsing the flow identifier as Quarter Stream ID field, the intermediary MUST treat it
as an HTTP/3 connection error of type H3_GENERAL_PROTOCOL_ERROR.

5. The H3_DATAGRAM HTTP/3 SETTINGS Parameter

Implementations of
Intermediaries MUST ignore any HTTP/3 that support this mechanism can indicate
that Datagram fields after the
Quarter Stream ID.

Endpoints parse both the Quarter Stream ID field and the Context ID
field in order to their peer by sending associate the H3_DATAGRAM SETTINGS parameter QUIC DATAGRAM frame with a value of 1. The value of the H3_DATAGRAM SETTINGS parameter MUST
be either 0 or 1. A value of 0 indicates stream and
context within that this mechanism is not
supported. An stream. If an endpoint that receives the H3_DATAGRAM SETTINGS
parameter with a value that QUIC DATAGRAM
frame whose payload is neither 0 or 1 MUST terminate too short to allow parsing the Quarter Stream
ID field, the endpoint MUST treat it as an HTTP/3 connection with error H3_SETTINGS_ERROR.

An of
type H3_GENERAL_PROTOCOL_ERROR. If an endpoint that sends the H3_DATAGRAM SETTINGS parameter with receives a
value of 1 MUST send the max_datagram_frame_size QUIC Transport
Parameter [DGRAM]. An
DATAGRAM frame whose payload is long enough to allow parsing the
Quarter Stream ID field but too short to allow parsing the Context ID
field, the endpoint that receives MUST abruptly terminate the H3_DATAGRAM
SETTINGS parameter corresponding stream
with a value stream error of 1 on type H3_GENERAL_PROTOCOL_ERROR.

If a QUIC connection DATAGRAM frame is received and its Quarter Stream ID maps to a
stream that did
not also receive has already been closed, the max_datagram_frame_size QUIC Transport Parameter receiver MUST terminate silently drop
that frame. If a DATAGRAM frame is received and its Quarter Stream
ID maps to a stream that has not yet been created, the connection with error H3_SETTINGS_ERROR.

When clients use 0-RTT, they MAY store receiver SHALL
either drop that frame silently or buffer it temporarily while
awaiting the value creation of the server's
H3_DATAGRAM SETTINGS parameter. Doing so corresponding stream.

4. CAPSULE HTTP/3 Frame Definition

CAPSULE allows reliably sending request-related information end-to-
end, even in the client to use presence of HTTP intermediaries.

CAPSULE is an HTTP/3 datagrams in 0-RTT packets. When servers decide Frame (as opposed to accept
0-RTT data, they MUST send a H3_DATAGRAM SETTINGS parameter greater
than or equal to the value they QUIC frame) which SHALL
only be sent to the client in client-initiated bidirectional streams.
Intermediaries MUST forward all received CAPSULE frames in their
unmodified entirety on the connection same stream where they sent them it would forward DATA
frames. Intermediaries MUST NOT send any CAPSULE frames other than
the NewSessionTicket message. ones it is forwarding.

This specification of CAPSULE currently uses HTTP/3 frame type
0xffcab5. If this document is approved, a client
stores lower number will be
requested from IANA.

CAPSULE HTTP/3 Frame {
Type (i) = 0xffcab5,
Length (i),
Capsule Type (i),
Capsule Data (..),
}

Figure 2: CAPSULE HTTP/3 Frame Format

The Type and Length fields follows the value definition of HTTP/3 frames
from [H3]. The payload consists of:

Capsule Type: The type of this capsule.

Capsule Data: Data whose semantics depends on the H3_DATAGRAM SETTINGS parameter Capsule Type.

Endpoints which receive a Capsule with their
0-RTT state, they an unknown Capsule Type MUST validate
silently drop that the new value of the H3_DATAGRAM
SETTINGS parameter sent by the server in the handshake is greater
than or equal to the stored value; if not, the client Capsule. Intermediaries MUST terminate forward Capsules,
even if they do not know the connection with error H3_SETTINGS_ERROR. In all cases, Capsule Type or cannot parse the
maximum permitted value Capsule
Data.

4.1. The REGISTER_DATAGRAM_CONTEXT Capsule

The REGISTER_DATAGRAM_CONTEXT capsule (type=0x00) allows an endpoint
to inform its peer of the H3_DATAGRAM SETTINGS parameter is 1.

6. Datagram-Flow-Id Header Field Definition

"Datagram-Flow-Id" is a List Structured Field [STRUCT-FIELD], whose
members MUST all be Items encoding and semantics of type Integer. datagrams
associated with a given context ID. Its ABNF is:

Datagram-Flow-Id = sf-list

The "Datagram-Flow-Id" header Capsule Data field is used consists
of:

REGISTER_DATAGRAM_CONTEXT Capsule {
Context ID (i),
Extension String (..),
}

Figure 3: REGISTER_DATAGRAM_CONTEXT Capsule Format

Context ID: The context ID to associate one or more
datagram flow identifiers register.

Extension String: A string of comma-separated key-value pairs to
enable extensibility. Keys are registered with an HTTP message. As a simple example
using a single identifier, IANA, see
Section 8.4.

The ABNF for the definition Extension String field is as follows (using syntax
from Section 3.2.6 of an HTTP method could
instruct the client to use its flow identifier allocation service to
allocate a new flow identifier, [RFC7230]):

extension-string = [ ext-member *( "," ext-member ) ]
ext-member = ext-member-key "=" ext-member-value
ext-member-key = token
ext-member-value = token

Note that these registrations are unilateral and then bidirectional: the client will add
sender of the
"Datagram-Flow-Id" header field to its request to communicate that
value frame unilaterally defines the semantics it will apply
to the server. In datagrams it sends and receives using this example, the resulting header field
could look like:

Datagram-Flow-Id = 2

List members are flow identifier elements, which context ID. Once a
context ID is registered, it can be named or
unnamed. One element used in the list is allowed to be unnamed, but all
but one elements both directions.

Endpoints MUST carry NOT send DATAGRAM frames using a name. The name of an element is
encoded in the key of Context ID until they
have either sent or received a REGISTER_DATAGRAM_CONTEXT Capsule with
the first parameter of same Context ID. However, due to reordering, an endpoint that element (parameters
are defined in Section 3.1.2 of [STRUCT-FIELD]). Each name
receives a DATAGRAM frame with an unknown Context ID MUST NOT
appear more than once in treat
it as an error, it SHALL instead drop the list. The value of DATAGRAM frame silently, or
buffer it temporarily while awaiting the first parameter
of each named element (whose corresponding key conveys
REGISTER_DATAGRAM_CONTEXT Capsule.

Endpoints MUST NOT register the same Context ID twice on the element
name) same
stream. This also applies to Context IDs that have been closed using
a CLOSE_DATAGRAM_CONTEXT capsule. Clients MUST be of type Boolean NOT register server-
initiated Context IDs and equal to true. The value of the
first parameter servers MUST NOT register client-initiated
Context IDs. If an endpoint receives a REGISTER_DATAGRAM_CONTEXT
capsule that violates one or more of these requirements, the unnamed element endpoint
MUST NOT be abruptly terminate the corresponding stream with a stream error
of type Boolean. H3_GENERAL_PROTOCOL_ERROR.

4.2. The ordering of the list does not carry any semantics. For example, CLOSE_DATAGRAM_CONTEXT Capsule

The CLOSE_DATAGRAM_CONTEXT capsule (type=0x01) allows an HTTP method endpoint to
inform its peer that wishes it will no longer send or parse received
datagrams associated with a given context ID. Its Capsule Data field
consists of:

CLOSE_DATAGRAM_CONTEXT Capsule {
Context ID (i),
Extension String (..),
}

Figure 4: CLOSE_DATAGRAM_CONTEXT Capsule Format

Context ID: The context ID to use four datagram flow identifiers for close.

Extension String: A string of comma-separated key-value pairs to
enable extensibility, see the lifetime definition of its request stream could look like this:

Datagram-Flow-Id = 42, 44; ecn-ect0, 46; ecn-ect1, 48; ecn-ce

In the same field in
Section 4.1 for details.

Note that this example, 42 close is unilateral and bidirectional: the unnamed flow identifier, 44 represents sender of
the
name "ecn-ect0", 46 represents "ecn-ect1", and 48 represents "ecn-
ce". Note that, since frame unilaterally informs its peer of the list ordering does not carry semantics,
this example closure. Endpoints
can be equivalently encoded as:

Datagram-Flow-Id = 44; ecn-ect0, 42, 48; ecn-ce, 46; ecn-ect1

Even if use CLOSE_DATAGRAM_CONTEXT capsules to close a context that was
initially registered by either themselves, or by their peer.
Endpoints MAY use the CLOSE_DATAGRAM_CONTEXT capsule to immediately
reject a context that was just registered using a sender attempts
REGISTER_DATAGRAM_CONTEXT capsule if they find its Extension String
to communicate the meaning of a flow
identifier before it uses it in be unacceptable.

After an HTTP/3 datagram, endpoint has either sent or received a
CLOSE_DATAGRAM_CONTEXT frame, it is possible MUST NOT send any DATAGRAM frames
with that its peer will receive Context ID. However, due to reordering, an HTTP/3 datagram endpoint that
receives a DATAGRAM frame with a flow identifier
that closed Context ID MUST NOT treat it does not know
as an error, it has not yet received the corresponding
"Datagram-Flow-Id" header field. (For example, this could happen if SHALL instead drop the QUIC STREAM DATAGRAM frame silently.

Endpoints MUST NOT close a Context ID that contains the "Datagram-Flow-Id" header
field is reordered and arrives afer the DATAGRAM frame.) was not previously
registered. Endpoints MUST NOT treat close a Context ID that scenario as has already
been closed. If an error; they endpoint receives a CLOSE_DATAGRAM_CONTEXT
capsule that violates one or more of these requirements, the endpoint
MUST either silently
discard abruptly terminate the corresponding stream with a stream error
of type H3_GENERAL_PROTOCOL_ERROR.

4.3. The DATAGRAM Capsule

The DATAGRAM capsule (type=0x02) allows an endpoint to send a
datagram or buffer it until they receive the "Datagram-
Flow-Id" header field.

Distinct frame over an HTTP requests MAY refer to stream. This is particularly useful when
using a version of HTTP that does not support QUIC DATAGRAM frames.
Its Capsule Data field consists of:

DATAGRAM Capsule {
Context ID (i),
HTTP/3 Datagram Payload (..),
}

Figure 5: DATAGRAM Capsule Format

Context ID: A variable-length integer indicating the context ID of
the datagram (see Section 2.1).

HTTP/3 Datagram Payload: The payload of the datagram, whose
semantics are defined by individual applications. Note that this
field can be empty.

Datagrams sent using the DATAGRAM Capsule have the exact same flow identifier
semantics as datagrams sent in their
respective "Datagram-Flow-Id" header fields.

Note QUIC DATAGRAM frames.

5. The H3_DATAGRAM HTTP/3 SETTINGS Parameter

Implementations of HTTP/3 that integer structured fields support this mechanism can only encode values up indicate
that to
10^15-1, therefore their peer by sending the maximum possible H3_DATAGRAM SETTINGS parameter with
a value of an element 1. The value of the
"Datagram-Flow-Id" header field is lower then the theoretical maximum H3_DATAGRAM SETTINGS parameter MUST
be either 0 or 1. A value of a flow identifier which 0 indicates that this mechanism is 2^62-1 due to the QUIC variable
length integer encoding. If the flow identifier allocation service
of an not
supported. An endpoint runs out of values lower than 10^15-1, that receives the endpoint H3_DATAGRAM SETTINGS
parameter with a value that is neither 0 or 1 MUST fail terminate the flow identifier allocation.
connection with error H3_SETTINGS_ERROR.

An HTTP message endpoint that
carries a "Datagram-Flow-Id" header field sends the H3_DATAGRAM SETTINGS parameter with a flow identifier
value above 10^15-1 is malformed (see Section 8.1.2.6 of [H2]).

7. HTTP Intermediaries

HTTP/3 DATAGRAM flow identifiers are specific to a given HTTP/3
connection. However, in some cases, an HTTP request may travel
across multiple HTTP connections if there are HTTP intermediaries
involved; see Section 2.3 of [RFC7230].

If an intermediary has sent 1 MUST send the max_datagram_frame_size QUIC Transport
Parameter [DGRAM]. An endpoint that receives the H3_DATAGRAM
SETTINGS parameter with a value of 1 on its client-facing connection, it MUST inspect all HTTP
requests from that a QUIC connection and check for the presence of the
"Datagram-Flow-Id" header field. If the HTTP method of the request
is that did
not supported by also receive the intermediary, it max_datagram_frame_size QUIC Transport Parameter
MUST remove terminate the "Datagram-
Flow-Id" header field before forwarding connection with error H3_SETTINGS_ERROR.

When clients use 0-RTT, they MAY store the request. If value of the
intermediary supports server's
H3_DATAGRAM SETTINGS parameter. Doing so allows the method, it client to use
HTTP/3 datagrams in 0-RTT packets. When servers decide to accept
0-RTT data, they MUST either remove the header
field send a H3_DATAGRAM SETTINGS parameter greater
than or adhere equal to the requirements leveraged by that method on
intermediaries.

If an intermediary has value they sent to the client in the connection
where they sent them the NewSessionTicket message. If a client
stores the value of the H3_DATAGRAM SETTINGS parameter with a
value of 1 on its server-facing connection, it their
0-RTT state, they MUST inspect all HTTP
responses from validate that connection and check for the presence new value of the
"Datagram-Flow-Id" header field. If H3_DATAGRAM
SETTINGS parameter sent by the HTTP method of server in the request handshake is not supported by the intermediary, it MUST remove greater
than or equal to the "Datagram-
Flow-Id" header field before forwarding stored value; if not, the response. If client MUST terminate
the
intermediary supports connection with error H3_SETTINGS_ERROR. In all cases, the method, it MUST either remove
maximum permitted value of the header
field or adhere to H3_DATAGRAM SETTINGS parameter is 1.

6. HTTP/1.x and HTTP/2 Support

We can provide DATAGRAM support in HTTP/2 by defining the requirements leveraged CAPSULE
frame in HTTP/2.

We can provide DATAGRAM support in HTTP/1.x by that method on
intermediaries.

If defining its data
stream format to a sequence of length-value capsules.

TODO: Refactor this document into "HTTP Datagrams" with definitions
for HTTP/1.x, HTTP/2, and HTTP/3.

7. Security Considerations

Since this feature requires sending an intermediary processes distinct HTTP requests HTTP/3 Settings parameter, it
"sticks out". In other words, probing clients can learn whether a
server supports this feature. Implementations that refer support this
feature SHOULD always send this Settings parameter to avoid leaking
the
same flow identifier in their respective "Datagram-Flow-Id" header
fields, it MUST ensure fact that those requests there are routed to the same
backend. applications using HTTP/3 datagrams enabled
on this endpoint.

8. Security IANA Considerations

8.1. HTTP/3 CAPSULE Frame

This document does not have additional security considerations beyond
those defined in [QUIC] and [DGRAM].

9. will request IANA Considerations

9.1. to register the following entry in
the "HTTP/3 Frames" registry:

8.2. HTTP SETTINGS Parameter

This document will request IANA to register the following entry in
the "HTTP/3 Settings" registry:

+--------------+-------+---------------+---------+

8.3. Capsule Types

This document establishes a registry for HTTP/3 frame type codes.
The "HTTP Capsule Types" registry governs a 62-bit space.
Registrations in this registry MUST include the following fields:

Type:

A name or label for the capsule type.

Value: The value of the Capsule Type field (see Section 4) is a
62bit integer.

Reference: An optional reference to a specification for the type.
This field MAY be empty.

Registrations follow the "First Come First Served" policy (see
Section 4.4 of [IANA-POLICY]) where two registrations MUST NOT have
the same Type.

This registry initially contains the following entries:

+---------------------------+-------+---------------+
| Capsule Type | Value | Specification |
+---------------------------+-------+---------------+
| REGISTER_DATAGRAM_CONTEXT | 0x00 |
+--------------+-------+---------------+---------+

9.2. HTTP Header Field This document will request IANA to register the "Datagram-Flow-Id"
header field in the "Permanent Message Header Field Names" registry
maintained at <https://www.iana.org/assignments/message-headers>.

9.3. Flow Identifier Parameters
+---------------------------+-------+---------------+

8.4. Context Extension Keys

REGISTER_DATAGRAM_CONTEXT capsules carry key-value pairs, see
Section 4.1. This document will request IANA to create an "HTTP
Datagram Flow
Identifier Parameters" Context Extension Keys" registry. Registrations in this
registry MUST include the following fields:

Key: The key of a parameter that is associated with a datagram flow
identifier list member (see Section 6). 4.1). Keys MUST be valid
structured field parameter keys (see tokens as
defined in Section 3.1.2 3.2.6 of
[STRUCT-FIELD]). [RFC7230].

Description: A brief description of the parameter key semantics, which MAY be
a summary if a specification reference is provided.

Is Name: This field MUST be either Yes or No. Yes indicates that
this parameter is the name of a named element (see Section 6). No
indicates that it is a parameter that is not a name.

Reference: An optional reference to a specification for the
parameter. This field MAY be empty.

Registrations follow the "First Come First Served" policy (see
Section 4.4 of [IANA-POLICY]) where two registrations MUST NOT have
the same Key. This registry is initially empty.

10.

9. Normative References

[DGRAM] Pauly, T., Kinnear, E., and D. Schinazi, "An Unreliable
Datagram Extension to QUIC", Work in Progress, Internet-
Draft, draft-ietf-quic-datagram-01, 24 August 2020,
<http://www.ietf.org/internet-drafts/draft-ietf-quic-
datagram-01.txt>.

[H2] Belshe, M., Peon, R., and M. Thomson, Ed., "Hypertext
Transfer Protocol Version 2 (HTTP/2)", RFC 7540,
DOI 10.17487/RFC7540, May 2015,
<https://www.rfc-editor.org/info/rfc7540>. draft-ietf-quic-datagram-02, 16 February 2021,
<https://tools.ietf.org/html/draft-ietf-quic-datagram-02>.

[H3] Bishop, M., "Hypertext Transfer Protocol Version 3
(HTTP/3)", Work in Progress, Internet-Draft, draft-ietf-
quic-http-33, 15 December 2020, <http://www.ietf.org/
internet-drafts/draft-ietf-quic-http-33.txt>.
quic-http-34, 2 February 2021,
<https://tools.ietf.org/html/draft-ietf-quic-http-34>.

[IANA-POLICY]
Cotton, M., Leiba, B., and T. Narten, "Guidelines for
Writing an IANA Considerations Section in RFCs", BCP 26,
RFC 8126, DOI 10.17487/RFC8126, June 2017,
<https://www.rfc-editor.org/info/rfc8126>.
<https://www.rfc-editor.org/rfc/rfc8126>.

[QUIC] Iyengar, J. and M. Thomson, "QUIC: A UDP-Based Multiplexed
and Secure Transport", Work in Progress, Internet-Draft,
draft-ietf-quic-transport-34, 14 January 2021,
<http://www.ietf.org/internet-drafts/draft-ietf-quic-
transport-34.txt>.
<https://tools.ietf.org/html/draft-ietf-quic-transport-
34>.

[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
Requirement Levels", BCP 14, RFC 2119,
DOI 10.17487/RFC2119, March 1997,
<https://www.rfc-editor.org/info/rfc2119>.
<https://www.rfc-editor.org/rfc/rfc2119>.

[RFC7230] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer
Protocol (HTTP/1.1): Message Syntax and Routing",
RFC 7230, DOI 10.17487/RFC7230, June 2014,
<https://www.rfc-editor.org/info/rfc7230>.
<https://www.rfc-editor.org/rfc/rfc7230>.

[RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC
2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174,
May 2017, <https://www.rfc-editor.org/info/rfc8174>.

[STRUCT-FIELD]
Nottingham, M. and P. Kamp, "Structured Field Values <https://www.rfc-editor.org/rfc/rfc8174>.

Appendix A. Examples

A.1. CONNECT-UDP
Client Server

STREAM(44): HEADERS -------->
:method = CONNECT-UDP
:scheme = https
:path = /
:authority = target.example.org:443

STREAM(44): CAPSULE -------->
Capsule Type = REGISTER_DATAGRAM_CONTEXT
Context ID = 0
Extension String = ""

DATAGRAM -------->
Quarter Stream ID = 11
Context ID = 0
Payload = Encapsulated UDP Payload

<-------- STREAM(44): HEADERS
:status = 200

/* Wait for
HTTP", Work in Progress, Internet-Draft, draft-ietf-
httpbis-header-structure-19, 3 June 2020,
<http://www.ietf.org/internet-drafts/draft-ietf-httpbis-
header-structure-19.txt>. target server to respond to UDP packet. */

<-------- DATAGRAM
Quarter Stream ID = 11
Context ID = 0
Payload = Encapsulated UDP Payload

A.2. CONNECT-UDP with Timestamp Extension
Client Server

STREAM(44): HEADERS -------->
:method = CONNECT-UDP
:scheme = https
:path = /
:authority = target.example.org:443

STREAM(44): CAPSULE -------->
Capsule Type = REGISTER_DATAGRAM_CONTEXT
Context ID = 0
Extension String = ""

DATAGRAM -------->
Quarter Stream ID = 11
Context ID = 0
Payload = Encapsulated UDP Payload

<-------- STREAM(44): HEADERS
:status = 200

/* Wait for target server to respond to UDP packet. */

<-------- DATAGRAM
Quarter Stream ID = 11
Context ID = 0
Payload = Encapsulated UDP Payload

STREAM(44): CAPSULE -------->
Capsule Type = REGISTER_DATAGRAM_CONTEXT
Context ID = 2
Extension String = "timestamp"

DATAGRAM -------->
Quarter Stream ID = 11
Context ID = 2
Payload = Encapsulated UDP Payload With Timestamp

A.3. CONNECT-IP with IP compression
Client Server

STREAM(44): HEADERS -------->
:method = CONNECT-IP
:scheme = https
:path = /
:authority = proxy.example.org:443

<-------- STREAM(44): HEADERS
:status = 200

/* Exchange CONNECT-IP configuration information. */

STREAM(44): CAPSULE -------->
Capsule Type = REGISTER_DATAGRAM_CONTEXT
Context ID = 0
Extension String = ""

DATAGRAM -------->
Quarter Stream ID = 11
Context ID = 0
Payload = Encapsulated IP Packet

/* Endpoint happily exchange encapsulated IP packets */
/* using Quarter Stream ID 11 and Context ID 0. */

DATAGRAM -------->
Quarter Stream ID = 11
Context ID = 0
Payload = Encapsulated IP Packet

/* After performing some analysis on traffic patterns, */
/* the client decides it wants to compress a 5-tuple. */

STREAM(44): CAPSULE -------->
Capsule Type = REGISTER_DATAGRAM_CONTEXT
Context ID = 2
Extension String = "ip=192.0.2.42,port=443"

DATAGRAM -------->
Quarter Stream ID = 11
Context ID = 2
Payload = Compressed IP Packet

A.4. WebTransport
Client Server

STREAM(44): HEADERS -------->
:method = CONNECT
:scheme = https
:method = webtransport
:path = /hello
:authority = webtransport.example.org:443
Origin = https://www.example.org:443

STREAM(44): CAPSULE -------->
Capsule Type = REGISTER_DATAGRAM_CONTEXT
Context ID = 0
Extension String = ""

<-------- STREAM(44): HEADERS
:status = 200

/* Both endpoints can now send WebTransport datagrams. */

Acknowledgments

The DATAGRAM flow context identifier was previously part of the DATAGRAM
frame definition itself, the author authors would like to acknowledge the
authors of that document and the members of the IETF MASQUE working
group for their suggestions. Additionally, the author authors would like to
thank Martin Thomson for suggesting the use of an HTTP/3 SETTINGS
parameter. Furthermore, the authors would like to thank Ben Schwartz
for writing the first proposal that used two layers of indirection.

Authors' Addresses

David Schinazi
Google LLC
1600 Amphitheatre Parkway
Mountain View, California 94043,
United States of America

Email: dschinazi.ietf@gmail.com

Lucas Pardue
Cloudflare

Email: lucaspardue.24.7@gmail.com