Draft: draft-ietf-quic-qpack

Commentary: This does n't do qpack because qpack is weird and needs a lot more work . The places where I kept backticks are for the inline formulae that were used for the reserved codepoints . That seemed like it was worth quoting somehow still . I also kept backticks for references to variables in examples . However , this last principle really hurts in qpack and I do n't know what to do about that . ( we 'll need another issue for qpack ) . 
 I can merge this and we can deal with qpack separately . 
 In I came up with a principle that might apply to use of . Field names , frame names , transport parameter names , and error codes do n't use any form of decoration . But if reference is being made to a variable in pseudocode , we would use backticks to distinguish it from . Qpack is a little tricky here because there is a mix of things . Note : backticks are quoted in for HTML and in double quotes ( ) in text output . Sparing use is probably best . 
 We 're somewhat inconsistent about whether transport parameters et al . get backticks or not across the documents . For example , Same goes for error code names , frame types , etc . 
 I think that - at this point - the overwhelming majority of parameter names are not quoted in any way and do go in and add backticks to all of them would be tiresome . However , most are in snakecase , CamelCase , Title Case , or SHOUTINGCASE so they are almost always distinguishable anyway . I grepped through and we have 38 instances of backticks . Most of these are in -http and -qpack . Most of them are in the description of reserved codepoints . I 'm going to suggest we remove the others .
Paragraph (version A):
An encoder stream is a unidirectional stream of type "0x02".  It
carries an unframed sequence of encoder instructions from encoder
to decoder.
Paragraph (version A):
A decoder stream is a unidirectional stream of type "0x03".  It
carries an unframed sequence of decoder instructions from decoder
to encoder.
Paragraph (version B):
An encoder stream is a unidirectional stream of type 0x02.  It
carries an unframed sequence of encoder instructions from encoder
to decoder.
Paragraph (version B):
A decoder stream is a unidirectional stream of type 0x03.  It
carries an unframed sequence of decoder instructions from decoder
to encoder.
Paragraph (version A):
If an implementation wishes to advise its peer of this limit, it can
be conveyed as a number of bytes in the
"SETTINGS_MAX_FIELD_SECTION_SIZE" parameter.  An implementation which
has received this parameter SHOULD NOT send an HTTP message header
which exceeds the indicated size, as the peer will likely refuse to
process it.  However, because this limit is applied at each hop,
messages below this limit are not guaranteed to be accepted.
Paragraph (version B):
If an implementation wishes to advise its peer of this limit, it can
be conveyed as a number of bytes in the
SETTINGS_MAX_FIELD_SECTION_SIZE parameter.  An implementation which
has received this parameter SHOULD NOT send an HTTP message header
which exceeds the indicated size, as the peer will likely refuse to
process it.  However, because this limit is applied at each hop,
messages below this limit are not guaranteed to be accepted.
Paragraph (version A):
A request or response that includes a payload body can include a
"content-length" header field.  A request or response is also
malformed if the value of a content-length header field does not
equal the sum of the DATA frame payload lengths that form the body.
A response that is defined to have no payload, as described in
Section 6.3.3 of SEMANTICS can have a non-zero content-length field,
even though no content is included in DATA frames.
Paragraph (version B):
A request or response that includes a payload body can include a
Content-Length header field.  A request or response is also malformed
if the value of a content-length header field does not equal the sum
of the DATA frame payload lengths that form the body.  A response
that is defined to have no payload, as described in Section 6.3.3 of
SEMANTICS can have a non-zero content-length field, even though no
content is included in DATA frames.
Paragraph (version A):
A control stream is indicated by a stream type of "0x00".  Data on
this stream consists of HTTP/3 frames, as defined in frames.
Paragraph (version B):
A control stream is indicated by a stream type of 0x00.  Data on this
stream consists of HTTP/3 frames, as defined in frames.
Paragraph (version A):
A push stream is indicated by a stream type of "0x01", followed by
the Push ID of the promise that it fulfills, encoded as a variable-
length integer.  The remaining data on this stream consists of HTTP/3
frames, as defined in frames, and fulfills a promised server push by
zero or more interim HTTP responses followed by a single final HTTP
response, as defined in request-response.  Server push and Push IDs
are described in server-push.
Paragraph (version B):
A push stream is indicated by a stream type of 0x01, followed by the
Push ID of the promise that it fulfills, encoded as a variable-length
integer.  The remaining data on this stream consists of HTTP/3
frames, as defined in frames, and fulfills a promised server push by
zero or more interim HTTP responses followed by a single final HTTP
response, as defined in request-response.  Server push and Push IDs
are described in server-push.
Paragraph (version A):
The "extension_data" field of the quic_transport_parameters extension
contains a value that is defined by the version of QUIC that is in
use.
Paragraph (version B):
The extension_data field of the quic_transport_parameters extension
contains a value that is defined by the version of QUIC that is in
use.
Paragraph (version A):
An endpoint also MUST NOT send packets from a different local
address, actively initiating migration, if the peer sent the
"disable_active_migration" transport parameter during the handshake.
An endpoint which has sent this transport parameter, but detects that
a peer has nonetheless migrated to a different network MUST either
drop the incoming packets on that path without generating a stateless
reset or proceed with path validation and allow the peer to migrate.
Generating a stateless reset or closing the connection would allow
third parties in the network to cause connections to close by
spoofing or otherwise manipulating observed traffic.
Paragraph (version B):
An endpoint also MUST NOT send packets from a different local
address, actively initiating migration, if the peer sent the
disable_active_migration transport parameter during the handshake.
An endpoint which has sent this transport parameter, but detects that
a peer has nonetheless migrated to a different network MUST either
drop the incoming packets on that path without generating a stateless
reset or proceed with path validation and allow the peer to migrate.
Generating a stateless reset or closing the connection would allow
third parties in the network to cause connections to close by
spoofing or otherwise manipulating observed traffic.
Paragraph (version A):
receiver's "max_ack_delay" value in determining timeouts for timer-
based retransmission, as detailed in Section 5.2.1 of QUIC-RECOVERY.
Paragraph (version B):
receiver's max_ack_delay value in determining timeouts for timer-
based retransmission, as detailed in Section 5.2.1 of QUIC-RECOVERY.
Paragraph (version A):
A variable-length integer representing the time delta in
microseconds between when this ACK was sent and when the largest
acknowledged packet, as indicated in the Largest Acknowledged
field, was received by this peer.  The value of the ACK Delay
field is scaled by multiplying the encoded value by 2 to the power
of the value of the "ack_delay_exponent" transport parameter set
by the sender of the ACK frame; see transport-parameter-
definitions.  Scaling in this fashion allows for a larger range of
values with a shorter encoding at the cost of lower resolution.
Because the receiver doesn't use the ACK Delay for Initial and
Handshake packets, a sender SHOULD send a value of 0.
Paragraph (version B):
A variable-length integer representing the time delta in
microseconds between when this ACK was sent and when the largest
acknowledged packet, as indicated in the Largest Acknowledged
field, was received by this peer.  The value of the ACK Delay
field is scaled by multiplying the encoded value by 2 to the power
of the value of the ack_delay_exponent transport parameter set by
the sender of the ACK frame; see transport-parameter-definitions.
Scaling in this fashion allows for a larger range of values with a
shorter encoding at the cost of lower resolution.  Because the
receiver doesn't use the ACK Delay for Initial and Handshake
packets, a sender SHOULD send a value of 0.
Paragraph (version A):
Additionally, each value of the format "31 * N + 27" for integer
values of N (that is, "27", "58", "89", ...) are reserved and MUST
NOT be assigned by IANA.
Paragraph (version B):
Additionally, each value of the format "31 * N + 27" for integer
values of N (that is, 27, 58, 89, ...) are reserved and MUST NOT be
assigned by IANA.