Draft: draft-ietf-quic-transport

Commentary: All references to figures that describe frame formats are changed to use the form : " X frames are formatted as shown in { { x } } . " This retains some of the extra details so that the change is limited to this change , but I made the empty frame description consistent throughout ( with a little extra explanation for PADDING , which is first ) . 
 This is a good improvement , but I disagree that it addresses . That was intended to be about the section headings , in which some are " X Frame " and others are " X Frames " : 
 My bad . I had forgotten that bit . I made these plural and changed definitions from " the X frame " to " a[n ] X frame " . For the multi - valued types , we were also inconsistent with use of " or " vs. " and " , so I changed that to match . 
 In the Frame Types section ( 19.x ) , the types which span multiple IDs are identified as " STREAM Frames " , " ACK Frames " , and " CONNECTIONCLOSE Frames " while all other frame types are singular ( " NEWTOKEN Frame " ) . I initially thought it was just a typo , but it 's consistently done for everything that has embedded flags . Raising an editorial issue to double - check if we want to retain a convention that looks like an error on first glance . If the editors say yes , feel free to close with no objection from me . 
 I made this change quite deliberately , but I 'm happy to take input on why " Frame " is clearer . 
 I suggest that we use the singular , since these sections are definitions of these frame types . 
 Two reasons . The first is simply consistency -- something technically correct that still looks like an error might not be worth defending . The second is the question of whether there are in fact multiple types versus a single type with flags . I can see the alternate view , that there are two different ACK frames and the section describes those two frame types . The same is true for CONNECTION_CLOSE , where there are two types with different implications . Both of these were two distinct frame types in previous drafts . For me , that view breaks down with STREAM , unless you want to say there are eight types of STREAM frame and the section describes all eight . The section describes a single STREAM frame with flags embedded in the type byte . 
 I 've seen implementations handle it both ways : one struct with a type , and many structs . My suggestion would be to define a term , then it is editorially pleasant to say something like 
 I 'm ambivalent on " frame " vs. " frames " here , but I will oppose any attempt to add to the cognitive load on readers . New terms are out for me . 
 How about we refer to frames collectively always instead and say " X frames are formatted as shown in { { x } } . " 
 Works for me . 
 Thanks !
