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

Commentary: This is a bit of a niche code , as it is only narrowly useful for signaling loss of paths . But people wanted it and it does n't code that much . Note the target of this pull request . For . 
 I 'm going to leave this for a bit , but if people like the idea , I plan to merge it into . 
 Thank you for the PR . This error code will be useful , as the only other way of closing the connection would be to use NO_ERROR . Then , it would be impossible to know why the connection was abruptly closed . Yes , there 's value in having a way to fail suggestion , but lgtm
Paragraph (version A):
When an endpoint abandons path validation, it determines that the
path is unusable.  This does not necessarily imply a failure of the
connection - endpoints can continue sending packets over other paths
as appropriate.  If no paths are available, an endpoint can wait for
a new path to become available or close the connection.
Paragraph (version B):
When an endpoint abandons path validation, it determines that the
path is unusable.  This does not necessarily imply a failure of the
connection - endpoints can continue sending packets over other paths
as appropriate.  If no paths are available, an endpoint can wait for
a new path to become available or close the connection.  An endpoint
that has no valid network path to its peer MAY signal this using the
NO_VIABLE_PATH connection error, noting that this is only possible if
the network path exists but does not support the required MTU
datagram-size.
Paragraph (version B):
An endpoint has determined that the network path is incapable of
supporting QUIC.  An endpoint is unlikely to receive
CONNECTION_CLOSE carrying this code except when the path does not
support a large enough MTU.
Draft: draft-ietf-quic-transport

Commentary: The issue suggests that any packet from the server validates the server 's address , because it echoes the client 's CID . I 'm not sure that 's correct , because the client might have chosen a zero - length SCID in its initial packet , and the server does n't echo the ODCID in Initial packets . This PR generalizes the existing rules for servers -- receiving a sufficiently - complex DCID or a valid Handshake packet is actual proof of address ownership . 
 The address validation section dives right into what a server needs to do to validate the client , but it does n't really address the client needs . This is pretty simple : any valid packet from the server validates the server address via the client - chosen destination connection ID . We just need to write that down here ( it might be elsewhere , I would need to check ) .
Paragraph (version A):
Connection establishment implicitly provides address validation for
both endpoints.  In particular, receipt of a packet protected with
Handshake keys confirms that the client received the Initial packet
from the server.  Once the server has successfully processed a
Handshake packet from the client, it can consider the client address
to have been validated.
Paragraph (version B):
Connection establishment implicitly provides address validation for
both endpoints.  In particular, receipt of a packet protected with
Handshake keys confirms that the peer successfully processed an
Initial packet.  Once an endpoint has successfully processed a
Handshake packet from the peer, it can consider the peer address to
have been validated.
Paragraph (version B):
For the client, the value of the Destination Connection ID field in
its first Initial packet allows it to validate the server address as
a part of successfully processing any packet.  Initial packets from
the server are protected with keys that are derived from this value
(see Section 5.2 of QUIC-TLS).  Alternatively, the value is echoed by
the server in Version Negotiation packets (version-negotiation) or
included in the Integrity Tag in Retry packets (Section 5.8 of QUIC-
TLS).
Draft: draft-ietf-quic-transport

Commentary: Added a wrapper section and  , then reorder .
Paragraph (version A):
As a result, the size of the packet number encoding is at least one
bit more than the base-2 logarithm of the number of contiguous
unacknowledged packet numbers, including the new packet.  Pseudo-code
and examples for packet number encoding can be found in sample-
packet-number-encoding.
Paragraph (version B):
As a result, the size of the packet number encoding is at least one
bit more than the base-2 logarithm of the number of contiguous
unacknowledged packet numbers, including the new packet.  Pseudocode
and examples for packet number encoding can be found in sample-
packet-number-encoding.
Paragraph (version A):
Once header protection is removed, the packet number is decoded by
finding the packet number value that is closest to the next expected
packet.  The next expected packet is the highest received packet
number plus one.  Pseudo-code and an example for packet number
decoding can be found in sample-packet-number-decoding.
Paragraph (version B):
Once header protection is removed, the packet number is decoded by
finding the packet number value that is closest to the next expected
packet.  The next expected packet is the highest received packet
number plus one.  Pseudocode and an example for packet number
decoding can be found in sample-packet-number-decoding.
Draft: draft-ietf-quic-transport

