jiebi/ids-paragraph-commentary-corpus huggingface dataset:
Draft: draft-ietf-quic-transport

Commentary: The first inverts the description of " ih " to be clearer . The second makes it clearer for IANA that the " packets " column can be ignored .
Paragraph (version A):
A CONNECTION_CLOSE frame of type 0x1d cannot appear in Initial or
Handshake packets.
Paragraph (version B):
Only a CONNECTION_CLOSE frame of type 0x1c can appear in Initial
or Handshake packets.
Paragraph (version A):
The initial contents of this registry are tabulated in frame-types.
Paragraph (version B):
The initial contents of this registry are tabulated in frame-types.
Note that the registry does not include the "Packets" column from
frame-types.
Draft: draft-ietf-quic-transport

Commentary:    suggestions , which seem quite reasonable . 
 ( 1 ) NiT : /The ECN counter for the ECN codepoint received in the associated IP header are incremented once for each QUIC packet , not per enclosing IP packet or UDP datagram./ mixed singular and plural - is this /counters/ ? ( 2 ) I like this phrase in the security considerations also from the point of view of how to generate transport feedback for ECT ( ? ) . Can we call this out here : /QUIC endpoints ignore the ECN codepoint field on an IP packet unless at least one QUIC packet in that IP packet is successfully processed/ ( 3 ) General experiments are not permitted in RFC8311 , only using experimental RFCs . I think therefore , we should be clear in the detail here : /Implementations MAY experiment with and use other strategies for use of ECN . Other methods of probing paths for ECN support are possible , as are different marking strategies . Implementations can also use the ECT(1 ) codepoint , as specified in { { ? RFC8311}}./ I ’d propose something more like this : /Other methods of probing paths for ECN support are possible , as are different marking strategies . Implementations MAY use other methods defined in RFCs , as specified in { { ? RFC8311 } } . Implementations that use the ECT(1 ) codepoint , need to perform ECN validation using this code point./
Paragraph (version A):
A packet detected by a receiver as a duplicate does not affect the
receiver's local ECN codepoint counts; see (security-ecn) for
relevant security concerns.
Paragraph (version B):
An IP packet that results in no QUIC packets being processed does not
increase ECN counts.  A QUIC packet detected by a receiver as a
duplicate does not affect the receiver's local ECN codepoint counts;
see security-ecn for relevant security concerns.
Paragraph (version A):
Coalesced packets (see packet-coalesce) mean that several packets can
share the same IP header.  The ECN counter for the ECN codepoint
received in the associated IP header are incremented once for each
QUIC packet, not per enclosing IP packet or UDP datagram.
Paragraph (version B):
Coalesced packets (see packet-coalesce) mean that several packets can
share the same IP header.  The ECN counts for the ECN codepoint
received in the associated IP header are incremented once for each
QUIC packet, not per enclosing IP packet or UDP datagram.
Paragraph (version A):
Implementations MAY experiment with and use other strategies for use
of ECN.  Other methods of probing paths for ECN support are possible,
as are different marking strategies.  Implementations can also use
the ECT(1) codepoint, as specified in RFC8311.
Paragraph (version B):
Other methods of probing paths for ECN support are possible, as are
different marking strategies.  Implementations MAY use other methods
defined in RFCs; see RFC8311.  Implementations that use the ECT(1)
codepoint need to perform ECN validation using ECT(1) counts.
Draft: draft-ietf-quic-transport

Commentary: I did not add a citation for MAX_PLPMTU as that is subtly different and that seems like it would be more of a liability than a help in this case . 
 Text looks OK . 
 In maxudppayloadsize ( 0x03 ) the following text seems good : /This limit does act as an additional constraint on datagram size in the same way as the path MTU , but it is a property of the endpoint and not the path./ could it refer to the appropriate section in the QUIC spec ? In DPLPMTUD the same value is known as “ MAXPLPMTU ” , Section 5.3.1 - in case you wish to cite that . 
 MAX_PLPMTU is slightly different as it refers to the IP layer , but you are right that it constrains the same underlying variable . I 'll add a cross - reference though .
