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

Commentary: Separately from this , I note that Security Considerations is becoming more of a jumbled bag of waving at various concerns . Some organization and expanded text around each topic might be warranted . 
 Can you add a sub - heading ( # # ) for each of these considerations , like in the transport draft ? Originally posted by in 
 Seems mostly right . Though I would prefer something that simply highlighted the fact that a remote address is not expected to be stable over the lifetime of a connection . Therefore , decisions that use an address as input need to either keep up to date , or accept the consequences of not doing so . I would also point out that this is true even if migration is disabled . The text looks great . I really appreciate the fact that we have a recommendation on what IP address we should associate with logging ( and address - based authentication ) .
Paragraph (version B):
Certain HTTP implementations use the client address for logging or
access-control purposes.  Since a QUIC client's address might change
during a connection (and future versions might support simultaneous
use of multiple addresses), such implementations will need to either
actively retrieve the client's current address or addresses when they
are relevant or explicitly accept that the original address might
change.
Draft: draft-ietf-quic-http

Commentary: This is my stab at adding the indication discussed in . 
 Lgtm . An minor  might be to highlight in the new sentence that " specific guidance is provided in the relevant section " but that might be obvious . I 'm happy without anything further .
Paragraph (version B):
Certain frames can only occur as the first frame of a particular
stream type; these are indicated in stream-frame-mapping with a (1).
Specific guidance is provided in the relevant section.
Draft: draft-ietf-quic-transport

Commentary: This fixes issue . 
 Thanks !
Paragraph (version B):
The sequence number specified in a RETIRE_CONNECTION_ID frame MUST
NOT refer to the Destination Connection ID field of the packet in
which the frame is contained.  The peer MAY treat this as a
connection error of type PROTOCOL_VIOLATION.
Draft: draft-ietf-quic-http

Commentary: So a friendly pointer to detail that could be easily misinterpreted or missed ? It seems like a table footnote is required but I 'm not sure how to do that in Markdown . 
 While each frame 's description indicates the stream type(s ) on which it is allowed , there is n't one unified place to indicate which frames are expected on which streams . QPACK subdivides the instruction space per stream , which has the nice property that you ca n't put something on the wrong stream . While that 's overkill for H3 ( too dramatic a departure from H2 , multiple IANA registries , etc . ) , having a table to indicate which frames are permitted on which streams would be helpful . 
 I like the table idea for both . Want a PR ? 
 Text always welcome . 
 I 'll submit two PRs in next day or so . 
 Minor nit ; otherwise good . Given that we have two frames that fall into this camp , might it be worth doing something like " ( * ) = only as the first frame " ?
Paragraph (version A):
As discussed above, frames are carried on QUIC streams and used on
control streams, request streams, and push streams.  This section
describes HTTP framing in QUIC.  For a comparison with HTTP/2 frames,
see h2-frames.
Paragraph (version B):
HTTP frames are carried on QUIC streams, as described in stream-
mapping.  HTTP/3 defines three stream types: control stream, request
stream, and push stream.  This section describes HTTP/3 frame formats
and the streams types on which they are permitted; see stream-frame-
mapping for an overiew.  A comparison between HTTP/2 and HTTP/3
frames is provided in h2-frames.
Draft: draft-ietf-quic-transport

Commentary: " # validate - future " is about tokens issued using a NEW_TOKEN frame .
Paragraph (version A):
A client sets the Destination Connection ID field of this Initial
packet to the value from the Source Connection ID in the Retry
packet.  Changing Destination Connection ID also results in a change
to the keys used to protect the Initial packet.  It also sets the
Token field to the token provided in the Retry.  The client MUST NOT
change the Source Connection ID because the server could include the
connection ID as part of its token validation logic (see validate-
future).
Paragraph (version B):
A client sets the Destination Connection ID field of this Initial
packet to the value from the Source Connection ID in the Retry
packet.  Changing Destination Connection ID also results in a change
to the keys used to protect the Initial packet.  It also sets the
Token field to the token provided in the Retry.  The client MUST NOT
change the Source Connection ID because the server could include the
connection ID as part of its token validation logic (see token-
integrity).
Draft: draft-ietf-quic-transport

Commentary: this is annoyingly close to done . Would you mind ? 
 : Take a look . 
 LGTM
Paragraph (version B):
When an endpoint has no validated path on which to send packets, it
MAY discard connection state.  An endpoint capable of connection
migration MAY wait for a new path to become available before
discarding connection state.
Paragraph (version B):
An endpoint MAY discard connection state if it does not have a
validated path on which it can send packets (see migrate-validate).
Draft: draft-ietf-quic-transport

Commentary: Recommendation to set the IPv6 flow label in accordance to RFC 6437 , as agreed in Tokyo . 
 I am a bit concerned that specifying the hash function would be overkill .  , HMAC , do we really care ? Are we really that concerned that developers are dumb and we must hold their hand ? 
 I think that all was asking for was an example . Even saying " a function based on a cryptographic hash " might help . 
 OK . I specified a " cryptographic hash " 
 fwiw is ( intentionally ) non - specific about the hash function . It says " If a hash algorithm is used , as suggested in Section 3 , it SHOULD include a step that makes the flow label value significantly difficult to predict [ RFC4086 ] , even with knowledge of the algorithm being used . " We did n't see any real need to specify a crypto hash for this purpose , but it 's certainly OK . ( The example in Appendix A of 6437 stinks and I regret it . ) 
 Mostly good , though plenty of nits . Let 's get chair confirmation before merging though . Can we give an example of a suitable one - way has function ?
Paragraph (version A):
This document defines the core of the QUIC transport protocol.
Accompanying documents describe QUIC's loss detection and congestion
control QUIC-RECOVERY and the use of TLS for key negotiation QUIC-
TLS.
Paragraph (version B):
Endpoints MUST explicitly negotiate an application protocol.  This
avoids situations where there is a disagreement about the protocol
that is in use.
Paragraph (version A):
A stateless reset will be interpreted by a recipient as a packet with
a short header.  For the packet to appear as valid, the Random Bits
field needs to include at least 182 bits of data (or 24 bytes, less
the two fixed bits).  This is intended to allow for a Destination
Connection ID of the maximum length permitted, with a minimal packet
number, and payload.  The Stateless Reset Token corresponds to the
minimum expansion of the packet protection AEAD.  More unpredictable
bytes might be necessary if the endpoint could have negotiated a
packet protection scheme with a larger minimum AEAD expansion.
Paragraph (version A):
Endpoints SHOULD send acknowledgments for packets containing CRYPTO
frames with a reduced delay; see Section 5.3.1 of QUIC-RECOVERY.
Paragraph (version A):
The ECN section should only be parsed when the ACK frame type is
0x03.  The ECN section consists of 3 ECN counts as shown below.
Draft: draft-ietf-quic-recovery

Commentary: In the recovery draft , RTT is briefly spelled out in section 5 but is used in several earlier sections . SRTT and PTO are not explained at all , it seems . TLP is spelled out . RTO has a section of its own but it referenced before that . The recovery doc can not be a tutorial on transmission theory , but it would be helpful to list the key acronyms and possibly reference an RFC with more details . There are already sections summarising key variables in pseudocode . There are references at the end , but the reader would have to go through them all . 
 Yes , thanks for the note . I 'm planning to do a cleanup of that doc soon . 
 I fixed defined RTT earlier in .
Paragraph (version A):
A sender calculates both smoothed RTT and RTT variance similar to
those specified in RFC6298, see on-ack-received.
Paragraph (version B):
A sender calculates both smoothed RTT (SRTT) and RTT variance
(RTTVAR) similar to those specified in RFC6298, see on-ack-received.
Draft: draft-ietf-quic-qpack

Commentary: Currently the draft is inconsistent : if the Required Insert Count value in a header block is smaller than dictated by the referenced dynamic table entries , { { overview - hol - avoidance } } says the decoder  treat this as a stream error , while { { invalid - references } } says it MUST . This PR seeks to clarify this .
Paragraph (version A):
Each header block contains a Required Insert Count, the lowest
possible value for the Insert Count with which the header block can
be decoded.  For a header block with no references to the dynamic
table, the Required Insert Count is zero.
Paragraph (version B):
Each header block contains a Required Insert Count, the lowest
possible value for the Insert Count with which the header block can
be decoded.  For a header block with references to the dynamic table,
the Required Insert Count is one larger than the largest Absolute
Index of all referenced dynamic table entries.  For a header block
with no references to the dynamic table, the Required Insert Count is
zero.
Paragraph (version B):
If the decoder encounters a header block with a Required Insert Count
value larger than defined above, it MAY treat this as a stream error
of type HTTP_QPACK_DECOMPRESSION_FAILED.  If the decoder encounters a
header block with a Required Insert Count value smaller than defined
above, it MUST treat this as a stream error of type
HTTP_QPACK_DECOMPRESSION_FAILED as prescribed in invalid-references.
Paragraph (version A):
If the decoder encounters a header block where the largest Absolute
Index used is not equal to the largest value permitted by the
Required Insert Count, it MAY treat this as a stream error of type
HTTP_QPACK_DECOMPRESSION_FAILED.
Draft: draft-ietf-quic-recovery

Commentary: Explicitly state that round trip time is abbreviated as RTT 
 In the recovery draft , RTT is briefly spelled out in section 5 but is used in several earlier sections . SRTT and PTO are not explained at all , it seems . TLP is spelled out . RTO has a section of its own but it referenced before that . The recovery doc can not be a tutorial on transmission theory , but it would be helpful to list the key acronyms and possibly reference an RFC with more details . There are already sections summarising key variables in pseudocode . There are references at the end , but the reader would have to go through them all . 
 Yes , thanks for the note . I 'm planning to do a cleanup of that doc soon . 
 I fixed defined RTT earlier in .
Paragraph (version A):
QUIC uses separate packet number spaces for each encryption level,
except 0-RTT and all generations of 1-RTT keys use the same packet
number space.  Separate packet number spaces ensures acknowledgement
of packets sent with one level of encryption will not cause spurious
retransmission of packets sent with a different encryption level.
Congestion control and RTT measurement are unified across packet
number spaces.
Paragraph (version B):
QUIC uses separate packet number spaces for each encryption level,
except 0-RTT and all generations of 1-RTT keys use the same packet
number space.  Separate packet number spaces ensures acknowledgement
of packets sent with one level of encryption will not cause spurious
retransmission of packets sent with a different encryption level.
Congestion control and round-trip time (RTT) measurement are unified
across packet number spaces.
Paragraph (version A):
RTT is calculated when an ACK frame arrives by computing the
difference between the current time and the time the largest acked
packet was sent.  An RTT sample MUST NOT be taken for a packet that
is not newly acknowledged or not ack-eliciting.
Paragraph (version B):
Round-trip time (RTT) is calculated when an ACK frame arrives by
computing the difference between the current time and the time the
largest acked packet was sent.  An RTT sample MUST NOT be taken for a
packet that is not newly acknowledged or not ack-eliciting.
Paragraph (version A):
QUIC senders use both ack information and timeouts to detect lost
packets, and this section provides a description of these algorithms.
Estimating the network round-trip time (RTT) is critical to these
algorithms and is described first.
Paragraph (version B):
QUIC senders use both ack information and timeouts to detect lost
packets, and this section provides a description of these algorithms.
Draft: draft-ietf-quic-transport

Commentary: This takes the suggestion from and expands on it .
Paragraph (version A):
A STOP_SENDING frame requests that the receiving endpoint send a
RESET_STREAM frame.  An endpoint that receives a STOP_SENDING frame
MUST send a RESET_STREAM frame for that stream.  An endpoint SHOULD
copy the error code from the STOP_SENDING frame, but MAY use any
application error code.  The endpoint that sends a STOP_SENDING frame
can ignore the error code carried in any RESET_STREAM frame it
receives.
Paragraph (version B):
A STOP_SENDING frame requests that the receiving endpoint send a
RESET_STREAM frame.  An endpoint that receives a STOP_SENDING frame
MUST send a RESET_STREAM frame if the stream is in the Ready or Send
state.  If the stream is in the Data Sent state and any outstanding
data is declared lost, an endpoint SHOULD send a RESET_STREAM frame
in lieu of a retransmission.
Paragraph (version B):
An endpoint SHOULD copy the error code from the STOP_SENDING frame to
the RESET_STREAM frame it sends, but MAY use any application error
code.  The endpoint that sends a STOP_SENDING frame MAY ignore the
error code carried in any RESET_STREAM frame it receives.
Draft: draft-ietf-quic-transport

Commentary: Editorial because it now says what we originally thought it said , but design because it is changing normative language . Does not interact with . 
 The following text is kind of hard to track : I 'm not really following what 's going on here . The server knows that it has two addresses and it wants to use its preferred address . Why does it have to probe from its preferred address . Also , I do n't understand how these two paragraphs work together . The first one says you have to send probing packets from your original address but the second paragraph tells you to probe from the preferrd address . 
 You 're right , that last restriction in the first paragraph looks backwards . IIRC , it 's supposed to be a reiteration of the fact that the client decides when to actually cut over , so the server should n't be sending non - probing packets from the preferred address until the client starts sending them there . This is section 9.6.2 of Transport . 
 I think that the first paragraph is just missing " ... until it receives a non - probing packet from the client at its preferred address . " Then maybe a simple : " The server MUST probe on the path toward its preferred address before sending non - probing packets . "
Paragraph (version A):
A server might receive a packet addressed to its preferred IP address
at any time after it accepts a connection.  If this packet contains a
PATH_CHALLENGE frame, the server sends a PATH_RESPONSE frame as per
migrate-validate.  The server MAY send other non-probing frames from
its preferred address, but MUST continue sending all probing packets
from its original IP address.
Paragraph (version A):
The server SHOULD also initiate path validation of the client using
its preferred address and the address from which it received the
client probe.  This helps to guard against spurious migration
initiated by an attacker.
Paragraph (version B):
A server might receive a packet addressed to its preferred IP address
at any time after it accepts a connection.  If this packet contains a
PATH_CHALLENGE frame, the server sends a PATH_RESPONSE frame as per
migrate-validate.  The server MUST send other non-probing frames from
its original address until it receives a non-probing packet from the
client at its preferred address and until the server has validated
the new path.
Paragraph (version B):
The server MUST probe on the path toward the client from its
preferred address.  This helps to guard against spurious migration
initiated by an attacker.
Draft: draft-ietf-quic-transport

Commentary: I find this pretty hard to read , but assuming I am reading it corectly , it basically says that if you read any packet or write any packet that has a frame other than ACK or padding , then you reset the timer . The text about " other packet has not been acknowledged or lost " does n't make sense unless you have some very complicated timer scheme , because the packet wo n't be acknowledge or lost until after it is sent , at which point I have already reset the timer . 
 Yeah , this is opaque . I think that the logic is something like : when receiving a packet , restart the idle timer when sending an ACK - eliciting packet . if you have n't sent other ACK - eliciting packets since the idle timer was started , restart the idle timer That is , if you send 10 packets , only the first of those restarts the timer . This clearly needs to be reworded . 
 I 'd suggest one change to the second bullet ,  . " when sending an ACK - eliciting packet . if you have n't sent other ACK - eliciting packets since the idle timer was restarted due to a received packet , restart the idle timer " And yes , that text is not clear . 
 I like the look of the wording change in . Is there something blocking it from being applied ? 
 Nothing . I just neglected to open the pull request . That happens sometimes . Lots of changes in flight ... 
 I think this looks good , but has more familiarity with this code than I do , so I 'm adding him as well .
Paragraph (version A):
Each endpoint advertises its own idle timeout to its peer.  The idle
timeout starts from the last packet received.  In order to ensure
that initiating new activity postpones an idle timeout, an endpoint
restarts this timer when sending a packet.  An endpoint does not
postpone the idle timeout if another packet has been sent containing
frames other than ACK or PADDING, and that other packet has not been
acknowledged or declared lost.  Packets that contain only ACK or
PADDING frames are not acknowledged until an endpoint has other
frames to send, so they could prevent the timeout from being
refreshed.
Paragraph (version B):
Each endpoint advertises its own idle timeout to its peer.  An
enpdpoint restarts any timer it maintains when a packet from its peer
is received and processed successfully.  The timer is also restarted
when sending a packet containing frames other than ACK or PADDING (an
ACK-eliciting packet, see QUIC-RECOVERY), but only if no other ACK-
eliciting packets have been sent since last receiving a packet.
Restarting when sending packets ensures that connections do not
prematurely time out when initiating new activity.
Draft: draft-ietf-quic-http

Commentary: ( Note that the issue identifies two issues , but one was already fixed in . ) 
 In , correctly observed that I messed up , but he closed his PR and I 'm not able to reopen it without more git wizardry than I 'm interested in practicing today . Easier just to fix it in my own branch . 
 Clients do n't send GOAWAY and when a client sends one , the server treats it as HTTPUNEXPECTEDFRAME . By contrast , servers do n't send  but the client treats receiving one as HTTPMALFORMEDFRAME . By contrast , if GOAWAY is sent on ! control it 's HTTPUNEXPECTEDFRAME , but if  is sent on ! control , it 's HTTPWRONGSTREAM . I think the answers here are HTTPUNEXPECTEDFRAME and HTTPWRONGSTREAM respectively , but we should be consistent . 
 I think you 're correct . There are some situations where newer errors would be more appropriate .
Paragraph (version A):
The GOAWAY frame is always sent on the control stream.  It carries a
QUIC Stream ID for a client-initiated bidirectional stream encoded as
a variable-length integer.  A client MUST treat receipt of a GOAWAY
frame containing a Stream ID of any other type as a connection error
of type HTTP_MALFORMED_FRAME.
Paragraph (version B):
The GOAWAY frame is always sent on the control stream.  It carries a
QUIC Stream ID for a client-initiated bidirectional stream encoded as
a variable-length integer.  A client MUST treat receipt of a GOAWAY
frame containing a Stream ID of any other type as a connection error
of type HTTP_WRONG_STREAM.
Draft: draft-ietf-quic-recovery

Commentary: Ignore the loss of Handshake , 0 - RTT , and 1 - RTT packets if the peer does n't have the keys to process them . Also unifies the text on discarding keys and no longer implies that 0 - RTT has it 's own packet number space . Replaces 
 merging this one as well to get this in -18 . 
 A few comments , editorial .
Paragraph (version A):
As described in Section 17.5.1 of QUIC-TRANSPORT, endpoints stop
sending and receiving Initial packets once they start exchanging
Handshake packets.  At this point, all loss recovery state for the
Initial packet number space is also discarded.  Packets that are in
flight for the packet number space are not declared as either
acknowledged or lost.  After discarding state, new Initial packets
will not be sent.
Paragraph (version B):
When packet protection keys are discarded (see Section 4.9 of QUIC-
TLS), all packets that were sent with those keys can no longer be
acknowledged because their acknowledgements cannot be processed
anymore.  The sender considers them no longer in flight.  That is,
the sender SHOULD discard all recovery state associated with those
packets and MUST remove them from the count of bytes in flight.
Paragraph (version B):
Endpoints stop sending and receiving Initial packets once they start
exchanging Handshake packets (see Section 17.2.2.1 of QUIC-
TRANSPORT).  At this point, recovery state for all in-flight Initial
packets is discarded.
Paragraph (version B):
When 0-RTT is rejected, recovery state for all in-flight 0-RTT
packets is discarded.
Paragraph (version B):
It is expected that keys are discarded after packets encrypted with
them would be acknowledged or declared lost.  Initial secrets however
might be destroyed sooner, as soon as handshake keys are available
(see Section 4.10 of QUIC-TLS).
Paragraph (version B):
During the handshake, some packet protection keys might not be
available when a packet arrives.  In particular, Handshake and 0-RTT
packets cannot be processed until the Initial packets arrive, and
1-RTT packets cannot be processed until the handshake completes.
Endpoints MAY ignore the loss of Handshake, 0-RTT, and 1-RTT packets
that might arrive before the peer has packet protection keys to
process those packets.
Paragraph (version A):
When keys for a packet number space are discarded, any in-flight
packets sent with those keys are removed from the count of bytes in
flight.  Loss recovery state is also discarded, so no loss events
will occur for any in-flight packets from that space (see discard-
initial).  Note that it is expected that keys are discarded after
those packets would be declared lost, but Initial secrets are
destroyed earlier.
Paragraph (version A):
When 0-RTT is rejected, all in-flight 0-RTT packets are removed from
the count of bytes in flight.  Loss recovery state is also discarded,
so no loss events will occur for any in-flight 0-RTT packets.