Commentary: Based on  's suggestion on .
Paragraph (version B):
This document uses the terms "QUIC packets", "UDP datagrams", and "IP
packets" to refer to the units of the respective protocols.  That is,
one or more QUIC packets can be encapsulated in a UDP datagram, which
is in turn encapsulated in an IP packet.
Draft: draft-ietf-quic-invariants

Commentary: This is right next to the BCP 14 text . ( Based on private conversation with   who expressed the concern that this seems to lack overt normative force . )
Paragraph (version B):
This document defines requirements on future QUIC versions, even
where normative language is not used.
Draft: draft-ietf-quic-transport

Commentary: It may be useful to review the commits separately ; the first commit reorders sections without modifying text , while the second commit contains a new paragraph to the beginning of the section . 
 An introduction to this long section would be useful I find it strange that having read 12 previous security analysis subsections I arrive at this section . I am surprised that the overview is not section 21.1 
 I 'm going to trust that you just reordered , because the diff tool is completely unable to process this changeset .
Paragraph (version B):
The goal of QUIC is to provide a secure transport connection.
security-properties provides an overview of those properties;
subsequent sections discuss constraints and caveats regarding these
properties, including descriptions of known attacks and
countermeasures.
Draft: draft-ietf-quic-transport

Commentary: while the client ' spins ' it after one RTT . On - path observers can measure the time between two spin bit toggle events to estimate the end - to - end RTT of a connection . It would be clearer to the reader if the explanation of operation proceeded the detail . 
 This is fine , but I find that description to be less than ideal . I wo n't try to suggest an improvement though . It is n't so bad .
Paragraph (version A):
The latency spin bit enables passive latency monitoring from
observation points on the network path throughout the duration of a
connection.  The spin bit is only present in the short packet header,
since it is possible to measure the initial RTT of a connection by
observing the handshake.  Therefore, the spin bit is available after
version negotiation and connection establishment are completed.  On-
path measurement and use of the latency spin bit is further discussed
in QUIC-MANAGEABILITY.
Paragraph (version B):
The latency spin bit enables passive latency monitoring from
observation points on the network path throughout the duration of a
connection.  The server reflects the spin value received, while the
client 'spins' it after one RTT.  On-path observers can measure the
time between two spin bit toggle events to estimate the end-to-end
RTT of a connection.
Paragraph (version B):
The spin bit is only present in the short packet header, since it is
possible to measure the initial RTT of a connection by observing the
handshake.  Therefore, the spin bit is available after version
negotiation and connection establishment are completed.  On-path
measurement and use of the latency spin bit is further discussed in
QUIC-MANAGEABILITY.
Paragraph (version A):
With this mechanism, the server reflects the spin value received,
while the client 'spins' it after one RTT.  On-path observers can
measure the time between two spin bit toggle events to estimate the
end-to-end RTT of a connection.
Draft: draft-ietf-quic-transport

Commentary: This was a little obtuse ; it would benefit from a clearer description of what the token is and how it is used . 
 Thanks  . I do n't think that I need to worry about " easy to regenerate " ( there is a lot of text on that later ) . The " exchanges " comment is unmodified text , but it is worth fixing . 
 Having read to the end of section 10 I made a note that I was still trying to figure out what a reset token actually looked like . 
 Addressed in . 
 10.3.1 . Detecting a Stateless Reset bytes of the UDP datagram . I find this rather opaque given that so far we do not know what a packet looks like , and I can not see what the encoding of this is . To add to the confusion over packets and frames we now have datagrams . 
 The encoding of a packet is specifically not relevant at this point . I think that the question is whether it is reasonable to expect that readers have internalized : There is a reasonable criticism here in that the level of detail in the stateless reset description is too much too early . It would be nicer if some of the more detailed stuff here were deferred until later . Unfortunately , it is hard to extricate this from the other more generic stuff in Section 10 . So I 'm not seeing any real way to improve this without making things worse in other ways . 
 A few suggestions , but I think this is adequate to resolve the issue .
