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

Commentary: If we get one , rely on the back - off that we require endpoints to implement when they enter the closing state . No need for any additional special processing rules ( as mentioned in ) . 
 Section 11.1 says : " An endpoint that receives an invalid CONNECTIONCLOSE frame MUST NOT signal the existence of the error to its peer . " Editorially , it is not clear to me whether I am to suppress the error code in the CONNECTIONCLOSE frame or the error I generate when I receive an invalid frame . Moreover , I am not sure what constitutes an invalid CONNECTION_CLOSE frame . The words do n't occur elsewhere . Section 19.19 does n't define any fatal errors for this type . I can imagine a Reason Length that overruns the packet , or perhaps an undefined error code ? A bogus frame type ? We should probably define those in 19.19 . Perhaps this sentence is an artifact from before we were throwing away Initial keys agressively ? 
 If you suppress the error , does it matter which error you do not send ? 
 I 'm not sure what the intent of the sentence is . Do I send PROTOCOL_VIOLATION but not the error code in the frame ? Do I send nothing ? 
 As I read it , you should not send anything if you see CONNECTION_CLOSE . As to the motivation , I 'm not quite sure , but if the peer closes but does it badly , chances are that anything you send just results in stateless resets . Maybe there can also be some malicious intend , especially in early handshake , but I do n't think that is the reason . 
 I think this is addressing the injected packet case -- if you ignore an injected CONNECTION_CLOSE , you should n't send the real peer anything about it , or you 've just allowed an attacker to inject authenticated traffic in the connection . 
 This is more about the looping case : sending CONNECTIONCLOSE in response to CONNECTIONCLOSE . But it is badly worded . 
 From the current text in 10.3 After sending a CONNECTIONCLOSE frame , endpoints immediately enter the closing state . During the closing period , an endpoint that sends a CONNECTIONCLOSE frame SHOULD respond to any packet that it receives with another packet containing a CONNECTION_CLOSE frame . To minimize the state that an endpoint maintains for a closing connection , endpoints MAY send the exact same packet . This will be a loop since the same invalid packet will be sent again by the sender .... 
 I 'm going to request that this be re - assessed . When looking into  's comment , I realize that we are n't really clear enough about this invalid case and some ( small amount of ) discussion might be necessary to confirm that this change is OK .
Paragraph (version A):
An endpoint that receives an invalid CONNECTION_CLOSE frame MUST NOT
signal the existence of the error to its peer.
Draft: draft-ietf-quic-transport

Commentary: This is really just an observation , because there is no real way we can insist on people doing this sort of thing , but being aware of the performance implication of spoofed migrations might motivate solutions . 
 I think the sections that describe connection migration attacks should mention that , when the endpoint detects a spurious migration , it should revert back to using the same CC state and ECN state as before . Otherwise , an attacker could degrade the performance of a connection . 
 Perhaps the tag should be recovery , not transport . 
 I can see it going either way . what do you think ? 
 I think the text is going to be in transport , so that 's probably the right tag 
 As long as this does n't lead to confusion ( for example : we recently tightened up the MUST around resetting state ) for folks when reading this , I think it 's really valuable to actually state this in the draft rather than hint at it throughout -- looks good !
Paragraph (version A):
An endpoint MAY send data to an unvalidated peer address, but it MUST
protect against potential attacks as described in address-spoofing
and on-path-spoofing.  An endpoint MAY skip validation of a peer
address if that address has been seen recently.
Paragraph (version B):
An endpoint MAY send data to an unvalidated peer address, but it MUST
protect against potential attacks as described in address-spoofing
and on-path-spoofing.  An endpoint MAY skip validation of a peer
address if that address has been seen recently.  In particular, if an
endpoint returns to a previously-validated path after detecting some
form of spurious migration, skipping address validation and restoring
loss detection and congestion state can reduce the performance impact
of the attack.
Draft: draft-ietf-quic-tls

Commentary: The old text used the non - specific " abort " here , but we can point to the right error code . 
 What does " abort " mean ? Perhaps change this to " drop QUIC connection state " ? Originally posted by in 
 LGTM modulo the preference below .