Paragraph (version A):
This limit does act as an additional constraint on datagram size
in the same way as the path MTU, but it is a property of the
endpoint and not the path.  It is expected that this is the space
an endpoint dedicates to holding incoming packets.
Paragraph (version B):
This limit does act as an additional constraint on datagram size
in the same way as the path MTU, but it is a property of the
endpoint and not the path; see packet-size.  It is expected that
this is the space an endpoint dedicates to holding incoming
packets.
Draft: draft-ietf-quic-transport

Commentary: I think that this can be this simple . 
 section : Address Validation for Future Connections The following RFC2119 keyword appears within a note , which seems wrong , could the RFC2119 recommendation be moved outside of the note ? : /A server SHOULD encode tokens provided with NEW_TOKEN frames and Retry packets differently , and validate the latter more strictly./
Paragraph (version A):
When a server receives an Initial packet with an address validation
token, it MUST attempt to validate the token, unless it has already
completed address validation.  If the token is invalid then the
server SHOULD proceed as if the client did not have a validated
address, including potentially sending a Retry.  If the validation
succeeds, the server SHOULD then allow the handshake to proceed.
Paragraph (version A):
The rationale for treating the client as unvalidated rather than
discarding the packet is that the client might have received the
token in a previous connection using the NEW_TOKEN frame, and if
the server has lost state, it might be unable to validate the
token at all, leading to connection failure if the packet is
discarded.  A server SHOULD encode tokens provided with NEW_TOKEN
frames and Retry packets differently, and validate the latter more
strictly.
Paragraph (version B):
When a server receives an Initial packet with an address validation
token, it MUST attempt to validate the token, unless it has already
completed address validation.  If the token is invalid then the
server SHOULD proceed as if the client did not have a validated
address, including potentially sending a Retry.  A server SHOULD
encode tokens provided with NEW_TOKEN frames and Retry packets
differently, and validate the latter more strictly.  If the
validation succeeds, the server SHOULD then allow the handshake to
proceed.
Paragraph (version B):
The rationale for treating the client as unvalidated rather than
discarding the packet is that the client might have received the
token in a previous connection using the NEW_TOKEN frame, and if
the server has lost state, it might be unable to validate the
token at all, leading to connection failure if the packet is
discarded.
Draft: draft-ietf-quic-transport

Commentary: Section : Stream Final Size /An endpoint MUST NOT send data on a stream at or beyond the final size./ It seems reasonable not to send after the Final Size , but why is this a “ MUST NOT ” ? The need to require this is not stated , and the reaction of the receiver appears to be ignore . Is this requirement justified ? 
 Because the Final Size is used to synchronize flow control consumption . If the Final Size is not , in fact , the last data ever sent on a stream , the two sides will disagree about how much flow control credit has been consumed . The reaction of the receiver is n't to ignore ; in the very next paragraph : 
 Aha , I knew there must be a reason - could we add something like this sentence ? " This is used to synchronize flow control consumption between the endpoints . " 
 : +1 : LGTM modulo a nitpick . Some suggestions
Paragraph (version A):
For a stream that is reset, the final size is carried explicitly in a
RESET_STREAM frame.  Otherwise, the final size is the offset plus the
length of a STREAM frame marked with a FIN flag, or 0 in the case of
incoming unidirectional streams.
Paragraph (version B):
The final size of a stream is always signaled to the recipient.  The
final size is the sum of the Offset and Length fields of a STREAM
frame with a FIN flag, noting that these fields might be implicit.
Alternatively, the Final Size field of a RESET_STREAM frame carries
this value.  This ensures that all ways that a stream can be closed
result in the number of bytes on the stream being reliably
transmitted.  This guarantees that both endpoints agree on how much
flow control credit was consumed by the stream.
Draft: draft-ietf-quic-transport