Paragraph (version A):
To support this process, a token is sent by endpoints.  The token is
carried in the Stateless Reset Token field of a NEW_CONNECTION_ID
frame.  Servers can also specify a stateless_reset_token transport
parameter during the handshake that applies to the connection ID that
it selected during the handshake; clients cannot use this transport
parameter because their transport parameters do not have
confidentiality protection.  These tokens are protected by
encryption, so only client and server know their value.  Tokens are
invalidated when their associated connection ID is retired via a
RETIRE_CONNECTION_ID frame (frame-retire-connection-id).
Paragraph (version B):
To support this process, an endpoint issues a stateless reset token,
which is a 16-byte value that is hard to guess.  If the peer
subsequently receives a stateless reset, which is a UDP datagram that
ends in that stateless reset token, the peer will immediately end the
connection.
Paragraph (version B):
A stateless reset token is specific to a connection ID.  An endpoint
issues a stateless reset token by including the value in the
Stateless Reset Token field of a NEW_CONNECTION_ID frame.  Servers
can also issue a stateless_reset_token transport parameter during the
handshake that applies to the connection ID that it selected during
the handshake.  These exchanges are protected by encryption, so only
client and server know their value.  Note that clients cannot use the
stateless_reset_token transport parameter because their transport
parameters do not have confidentiality protection.
Paragraph (version B):
Tokens are invalidated when their associated connection ID is retired
via a RETIRE_CONNECTION_ID frame (frame-retire-connection-id).
Draft: draft-ietf-quic-transport

Commentary: if we decide we need / want it . 
 And yes , this handwaves over coercing the mask into the right size integer for the number of bytes you read . 
 When you do that , it 's probably worth copying the " Code Components " language from -recovery . 
 hexadecimal ) decodes to the decimal value ; the four byte sequence 9d 7f 3e 7d decodes to ; the two byte sequence 7b bd decodes to ; and the single byte 25 decodes to 37 ( as does the two byte sequence 40 25 ) . The Some hex & decimal indication would help . A picture is worth a thousand words and save the reader drawing this out themselves to understand it and getting confused . The conversion pseudo code would be helpful , possibly in an appendix . 
 I do n't think that any change is needed here . It says " in hexadecimal " and " decimal value " right there . 
 We could put comma separators in the decimal values ( i.e. = 494,878,333 ) so they 're more readily parsed as decimals rather than digit sequences . And an appendix with a varint decoder might not be the worst idea .
Paragraph (version A):
For example, the eight byte sequence c2 19 7c 5e ff 14 e8 8c (in
hexadecimal) decodes to the decimal value 151288809941952652; the
four byte sequence 9d 7f 3e 7d decodes to 494878333; the two byte
sequence 7b bd decodes to 15293; and the single byte 25 decodes to 37
(as does the two byte sequence 40 25).
Paragraph (version B):
Examples and a sample decoding algorithm are shown in sample-varint.
Draft: draft-ietf-quic-transport

Commentary: I struggled with this a little . Happy to take suggestions . 
 I 'm going to say that the IP Packet vs. QUIC Packet text is not necessary . We carefully qualify where there is any potential for confusion . 
 On the other issue , it might be worth simply stating the terminology upfront . Something like 
 Datagram Size There is some confusion in the text between packets , frames and datagrams . That could be helped by earlier clarification . 
 This is a duplicate of . 
 12.4 . Frames and Frame Types Packet Payload { Frame ( 8 .. ) ... , } Version Negotiation , Stateless Reset , and Retry packets do not contain frames . At this point ( page 82 ) I am still not sure what a packet or a frame is and have no idea what is going on on the wire . 
 Probably a duplicate of . These terms should be to the definitions , with possibly some additional explanatory text in Section 12 . 
 Section 1 is the first place that you introduce the term " Frame " . I got very confused about frames and packets , and I thing the taxonomy needs to be clearly explained . You have UDP / IP packets that carry one or more QUIC PDUs , but the frame / packet notation made it unclear what was being discussed and whether the terms were being used consistently . Some clarification would be useful , or if it is in the text then making it more obvious would help . 
 Perhaps " frame " and " datagram " should be as defined terms in Section 1.2 . On a related note , the defined term is " QUIC packet " but in the text we do n't always specify what type of " packet . " Perhaps we should define " packet " as generally referring to QUIC , with a note that IP packets will be indicated as such . ( I believe all instances of " packet " that refer to IP explicitly say " IP packet , " but we should verify that . ) 
 One small suggestion , which you can ignore if you do n't like it .