Paragraph (version A):
QUIC requires that the cryptographic handshake provide authenticated
protocol negotiation.  TLS uses Application Layer Protocol
Negotiation (ALPN) RFC7301 to select an application protocol.  Unless
another mechanism is used for agreeing on an application protocol,
endpoints MUST use ALPN for this purpose.  When using ALPN, endpoints
MUST immediately close a connection (see Section 10.3 in QUIC-
TRANSPORT) if an application protocol is not negotiated with a
no_application_protocol TLS alert (QUIC error code 0x178, see tls-
errors).  While RFC7301 only specifies that servers use this alert,
QUIC clients MUST also use it to terminate a connection when ALPN
negotiation fails.
Paragraph (version A):
An application-layer protocol MAY restrict the QUIC versions that it
can operate over.  Servers MUST select an application protocol
compatible with the QUIC version that the client has selected.  If
the server cannot select a compatible combination of application
protocol and QUIC version, it MUST abort the connection.  A client
MUST abort a connection if the server picks an application protocol
incompatible with the protocol version being used.
Paragraph (version B):
QUIC requires that the cryptographic handshake provide authenticated
protocol negotiation.  TLS uses Application Layer Protocol
Negotiation (ALPN) ALPN to select an application protocol.  Unless
another mechanism is used for agreeing on an application protocol,
endpoints MUST use ALPN for this purpose.  When using ALPN, endpoints
MUST immediately close a connection (see Section 10.3 in QUIC-
TRANSPORT) if an application protocol is not negotiated with a
no_application_protocol TLS alert (QUIC error code 0x178, see tls-
errors).  While ALPN only specifies that servers use this alert, QUIC
clients MUST also use it to terminate a connection when ALPN
negotiation fails.
Paragraph (version B):
An application protocol MAY restrict the QUIC versions that it can
operate over.  Servers MUST select an application protocol compatible
with the QUIC version that the client has selected.  The server MUST
treat the inability to select a compatible application protocol as a
connection error of type 0x178 (no_application_protocol).  Similarly,
a client MUST treat the selection of an incompatible application
protocol by a server as a connection error of type 0x178.
Draft: draft-ietf-quic-transport

Commentary: It 's still slightly odd where we have this setup between TLS and transport , but it seems like replicating the information might be enough . 
 Would it make sense to add PN space columns to the table of frames with section references , with an X where a frame is applicable ? Transport section 12.4 
 Looks good to me , and thank you for adding this column . Seeing frames like PATH_CHALLENGE / RESPONSE in 0RTT packets is strange , but clearly allowed by the spec . I do n't see a reason to changing this , but it 's why I think this column is useful .
Paragraph (version B):
A CONNECTION_CLOSE frame of type 0x1c can appear in Initial,
Handshake, and 1-RTT packets, whereas a CONNECTION_CLOSE of type
0x1d can only appear in a 1-RTT packet.
Paragraph (version B):
Section 4 of QUIC-TLS provides more detail about these restrictions.
Note that all frames can appear in 1-RTT packets.
Draft: draft-ietf-quic-transport

Commentary: now we know how many holes it takes to fill the Albert Hall . This section has existed for a long time as " TBD " . No longer . It also takes the opportunity to explain a little bit about what 0 - RTT is for . 
 Retry is there , but at one level higher up ( confirms that endpoints are willing to communicate ( { { validate - handshake } } ) ) . 
 So we have little diagrams for send and receive stream states . Any chance this section could include a state diagram and transitions for the overall connection state ? 
 There 's a lot of text in the transport draft that assumes you know what 0 - RTT / early data are . The term " early data " occurs only once , and does n't even appear until describing the 0 - RTT packet type . The introductory sections should probably contain some high - level description of Early Data , then point off to TLS for more detailed considerations . Purely editorial -- nothing new needs to be specified , but an uninitiated reader will need some context . This could possibly be part of . 
 I did n't see any other TBDs in the draft -transport doc or an existing issue , so opening this for tracking purposes . 
 Whoops ! 
 I noticed you did n't write anything about Retry . Was that intentional ?