Paragraph (version A):
The PADDING frame (type=0x00) has no semantic value.  PADDING frames
can be used to increase the size of a packet.  Padding can be used to
increase an initial client packet to the minimum required size, or to
provide protection against traffic analysis for protected packets.
Paragraph (version A):
As shown in padding-format, a PADDING frame has no content.  That is,
a PADDING frame consists of the single byte that identifies the frame
as a PADDING frame.
Paragraph (version A):
Endpoints can use PING frames (type=0x01) to verify that their peers
are still alive or to check reachability to the peer.  As shown in
ping-format, a PING frame has no content.
Paragraph (version B):
A PADDING frame (type=0x00) has no semantic value.  PADDING frames
can be used to increase the size of a packet.  Padding can be used to
increase an initial client packet to the minimum required size, or to
provide protection against traffic analysis for protected packets.
Paragraph (version B):
PADDING frames are formatted as shown in padding-format, which shows
that PADDING frames have no content.  That is, a PADDING frame
consists of the single byte that identifies the frame as a PADDING
frame.
Paragraph (version B):
Endpoints can use PING frames (type=0x01) to verify that their peers
are still alive or to check reachability to the peer.
Paragraph (version B):
PING frames are formatted as shown in ping-format, which shows that
PING frames have no content.
Paragraph (version A):
An ACK frame is shown in ack-format.
Paragraph (version B):
ACK frames are formatted as shown in ack-format.
Paragraph (version A):
The RESET_STREAM frame is shown in fig-reset-stream.
Paragraph (version B):
RESET_STREAM frames are formatted as shown in fig-reset-stream.
Paragraph (version A):
The STOP_SENDING frame is shown in fig-stop-sending.
Paragraph (version B):
STOP_SENDING frames are formatted as shown in fig-stop-sending.
Paragraph (version A):
The CRYPTO frame (type=0x06) is used to transmit cryptographic
handshake messages.  It can be sent in all packet types except 0-RTT.
The CRYPTO frame offers the cryptographic protocol an in-order stream
of bytes.  CRYPTO frames are functionally identical to STREAM frames,
except that they do not bear a stream identifier; they are not flow
controlled; and they do not carry markers for optional offset,
optional length, and the end of the stream.
Paragraph (version B):
A CRYPTO frame (type=0x06) is used to transmit cryptographic
handshake messages.  It can be sent in all packet types except 0-RTT.
The CRYPTO frame offers the cryptographic protocol an in-order stream
of bytes.  CRYPTO frames are functionally identical to STREAM frames,
except that they do not bear a stream identifier; they are not flow
controlled; and they do not carry markers for optional offset,
optional length, and the end of the stream.
Paragraph (version A):
The CRYPTO frame is shown in fig-crypto.
Paragraph (version B):
CRYPTO frames are formatted as shown in fig-crypto.
Paragraph (version A):
The NEW_TOKEN frame is shown in fig-new-token.
Paragraph (version B):
NEW_TOKEN frames are formatted as shown in fig-new-token.
Paragraph (version A):
The STREAM frames are shown in fig-stream.
Paragraph (version B):
STREAM frames are formatted as shown in fig-stream.
Paragraph (version A):
The MAX_DATA frame (type=0x10) is used in flow control to inform the
peer of the maximum amount of data that can be sent on the connection
as a whole.
Paragraph (version A):
The MAX_DATA frame is shown in fig-max-data.
Paragraph (version B):
A MAX_DATA frame (type=0x10) is used in flow control to inform the
peer of the maximum amount of data that can be sent on the connection
as a whole.
Paragraph (version B):
MAX_DATA frames are formatted as shown in fig-max-data.
Paragraph (version A):
The MAX_STREAM_DATA frame (type=0x11) is used in flow control to
inform a peer of the maximum amount of data that can be sent on a
stream.
Paragraph (version B):
A MAX_STREAM_DATA frame (type=0x11) is used in flow control to inform
a peer of the maximum amount of data that can be sent on a stream.
Paragraph (version A):
The MAX_STREAM_DATA frame is shown in fig-max-stream-data.
Paragraph (version B):
MAX_STREAM_DATA frames are formatted as shown in fig-max-stream-data.
Paragraph (version A):
The MAX_STREAMS frames (type=0x12 and 0x13) inform the peer of the
cumulative number of streams of a given type it is permitted to open.
A MAX_STREAMS frame with a type of 0x12 applies to bidirectional
streams, and a MAX_STREAMS frame with a type of 0x13 applies to
unidirectional streams.
Paragraph (version B):
A MAX_STREAMS frame (type=0x12 or 0x13) inform the peer of the
cumulative number of streams of a given type it is permitted to open.
A MAX_STREAMS frame with a type of 0x12 applies to bidirectional
streams, and a MAX_STREAMS frame with a type of 0x13 applies to
unidirectional streams.
Paragraph (version A):
The DATA_BLOCKED frame is shown in fig-data-blocked.
Paragraph (version B):
DATA_BLOCKED frames are formatted as shown in fig-data-blocked.
Paragraph (version A):
The STREAM_DATA_BLOCKED frame is shown in fig-stream-data-blocked.
Paragraph (version B):
STREAM_DATA_BLOCKED frames are formatted as shown in fig-stream-data-
blocked.
Paragraph (version A):
The STREAMS_BLOCKED frames are shown in fig-streams-blocked.
Paragraph (version B):
STREAMS_BLOCKED frames are formatted as shown in fig-streams-blocked.
Paragraph (version A):
The NEW_CONNECTION_ID frame is shown in fig-new-connection-id.
Paragraph (version B):
NEW_CONNECTION_ID frames are formatted as shown in fig-new-
connection-id.
Paragraph (version A):
The RETIRE_CONNECTION_ID frame is shown in fig-retire-connection-id.
Paragraph (version B):
RETIRE_CONNECTION_ID frames are formatted as shown in fig-retire-
connection-id.
Paragraph (version A):
The PATH_CHALLENGE frame is shown in fig-path-challenge.
Paragraph (version B):
PATH_CHALLENGE frames are formatted as shown in fig-path-challenge.
Paragraph (version A):
The PATH_RESPONSE frame (type=0x1b) is sent in response to a
PATH_CHALLENGE frame.  Its format, shown in fig-path-response is
identical to the PATH_CHALLENGE frame (frame-path-challenge).
Paragraph (version B):
A PATH_RESPONSE frame (type=0x1b) is sent in response to a
PATH_CHALLENGE frame.
Paragraph (version B):
PATH_RESPONSE frames are formatted as shown in fig-path-response,
which is identical to the PATH_CHALLENGE frame (frame-path-
challenge).
Paragraph (version A):
The CONNECTION_CLOSE frames are shown in fig-connection-close.
Paragraph (version B):
CONNECTION_CLOSE frames are formatted as shown in fig-connection-
close.
Paragraph (version A):
The server uses the HANDSHAKE_DONE frame (type=0x1e) to signal
confirmation of the handshake to the client.  As shown in handshake-
done-format, a HANDSHAKE_DONE frame has no content.
Paragraph (version B):
The server uses a HANDSHAKE_DONE frame (type=0x1e) to signal
confirmation of the handshake to the client.
Paragraph (version B):
HANDSHAKE_DONE frames are formatted as shown in handshake-done-
format, which shows that HANDSHAKE_DONE frames have no content.