Paragraph (version A):
A complete processable unit of QUIC that can be encapsulated in a
UDP datagram.  Multiple QUIC packets can be encapsulated in a
single UDP datagram.
Paragraph (version B):
A complete processable unit of QUIC that can be encapsulated in a
UDP datagram.  One or more QUIC packets can be encapsulated in a
single UDP datagram.
Paragraph (version B):
A unit of structured protocol information.  There are multiple
frame types, each of which carries different information.  Frames
are contained in QUIC packets.
Draft: draft-ietf-quic-transport

Commentary: We explicitly do n't recommend anything for defeating traffic analysis . We only offer PADDING frames as they are known to be useful in existing strategies . 
 The choice of padding values is itself an interesting problem , but as far as I can see the text is silent on the subject . 
 I do n't understand this comment . The text is silent because there is no choice of padding values -- PADDING frames have a defined frame type and no content . 
 I believe that this is raising the known - difficult problem of knowing when and how much to pad . That is something that other documents have addressed by saying " we provide the tools , but do n't show you how to use them " . That is absent here , so this is a fair criticism . 
 I do n't read the comment as being about the amount of padding , and so I have the same question as but the clarification in is a welcome addition . I think the PR addresses the addressable part of this issue .
Paragraph (version B):
The length of QUIC packets can reveal information about the length of
the content of those packets.  The PADDING frame is provided so that
endpoints have some ability to obscure the length of packet content;
see frame-padding.
Paragraph (version B):
Note however that defeating traffic analysis is challenging and the
subject of active research.  Length is not the only way that
information might leak.  Endpoints might also reveal sensitive
information through other side channels, such as the timing of
packets.
Draft: draft-ietf-quic-transport

Commentary: Does this win the record for least amount of bytes touched in a PR ? 
  , I ca n't find it easily , but I believe that I pushed a 1 bit change at one point in this process . 
   field . Presumably the length in bytes .
Paragraph (version A):
The Transport Parameter Length field contains the length of the
Transport Parameter Value field.
Paragraph (version B):
The Transport Parameter Length field contains the length of the
Transport Parameter Value field in bytes.
Draft: draft-ietf-quic-transport

Commentary: Less detail above , but a pointer to what follows . 
 Table 3 : Frame Types The notation used in the table took a while to figure out . A little more explanation , and possibly before the table itself might make it clearer . 
 One suggestion , but LGTM
Paragraph (version A):
The frame types defined in this specification are listed in frame-
types.  The Frame Type in ACK, STREAM, MAX_STREAMS, STREAMS_BLOCKED,
and CONNECTION_CLOSE frames is used to carry other frame-specific
flags.  For all other frames, the Frame Type field simply identifies
the frame.  These frames are explained in more detail in frame-
formats.
Paragraph (version B):
frame-types lists and summarizes information about each frame type
that is defined in this specification.  A description of this summary
is included after the table.
Paragraph (version B):
The format and semantics of each frame type are explained in more
detail in frame-formats.  The remainder of this section provides a
summary of important and general information.
Paragraph (version B):
The Frame Type in ACK, STREAM, MAX_STREAMS, STREAMS_BLOCKED, and
CONNECTION_CLOSE frames is used to carry other frame-specific flags.
For all other frames, the Frame Type field simply identifies the
frame.
Paragraph (version A):
All QUIC frames are idempotent in this version of QUIC.  That is, a
valid frame does not cause undesirable side effects or errors when
received more than once.
Paragraph (version B):
All frames are idempotent in this version of QUIC.  That is, a valid
frame does not cause undesirable side effects or errors when received
more than once.
Draft: draft-ietf-quic-transport