Paragraph (version A):
TBD.
Paragraph (version B):
A QUIC connection is a stateful interaction between a client and
server, the primary purpose of which is to support the exchange of
data by an application protocol.  Streams (streams) are the primary
means by which an application protocol exchanges information.
Paragraph (version B):
Each connection starts with a handshake phase, during which client
and server establish a shared secret using the cryptographic
handshake protocol QUIC-TLS and negotiate the application protocol.
The handshake (handshake) confirms that both endpoints are willing to
communicate (validate-handshake) and establishes parameters for the
connection (transport-parameters).
Paragraph (version B):
An application protocol can also operate in a limited fashion during
the handshake phase.  0-RTT allows application messages to be sent by
a client before receiving any messages from the server.  However,
0-RTT lacks certain key security guarantees.  In particular, there is
no protection against replay attacks in 0-RTT; see QUIC-TLS.
Separately, a server can also send application data to a client
before it receives the final cryptographic handshake messages that
allow it to confirm the identity and liveness of the client.  These
capabilities allow an application protocol to offer the option to
trade some security guarantees for reduced latency.
Paragraph (version B):
The use of connection IDs (connection-id) allows connections to
migrate to a new network path, both as a direct choice of an endpoint
and when forced by a change in a middlebox.  migration describes
mitigations for the security and privacy issues associated with
migration.
Paragraph (version B):
For connections that are no longer needed or desired, there are
several ways for a client and server to terminate a connection
(termination).
Draft: draft-ietf-quic-http

Commentary: Lest some readers get the impression that each request consumes a single QUIC stream and each response consumes a single QUIC stream .
Paragraph (version A):
Multiplexing of requests is performed using the QUIC stream
abstraction, described in Section 2 of QUIC-TRANSPORT.  Each request
and response consumes a single QUIC stream.  Streams are independent
of each other, so one stream that is blocked or suffers packet loss
does not prevent progress on other streams.
Paragraph (version B):
Multiplexing of requests is performed using the QUIC stream
abstraction, described in Section 2 of QUIC-TRANSPORT.  Each request-
response pair consumes a single QUIC stream.  Streams are independent
of each other, so one stream that is blocked or suffers packet loss
does not prevent progress on other streams.
Draft: draft-ietf-quic-recovery

Commentary: I was trying to come up with text for this but this PR looks great . 
 I believe there 's an extra " is " . 
 Can you write a PR ? Removing either ' is ' does n't read well to me , but I suspect a sentence rewrite could be an improvement . ie : " A loss epoch ends when a packet sent after loss is first declared is acknowledged . " ? 
 I agree a rewrite would be better .
Paragraph (version A):
QUIC ends a loss epoch when a packet sent after loss is declared is
acknowledged.  TCP waits for the gap in the sequence number space to
be filled, and so if a segment is lost multiple times in a row, the
loss epoch may not end for several round trips.  Because both should
reduce their congestion windows only once per epoch, QUIC will do it
correctly once for every round trip that experiences loss, while TCP
may only do it once across multiple round trips.
Paragraph (version B):
QUIC starts a loss epoch when a packet is lost and ends one when any
packet sent after the epoch starts is acknowledged.  TCP waits for
the gap in the sequence number space to be filled, and so if a
segment is lost multiple times in a row, the loss epoch may not end
for several round trips.  Because both should reduce their congestion
windows only once per epoch, QUIC will do it correctly once for every
round trip that experiences loss, while TCP may only do it once
across multiple round trips.
Draft: draft-ietf-quic-transport

Commentary: updated quic - tls but not quic - transport 
 Thanks for catching this
