Draft: draft-ietf-webtrans-http2

Commentary: I make a few word - level adjustments , but the goal here was to tweak the way that this defines key concepts . I one concept " WebTransport frames " , which is n't necessarily a global concept , but it might be useful in this document to distinguish between HTTP/2 frames and the stuff in Section 6 . I also linked up the frame types . I 've a change that I 'm going to propose to kramdown that should make this a whole lot less unpleasant to use for the general case . 
 Check out . It 's magic .
WebTransport sessions are initiated inside a given HTTP/2 connection
by the client, who sends an extended CONNECT request RFC8441.  If the
server accepts the request, an WebTransport session is established.
The resulting stream will be further referred to as a _CONNECT
stream_, and its stream ID is used to uniquely identify a given
WebTransport session within the connection.  The ID of the CONNECT
stream that established a given WebTransport session will be further
referred to as a _Session ID_.
Both client and server can create a bidirectional or
unidirectional WebTransport stream within the WebTransport session
using a WT_STREAM frame.
A datagram can be sent using a WT_DATAGRAM frame.
Data flow on these streams is controlled via a flow control mechanism
very similar to the one provided by QUIC using WT_MAX_DATA,
WT_MAX_STREAM_DATA, WT_MAX_STREAMS, WT_DATA_BLOCKED,
WT_STREAM_DATA_BLOCKED, and WT_STREAMS_BLOCKED frames.
WebTransport streams can be closed via a WT_RESET_STREAM frame and a
receiver can request that a sender stop sending with a
WT_STOP_SENDING frame.
A client initiates a WebTransport session by sending an extended
CONNECT request RFC8441.  If the server accepts the request, a
WebTransport session is established.  The stream that carries the
CONNECT request is used to exchange bidirectional data for the
session.  This stream will be referred to as a _CONNECT stream_.  The
stream ID of a CONNECT stream, which will be referrred to as a
_Session ID_, is used to uniquely identify a given WebTransport
session within the connection.
After the session is established, endpoints exchange _WebTransport
frames_ using the bidirectional CONNECT stream.  Within this stream,
_WebTransport streams_ and _WebTransport datagrams_ are multiplexed.
In HTTP/2, WebTransport frames are carried in HTTP/2 DATA frames.
Multiple independent WebTransport sessions can share a connection if
the HTTP version supports that, as HTTP/2 does.
Stream creation and data flow on streams uses flow control mechanisms
modeled on those in QUIC.  Flow control is managed using the
WebTransport frames: , , , , , and . Flow control for the CONNECT
stream as a whole, as provided by the HTTP version in use, applies in
addition to any WebTransport-session-level flow control.
WebTransport streams can be aborted using a frame and a receiver can
request that a sender stop sending with a frame.
A WT_PADDING frame (type=0x00) has no semantic value.  PADDING frames
can be used to introduce additional data between other WebTransport
frames and can also be used to provide protection against traffic
analysis or for other reasons.
A WebTransport frame called WT_RESET_STREAM is introduced for either
endpoint to abruptly terminate the sending part of a WebTransport
stream.
An endpoint uses a WT_RESET_STREAM frame (type=0x04) to abruptly
terminate the sending part of a stream.
After sending a WT_RESET_STREAM, an endpoint ceases transmission and
retransmission of WT_STREAM frames on the identified stream.  A
receiver of WT_RESET_STREAM can discard any data that it already
received on that stream.
A frame (type=0x00) has no semantic value.  PADDING frames can be
used to introduce additional data between other WebTransport frames
and can also be used to provide protection against traffic analysis
or for other reasons.
A WebTransport frame called is introduced for either endpoint to
abruptly terminate the sending part of a WebTransport stream.
An endpoint uses a frame (type=0x04) to abruptly terminate the
sending part of a stream.
After sending a , an endpoint ceases transmission and retransmission
of frames on the identified stream.  A receiver of can discard any
data that it already received on that stream.
Unlike the equivalent QUIC frame, this frame does not include a Final
Size field.  In-order delivery of WT_STREAM frames ensures that the
amount of session-level flow control consumed by a stream is always
known by both endpoints.
A WebTransport frame called WT_STOP_SENDING is introduced to
communicate that incoming data is being discarded on receipt per
application request.  WT_STOP_SENDING requests that a peer cease
transmission on a stream.
Unlike the equivalent QUIC frame, this frame does not include a Final
Size field.  In-order delivery of frames ensures that the amount of
session-level flow control consumed by a stream is always known by
both endpoints.
A WebTransport frame called is introduced to communicate that
incoming data is being discarded on receipt per application request.
requests that a peer cease transmission on a stream.
A WebTransport frame called WT_MAX_DATA is introduced to inform the
peer of the maximum amount of data that can be sent on the
WebTransport session as a whole.
All data sent in WT_STREAM frames counts toward this limit.  The sum
of the lengths of Stream Data fields in WT_STREAM frames MUST NOT
exceed the value advertised by a receiver.
A WebTransport frame called WT_MAX_STREAM_DATA is introduced to
inform a peer of the maximum amount of data that can be sent on a
stream.
A WebTransport frame called is introduced to inform the peer of the
maximum amount of data that can be sent on the WebTransport session
as a whole.
All data sent in frames counts toward this limit.  The sum of the
lengths of Stream Data fields in frames MUST NOT exceed the value
advertised by a receiver.
A WebTransport frame called is introduced to inform a peer of the
maximum amount of data that can be sent on a stream.
All data sent in WT_STREAM frames for the identified stream counts
toward this limit.  The sum of the lengths of Stream Data fields in
WT_STREAM frames on the identified stream MUST NOT exceed the value
advertised by a receiver.
A WebTransport frame called WT_MAX_STREAMS is introduced to inform
the peer of the cumulative number of streams of a given type it is
permitted to open.  A WT_MAX_STREAMS frame with a type of 0x12
applies to bidirectional streams, and a WT_MAX_STREAMS frame with a
type of 0x13 applies to unidirectional streams.
All data sent in frames for the identified stream counts toward this
limit.  The sum of the lengths of Stream Data fields in frames on the
identified stream MUST NOT exceed the value advertised by a receiver.
A WebTransport frame called is introduced to inform the peer of the
cumulative number of streams of a given type it is permitted to open.
A frame with a type of 0x12 applies to bidirectional streams, and a
frame with a type of 0x13 applies to unidirectional streams.
A sender SHOULD send a WT_DATA_BLOCKED frame (type=0x14) when it
wishes to send data but is unable to do so due to WebTransport
session-level flow control.  WT_DATA_BLOCKED frames can be used as
input to tuning of flow control algorithms.
A sender SHOULD send a WT_STREAM_DATA_BLOCKED frame (type=0x15) when
it wishes to send data but is unable to do so due to stream-level
flow control.  This frame is analogous to WT_DATA_BLOCKED.
A sender SHOULD send a frame (type=0x14) when it wishes to send data
but is unable to do so due to WebTransport session-level flow
control.  frames can be used as input to tuning of flow control
algorithms.
A sender SHOULD send a frame (type=0x15) when it wishes to send data
but is unable to do so due to stream-level flow control.  This frame
is analogous to .
A sender SHOULD send a WT_STREAMS_BLOCKED frame (type=0x16 or 0x17)
when it wishes to open a stream but is unable to do so due to the
maximum stream limit set by its peer.  A WT_STREAMS_BLOCKED frame of
type 0x16 is used to indicate reaching the bidirectional stream
limit, and a STREAMS_BLOCKED frame of type 0x17 is used to indicate
reaching the unidirectional stream limit.
A WT_STREAMS_BLOCKED frame does not open the stream, but informs the
peer that a new stream was needed and the stream limit prevented the
creation of the stream.
A sender SHOULD send a frame (type=0x16 or 0x17) when it wishes to
open a stream but is unable to do so due to the maximum stream limit
set by its peer.  A frame of type 0x16 is used to indicate reaching
the bidirectional stream limit, and a STREAMS_BLOCKED frame of type
0x17 is used to indicate reaching the unidirectional stream limit.
A frame does not open the stream, but informs the peer that a new
stream was needed and the stream limit prevented the creation of the
stream.
The WT_DATAGRAM frame type (0x31) is used to carry datagram traffic.
Frame type 0x30 is also reserved to maintain parity with QUIC, but
unused, as all WebTransport frames MUST contain a length field.
The data in WT_DATAGRAM frames is not subject to flow control.  The
receiver MAY discard this data if it does not have sufficient space
to buffer it.
An intermediary could forward the data in a WT_DATAGRAM frame over
another protocol, such as WebTransport over HTTP/3.  In QUIC, a
datagram frame can span at most one packet.  Because of that, the
applications have to know the maximum size of the datagram they can
send.  However, when proxying the datagrams, the hop-by-hop MTUs can
vary.
The frame type (0x31) is used to carry datagram traffic.  Frame type
0x30 is also reserved to maintain parity with QUIC, but unused, as
all WebTransport frames MUST contain a length field.
The data in frames is not subject to flow control.  The receiver MAY
discard this data if it does not have sufficient space to buffer it.
An intermediary could forward the data in a frame over another
protocol, such as WebTransport over HTTP/3.  In QUIC, a datagram
frame can span at most one packet.  Because of that, the applications
have to know the maximum size of the datagram they can send.
However, when proxying the datagrams, the hop-by-hop MTUs can vary.
An example of the server initiating a WebTransport Stream follows.
The only difference here is the endpoint that sends the first
WT_STREAM frame.
An example of the server initiating a WebTransport Stream follows.
The only difference here is the endpoint that sends the first frame.