Commentary: On endpoints . 
 This is the IPv6 minimum size ( [ IPv6 ] ) and is also supported by most modern IPv4 networks . Assuming the minimum IP header size of 40 bytes for IPv6 and 20 bytes for IPv4 and a UDP header size of 8 bytes , this results in a maximum datagram size of 1232 bytes for IPv6 and 1252 bytes for IPv4 . The previous two paras are quite confusing . I think the first para refers to the  packet size in the network layer , but the second para is not clear , nor is the next para . 
 The paragraph preceding the first is this : So it is clear what the second paragraph means . QUIC does n't operate if the network is incapable of carrying a datagram payload of 1200 bytes . I think that rewording that way might help . What is less clear is where the extra 32 ( or 52 ) bytes go . In that we 've been very generous in providing for header extensions or UDP extensions . But I do n't see a need to explain that aspect . 
 I found this to still be very confusing , FWIW . It 's unclear why the limit would be 1200 bytes when the text very clearly explains that at least 1232 can be relied upon , or alternatively why the text claims " QUIC assumes a minimum IP packet size of at least 1280 bytes . " when in fact it appears to only mandate a 32 bytes smaller figure . It reads like someone forgot to update a constant . above suggests that this was intentional , to leave space for unspecified future use by lower layers . I think some allusion to this is justified , just to clarify the otherwise seeming inconsistency . 
 A sentence to tie it together but LGTM
Paragraph (version A):
The maximum datagram size is defined as the largest size of UDP
payload that can be sent across a network path using a single UDP
datagram.
Paragraph (version A):
QUIC depends upon a minimum IP packet size of at least 1280 bytes.
This is the IPv6 minimum size (IPv6) and is also supported by most
modern IPv4 networks.  Assuming the minimum IP header size of 40
bytes for IPv6 and 20 bytes for IPv4 and a UDP header size of 8
bytes, this results in a maximum datagram size of 1232 bytes for IPv6
and 1252 bytes for IPv4.
Paragraph (version A):
The maximum datagram size MUST be at least 1200 bytes.
Paragraph (version B):
The maximum datagram size is defined as the largest size of UDP
payload that can be sent across a network path using a single UDP
datagram.  QUIC MUST NOT be used if the network path cannot support a
maximum datagram size of at least 1200 bytes.
Paragraph (version B):
QUIC assumes a minimum IP packet size of at least 1280 bytes.  This
is the IPv6 minimum size (IPv6) and is also supported by most modern
IPv4 networks.  Assuming the minimum IP header size of 40 bytes for
IPv6 and 20 bytes for IPv4 and a UDP header size of 8 bytes, this
results in a maximum datagram size of 1232 bytes for IPv6 and 1252
bytes for IPv4.  Thus, modern IPv4 and all IPv6 network paths will be
able to support QUIC.
Draft: draft-ietf-quic-transport

Commentary: are encoded as variable - length integers ; see Section 16 . A QUIC endpoint MUST NOT reuse a stream ID within a connection . This was a common problem throughout the text . I found the use of ( 0x1 ) and similar confusing in the text . Where you use this notation you mean the bit manipulated by the mask  ( and similar ) . It would be helpful to the reader to be a little more pedantic in the use of the term in each case . We will get to it later , in the comments but a lot of readers would be helped by the use of the classic ASCII art style representation of bit fields . 
 slightly more text
Paragraph (version B):
When a single-bit field is referenced in prose, the position of that
field can be clarified by using the value of the byte that carries
the field with the field's value set.  For example, the value 0x80
could be used to refer to the single-bit field in the most
significant bit of the byte, such as One-bit Field in fig-ex-format.