Paragraph (version A):
The payload of an Initial packet includes a CRYPTO frame (or frames)
containing a cryptographic handshake message, ACK frames, or both.
PADDING and CONNECTION_CLOSE frames are also permitted.  An endpoint
that receives an Initial packet containing other frames can either
discard the packet as spurious or treat it as a connection error.
Paragraph (version B):
The payload of an Initial packet includes a CRYPTO frame (or frames)
containing a cryptographic handshake message, ACK frames, or both.
PING, PADDING, and CONNECTION_CLOSE frames are also permitted.  An
endpoint that receives an Initial packet containing other frames can
either discard the packet as spurious or treat it as a connection
error.
Paragraph (version A):
The payload of this packet contains CRYPTO frames and could contain
PADDING, or ACK frames.  Handshake packets MAY contain
CONNECTION_CLOSE frames.  Endpoints MUST treat receipt of Handshake
packets with other frames as a connection error.
Paragraph (version B):
The payload of this packet contains CRYPTO frames and could contain
PING, PADDING, or ACK frames.  Handshake packets MAY contain
CONNECTION_CLOSE frames.  Endpoints MUST treat receipt of Handshake
packets with other frames as a connection error.
Draft: draft-ietf-quic-qpack

Commentary: Did a sweep before ; either I missed a few , or these have crept in since .
Paragraph (version A):
The Header Acknowledgement instruction might increase the Known
Received Count, see known-received-count.
Paragraph (version B):
The Header Acknowledgement instruction might increase the Known
Received Count; see known-received-count.
Paragraph (version A):
An endpoint uses a new connection ID for probes sent from a new local
address, see migration-linkability for further discussion.  An
endpoint that uses a new local address needs to ensure that at least
one new connection ID is available at the peer.  That can be achieved
by including a NEW_CONNECTION_ID frame in the probe.
Paragraph (version B):
An endpoint uses a new connection ID for probes sent from a new local
address; see migration-linkability for further discussion.  An
endpoint that uses a new local address needs to ensure that at least
one new connection ID is available at the peer.  That can be achieved
by including a NEW_CONNECTION_ID frame in the probe.
Draft: draft-ietf-quic-transport

Commentary: This seems unnecessarily wishy - washy . Either they 're reserved by definition , and therefore will never represent a real protocol , or they 're available for use . We should remove the " probably " unless there 's a good reason to keep it that I 'm missing . 
 Use of that word was entirely intentional . If there is certainty about this status , then it creates a temptation to apply certain optimizations that could be disruptive . What if middleboxes cached Version Negotiation packets from servers and helpfully provided responses to greased connection attempts ? 
 We fear that someone might ossify if they discover that these are definitely not real protocol versions . On the other hand , the thing that breaks is use of these as real protocol versions , which I do n't believe we 're trying to achieve . If the middlebox is generating accurate VN packets , that seems entirely reasonable ( and indistinguishable from actual VN packets ) . If they 're generating inaccurate VN packets , then our anti - downgrade protections that we 've decided to implement RSN will break . On the other hand , if these ever are real protocol versions , then a junk grease packet using the reserved version will fail to parse as a valid Initial and will just fail rather than eliciting a VN response . This seems like an impossible battle to win , and a lot of subtlety to expect of middlebox vendors . Write what we mean and move on .
Paragraph (version A):
Reserved version numbers will probably never represent a real
protocol; a client MAY use one of these version numbers with the
expectation that the server will initiate version negotiation; a
server MAY advertise support for one of these versions and can expect
that clients ignore the value.
Paragraph (version B):
Reserved version numbers will never represent a real protocol; a
client MAY use one of these version numbers with the expectation that
the server will initiate version negotiation; a server MAY advertise
support for one of these versions and can expect that clients ignore
the value.
Draft: draft-ietf-quic-http

Commentary: Probably a bit overkill , but since it was n't explicitly stated + I thought we had replaced " octets " with bytes everywhere else .
Paragraph (version A):
The smallest unit of communication on a stream in HTTP/3,
consisting of a header and a variable-length sequence of octets
structured according to the frame type.  Protocol elements called
"frames" exist in both this document and QUIC-TRANSPORT.  Where
frames from QUIC-TRANSPORT are referenced, the frame name will be
prefaced with "QUIC."  For example, "QUIC CONNECTION_CLOSE
frames."  References without this preface refer to frames defined
in frames.
Paragraph (version B):
The smallest unit of communication on a stream in HTTP/3,
consisting of a header and a variable-length sequence of bytes
structured according to the frame type.  Protocol elements called
"frames" exist in both this document and QUIC-TRANSPORT.  Where
frames from QUIC-TRANSPORT are referenced, the frame name will be
prefaced with "QUIC."  For example, "QUIC CONNECTION_CLOSE
frames."  References without this preface refer to frames defined
in frames.
Paragraph (version A):
A variable-length integer that describes the length of the Frame
Payload.
Paragraph (version B):
A variable-length integer that describes the length in bytes of
the Frame Payload.
Draft: draft-ietf-quic-qpack