Commentary: An attempt to make this slightly easier to read , based on feedback that this was hard to read and follow . 
 Looks good , but I think the paragraph on lines 1574 to 1582 might be best split too , into sub - paragraphs for each TP and how it 's used .
Paragraph (version A):
For the handshakes in fig-auth-cid and fig-auth-cid-retry the client
sets the value of the initial_source_connection_id transport
parameter to "C1".  In fig-auth-cid-retry, the server sets
original_destination_connection_id to "S1",
retry_source_connection_id to "S2", and initial_source_connection_id
to "S3".  In fig-auth-cid, the server sets
original_destination_connection_id to "S1",
initial_source_connection_id to "S3", and does not include
retry_source_connection_id.  Each endpoint validates the transport
parameters set by their peer, including the client confirming that
retry_source_connection_id is absent if no Retry packet was
processed.
Paragraph (version B):
In both cases (fig-auth-cid and fig-auth-cid-retry), the client sets
the value of the initial_source_connection_id transport parameter to
"C1".
Paragraph (version B):
When the handshake does not include a Retry (fig-auth-cid), the
server sets original_destination_connection_id to "S1" and
initial_source_connection_id to "S3".  In this case, the server does
not include a retry_source_connection_id transport parameter.
Paragraph (version B):
When the handshake includes a Retry (fig-auth-cid-retry), the server
sets original_destination_connection_id to "S1",
retry_source_connection_id to "S2", and initial_source_connection_id
to "S3".
Paragraph (version B):
Each endpoint validates transport parameters set by the peer.  The
client confirms that the retry_source_connection_id transport
parameter is absent if it did not process a Retry packet.
Draft: draft-ietf-quic-transport

Commentary: The longer the draft sits in my edit buffer , the more opportunities I have to see this sort of thing .
Paragraph (version A):
The application-specific variant of CONNECTION_CLOSE (type 0x1d) can
only be sent using 0-RTT or 1-RTT packets (QUIC-TLS, Section 4).
When an application wishes to abandon a connection during the
handshake, an endpoint can send a CONNECTION_CLOSE frame (type 0x1c)
with an error code of APPLICATION_ERROR in an Initial or a Handshake
packet.
Paragraph (version B):
The application-specific variant of CONNECTION_CLOSE (type 0x1d) can
only be sent using 0-RTT or 1-RTT packets; see Section 4 of QUIC-TLS.
When an application wishes to abandon a connection during the
handshake, an endpoint can send a CONNECTION_CLOSE frame (type 0x1c)
with an error code of APPLICATION_ERROR in an Initial or a Handshake
packet.
Draft: draft-ietf-quic-recovery

Commentary: Section 3.1 is the only subsection in section 3 , and it makes sense to promote it to its own section . This PR also fixes references to Section 3.1 ( and a few others that needed correction ) from the transport draft . 
 Yeah , I know , I was going to do that separately . But fair enough . I 'll get that in tomorrow . 
 There do n't appear to be too many to fix up : This seems to cover it . 
 Ok , I think I got them all . Some of the references were broken , so fixed them . 
 Could I ask why you are not giving section headers IDs ( via ) ? When you then use in the text , it turns into ( if you gave that section that ID . ) Which means no more manual updating section numbers on references . ( These IDs even get automatically and you can just use those . See " Automatic Generation of Header IDs " on But those can be long and awkward , which is why I prefer manual IDs . ) 
 that works within the document , it does n't work across documents . These references are in transport for sections in recovery . 
  . 
 tracks a feature request to support cross - document references with similar syntax , but it 's challenging . 
 Section 3 has just one subsection , which goes into detail about how QUIC is similar and different than TCP . This might be better as its own top - level section . I was always taught to avoid a ) sections that only subsections and no text of their own , b ) sections that have precisely one subsection , c ) lists with fewer than 3 items in them . 
 Thanks  , LG . Can you update the PR title and/or description to be a bit more descriptive ?
Paragraph (version A):
Initial packets and Handshake packets could be never acknowledged,
but they are removed from bytes in flight when the Initial and
Handshake keys are discarded, as described below in Section
discarding-packets.  When Initial or Handshake keys are discarded,
the PTO and loss detection timers MUST be reset, because discarding
keys indicates forward progress and the loss detection timer might
have been set for a now discarded packet number space.
Paragraph (version B):
Initial packets and Handshake packets could be never acknowledged,
but they are removed from bytes in flight when the Initial and
Handshake keys are discarded, as described below in discarding-
packets.  When Initial or Handshake keys are discarded, the PTO and
loss detection timers MUST be reset, because discarding keys
indicates forward progress and the loss detection timer might have
been set for a now discarded packet number space.
Draft: draft-ietf-quic-transport

Commentary: I noticed these when re - reading the text . 
 Thanks .
Paragraph (version A):
A minimum size of 21 bytes does not guarantee that a stateless reset
is difficult to distinguish from other packets if the recipient
requires the use of a connection ID.  To prevent a resulting
stateless reset from being trivially distinguishable from a valid
packet, all packets sent by an endpoint SHOULD be padded to at least
22 bytes longer than the minimum connection ID that the endpoint
might use.  An endpoint that sends a stateless reset in response to
packet that is 43 bytes or less in length SHOULD send a stateless
reset that is one byte shorter than the packet it responds to.
Paragraph (version A):
These values assume that the Stateless Reset Token is the same as the
minimum expansion of the packet protection AEAD.  Additional
unpredictable bytes are necessary if the endpoint could have
negotiated a packet protection scheme with a larger minimum
expansion.
Paragraph (version B):
A minimum size of 21 bytes does not guarantee that a stateless reset
is difficult to distinguish from other packets if the recipient
requires the use of a connection ID.  To prevent a resulting
stateless reset from being trivially distinguishable from a valid
packet, all packets sent by an endpoint SHOULD be padded to at least
22 bytes longer than the minimum connection ID that the endpoint
might use.  An endpoint that sends a stateless reset in response to a
packet that is 43 bytes or less in length SHOULD send a stateless
reset that is one byte shorter than the packet it responds to.
Paragraph (version B):
These values assume that the Stateless Reset Token is the same length
as the minimum expansion of the packet protection AEAD.  Additional
unpredictable bytes are necessary if the endpoint could have
negotiated a packet protection scheme with a larger minimum
expansion.
Draft: draft-ietf-quic-http

Commentary: by reversing the polarity of a SHOULD . Does n't break interop , but it 's always safer to send CANCEL_PUSH than to omit it , so let 's not recommend omitting it under any circumstances . 
 The spec suggest that a server should send a CANCELPUSH to notify a client that it will not fulfill a PUSHPROMISE . The server should send CANCELPUSH before a push stream has been open . The server still can cancel a push stream after it has been created and that will have a similar effect as a CANCELPUSH frame . There is a small problem with that . If the server resets a push stream before client starts reading , the client may have not read the pushid from the stream and that pushid will never be fulfill or cancel for the client point of view . Should there be a sentence in the spec explaining this ? Probably suggesting not to cancel a push stream until server is certain that client has read it , which is difficult . Should the spec suggest ot send CANCEL_PUSH even after a push stream has been created ? 
 The server does n't need to ensure that the push ID is read if CANCELPUSH is used , mostly . If the stream type is read , but not the push ID ( which is entirely possible ) , then the client will know that there was a push and that it did n't happen , but ca n't connect that with the promise or cancellation . In that case , clients need to handle that . In fact , this highlights the value of CANCELPUSH in the case where the stream is reset . 
 This will not break interop either way . We can change the recommendation easily . 
 This issue and its fix has been pretty well discussed already . The proposal is borderline on a design change , so I 've marked this as design to get some visibility during the next consensus call . 
 lgtm