Commentary: This change has been suggested by afrind at on the basis that the Base is a count , and comparing an index to a count feels awkward .
Paragraph (version A):
An indexed header field representation identifies an entry in the
static table, or an entry in the dynamic table with an absolute index
less than the Base.
Paragraph (version B):
An indexed header field representation identifies an entry in the
static table, or an entry in the dynamic table with an absolute index
less than the value of the Base.
Paragraph (version A):
An indexed header field with post-base index representation
identifies an entry in the dynamic table with an absolute index
greater than or equal to the Base.
Paragraph (version B):
An indexed header field with post-base index representation
identifies an entry in the dynamic table with an absolute index
greater than or equal to the value of the Base.
Paragraph (version A):
A literal header field with name reference representation encodes a
header field where the header field name matches the header field
name of an entry in the static table, or the header field name of an
entry in the dynamic table with an absolute index less than the Base.
Paragraph (version B):
A literal header field with name reference representation encodes a
header field where the header field name matches the header field
name of an entry in the static table, or the header field name of an
entry in the dynamic table with an absolute index less than the value
of the Base.
Paragraph (version A):
A literal header field with post-base name reference representation
encodes a header field where the header field name matches the header
field name of a dynamic table entry with an absolute index greater
than or equal to the Base.
Paragraph (version B):
A literal header field with post-base name reference representation
encodes a header field where the header field name matches the header
field name of a dynamic table entry with an absolute index greater
than or equal to the value of the Base.
Draft: draft-ietf-quic-recovery

Commentary: I did n't notice this change in PR , but I think the older text is more correct . I a bit more detail about why it can not be treated as an acknowledgement . 
 I updated the text to reflect both the lack of processing and packet number .
Paragraph (version A):
A Retry packet causes a client to send another Initial packet,
effectively restarting the connection process.  A Retry packet
indicates that the Initial was received, but not processed.  A Retry
packet MUST NOT be treated as an acknowledgment.
Paragraph (version B):
A Retry packet causes a client to send another Initial packet,
effectively restarting the connection process.  A Retry packet
indicates that the Initial was received, but not processed.  A Retry
packet cannot be treated as an acknowledgment, because it does not
indicate that a packet was processed or specify the packet number.
Draft: draft-ietf-quic-recovery

Commentary: Clarifies that this is the maximum datagram size currently in use on the connection . 
 kMaxDatagramSize is currently set to the minimum packet size of 1200 bytes . It should be set instead to the  packet size used by the connection , which is discussed in Section 14.1 of the transport draft . ( Issue raised by   on the mailing list . ) 
 My reading is that this value is the actual max packet size used in the connection , it 's just not clear from the explanation . kInitialWindow and kMinimumWindow are also per - connection fields defined directly below . There is one potential detail , which is if the MTU increases after the handshake , do the min CWND and  behavior change accordingly ? I think it 's simpler to reason about them not changing , but I can see both arguments and in the end I do n't think it 'll matter that much . 
 WinQuic uses the currently calculated path MTU instead a constant kMaxDatagramSize .
Paragraph (version A):
Sending multiple packets into the network without any delay between
them creates a packet burst that might cause short-term congestion
and losses.  Implementations MUST either use pacing or limit such
bursts to the initial congestion window, which is recommended to be
the minimum of 10 * kMaxDatagramSize and max(2* kMaxDatagramSize,
14720)).
Paragraph (version B):
Sending multiple packets into the network without any delay between
them creates a packet burst that might cause short-term congestion
and losses.  Implementations MUST either use pacing or limit such
bursts to the initial congestion window, which is recommended to be
the minimum of 10 * max_datagram_size and max(2* max_datagram_size,
14720)), where max_datagram_size is the current maximum size of a
datagram for the connection, not including UDP or IP overhead.