Paragraph (version A):
When a server sends CANCEL_PUSH, it is indicating that it will not be
fulfilling a promise and has not created a push stream.  The client
should not expect the corresponding promise to be fulfilled.
Paragraph (version A):
Sending CANCEL_PUSH has no direct effect on the state of existing
push streams.  A server SHOULD NOT send a CANCEL_PUSH when it has
already created a corresponding push stream, and a client SHOULD NOT
send a CANCEL_PUSH when it has already received a corresponding push
stream.  If a push stream arrives after a client has sent
CANCEL_PUSH, this MAY be treated as a stream error of type
H3_STREAM_CREATION_ERROR.
Paragraph (version B):
When a server sends CANCEL_PUSH, it is indicating that it will not be
fulfilling a promise.  The client cannot expect the corresponding
promise to be fulfilled, unless it has already received and processed
the promised response.  A server SHOULD send a CANCEL_PUSH even if it
has opened the corresponding stream.
Paragraph (version B):
Sending CANCEL_PUSH has no direct effect on the state of existing
push streams.  A client SHOULD NOT send a CANCEL_PUSH when it has
already received a corresponding push stream.  A push stream could
arrive after a client has sent CANCEL_PUSH, because a server might
not have processed the CANCEL_PUSH.  The client SHOULD abort reading
the stream with an error code of H3_REQUEST_CANCELLED.
Draft: draft-ietf-quic-transport

Commentary: I do n't see much point in doing the same for invariants , but I 'm willing to take input on that choice . 
 The chairs just had a question from someone who wanted to cite " QUIC " on what document they should be citing . We responded that they should cite -transport , since we see this as the central document . Should we add brief notes to the documents saying " if you want to cite QUIC , cite -transport " ? 
 That seems reasonable , since we say in there that accompanying documents describe TLS and recovery . Where are you thinking of adding that note ? 
 As early as possible ? 
 If you want to cite QUIC version 1 , transport . If you want to cite QUIC all - up , invariants . 
 , or immediately after it , seems like as good a place as any . 
 I probably would have made it part of the preceding paragraph , but I do n't feel strongly .
Paragraph (version B):
To refer to QUIC version 1, cite this document.  References to the
limited set of version-independent properties of QUIC can cite QUIC-
INVARIANTS.
Draft: draft-ietf-quic-transport

Commentary: As discussed in , most of the errors that can occur when authenticating connection IDs should be TRANSPORTPARAMETERERRORs , not PROTOCOL_VIOLATIONs . 
 This changes the error codes that we require , so it is technically a design change . I think we 'll need an issue to track this . 
 Created . 
 The guiding principle here ( as we apply it for FRAMEENCODINGERRORs ) is that if an error is detectable without accessing connection state , we use the more specific error . So for example , since and are required transport parameters , their absence should be responded to with a TRANSPORTPARAMETERERROR . A similar argument applies to the absence of the TP , although I can see how one might use PROTOCOLVIOLATION here ( note that this is still valid behavior with this PR , as every more specific error can be replaced with a PROTOCOL_VIOLATION , if an implementation wishes to do so ) . 
 Thanks . I think that this is fine . I will make a few editorial comments on the PR , but I think that the application of the agreed principles is correct . 
 If you take the suggestions here , I will mark this for inclusion in the next consensus call . ( Otherwise , we should continue discussion . )
Paragraph (version A):
absence of the initial_source_connection_id transport parameter
from either endpoint,
Paragraph (version A):
absence of the original_destination_connection_id transport
parameter from the server,
Paragraph (version B):
The values provided by a peer for these transport parameters MUST
match the values that an endpoint used in the Destination and Source
Connection ID fields of Initial packets that it sent.  Including
connection ID values in transport parameters and verifying them
ensures that that an attacker cannot influence the choice of
connection ID for a successful connection by injecting packets
carrying attacker-chosen connection IDs during the handshake.
Paragraph (version B):
An endpoint MUST treat absence of the initial_source_connection_id
transport parameter from either endpoint or absence of the
original_destination_connection_id transport parameter from the
server as a connection error of type TRANSPORT_PARAMETER_ERROR.