jiebi/TextFlow huggingface dataset:
Original text:
definitions) is closed.  A connection enters the draining state when the idle timeout expires. <del> 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. </del>  The value for an idle timeout can be asymmetric.  The value advertised by an endpoint is only used to determine whether the

Reviewer comments:
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" doesn't make sense unless you have some very complicated timer scheme, because the packet won'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 haven'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, Martin. "when sending an ACK-eliciting packet. if you haven'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 ac59e11. 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 NAME has more familiarity with this code than I do, so I'm adding him as well.

Revised text:
definitions) is closed.  A connection enters the draining state when the idle timeout expires.  <ins> 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. </ins> The value for an idle timeout can be asymmetric.  The value advertised by an endpoint is only used to determine whether the
Original text:
result is smaller than the min_rtt, the RTT should be used, but the ack delay field should be ignored. <del> A sender calculates both smoothed RTT and RTT variance similar to those specified in RFC6298, see on-ack-received. </del>  A sender takes an RTT sample when an ACK frame is received that acknowledges a larger packet number than before (see on-ack-

Reviewer comments:
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 cannot 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 .

Revised text:
result is smaller than the min_rtt, the RTT should be used, but the ack delay field should be ignored.  <ins> A sender calculates both smoothed RTT (SRTT) and RTT variance (RTTVAR) similar to those specified in RFC6298, see on-ack-received. </ins> A sender takes an RTT sample when an ACK frame is received that acknowledges a larger packet number than before (see on-ack-
Original text:
Data is protected using a number of encryption levels: <del> Plaintext </del>  Early Data (0-RTT) Keys

Reviewer comments:
I suspect these are uncontroversial.
All three Mart[ie]ns now agree, no further objections allowed.
LGTM, with the one change altered.

Revised text:
Data is protected using a number of encryption levels:  <ins> Initial Keys </ins> Early Data (0-RTT) Keys
Original text:
using the KDF provided by TLS.  In TLS 1.3, the HKDF-Expand-Label function described in Section 7.1 of TLS13 is used, using the hash function from the negotiated cipher suite.  Other versions of TLS <del> MUST provide a similar function in order to be used QUIC. </del>  The current encryption level secret and the label "quic key" are input to the KDF to produce the AEAD key; the label "quic iv" is used

Reviewer comments:
I suspect these are uncontroversial.
All three Mart[ie]ns now agree, no further objections allowed.
LGTM, with the one change altered.

Revised text:
using the KDF provided by TLS.  In TLS 1.3, the HKDF-Expand-Label function described in Section 7.1 of TLS13 is used, using the hash function from the negotiated cipher suite.  Other versions of TLS  <ins> MUST provide a similar function in order to be used with QUIC. </ins> The current encryption level secret and the label "quic key" are input to the KDF to produce the AEAD key; the label "quic iv" is used
Original text:
in hexadecimal notation.  Future versions of QUIC SHOULD generate a new salt value, thus ensuring that the keys are different for each version of QUIC.  This prevents a middlebox that only recognizes one <del> version of QUIC from seeing or modifying the contents of handshake packets from future versions. </del>  The HKDF-Expand-Label function defined in TLS 1.3 MUST be used for Initial packets even where the TLS versions offered do not include

Reviewer comments:
I suspect these are uncontroversial.
All three Mart[ie]ns now agree, no further objections allowed.
LGTM, with the one change altered.

Revised text:
in hexadecimal notation.  Future versions of QUIC SHOULD generate a new salt value, thus ensuring that the keys are different for each version of QUIC.  This prevents a middlebox that only recognizes one  <ins> version of QUIC from seeing or modifying the contents of packets from future versions. </ins> The HKDF-Expand-Label function defined in TLS 1.3 MUST be used for Initial packets even where the TLS versions offered do not include
Original text:
The "extension_data" field of the quic_transport_parameters extension contains a value that is defined by the version of QUIC that is in use.  The quic_transport_parameters extension carries a <del> TransportParameters when the version of QUIC defined in QUIC- </del>  TRANSPORT is used. The quic_transport_parameters extension is carried in the ClientHello

Reviewer comments:
I suspect these are uncontroversial.
All three Mart[ie]ns now agree, no further objections allowed.
LGTM, with the one change altered.

Revised text:
The "extension_data" field of the quic_transport_parameters extension contains a value that is defined by the version of QUIC that is in use.  The quic_transport_parameters extension carries a  <ins> TransportParameters struct when the version of QUIC defined in QUIC- </ins> TRANSPORT is used. The quic_transport_parameters extension is carried in the ClientHello
Original text:
A client MUST NOT send a DUPLICATE_PUSH frame.  A server MUST treat the receipt of a DUPLICATE_PUSH frame as a connection error of type <del> HTTP_MALFORMED_FRAME. </del>  The DUPLICATE_PUSH frame carries a single variable-length integer that identifies the Push ID of a resource that the server has

Reviewer comments:
I believe UNEXPECTED_FRAME is the preferred type.
I actually prefer the wording in duplicate push section and wonder if we should port that to PUSH_PROMISE too

Revised text:
A client MUST NOT send a DUPLICATE_PUSH frame.  A server MUST treat the receipt of a DUPLICATE_PUSH frame as a connection error of type  <ins> HTTP_UNEXPECTED_FRAME. </ins> The DUPLICATE_PUSH frame carries a single variable-length integer that identifies the Push ID of a resource that the server has
Original text:
can be mounted using spoofed source addresses.  In determining this limit, servers only count the size of successfully processed packets. <del> Clients MUST ensure that UDP datagrams containing Initial packets are sized to at least 1200 bytes, adding padding to packets in the datagram as necessary.  Once a client has received an acknowledgment for a Handshake packet it MAY send smaller datagrams.  Sending padded datagrams ensures that the server is not overly constrained by the amplification restriction. </del>  Packet loss, in particular loss of a Handshake packet from the server, can cause a situation in which the server cannot send when

Reviewer comments:
Builds on .
Initial packets need to be in 1200 byte datagrams for DoS amplification reasons. We have an exception for the case where an ACK for a Handshake packet has been received from the peer. In that case, we remove the requirement to pad. That condition is extraordinarily obscure, especially if we are suggesting that endpoints not send any more Initial packets once they have Handshake keys. Removing this text is the right answer.
+1 to the proposed resolution.

Revised text:
can be mounted using spoofed source addresses.  In determining this limit, servers only count the size of successfully processed packets.  <ins> Clients MUST ensure that UDP datagrams containing only Initial packets are sized to at least 1200 bytes, adding padding to packets in the datagram as necessary.  Sending padded datagrams ensures that the server is not overly constrained by the amplification restriction. </ins> Packet loss, in particular loss of a Handshake packet from the server, can cause a situation in which the server cannot send when
Original text:
though 1-RTT keys are available to a server after receiving the first handshake messages from a client, the server cannot consider the client to be authenticated until it receives and validates the <del> client's Finished message. </del>  The requirement for the server to wait for the client Finished message creates a dependency on that message being delivered.  A

Reviewer comments:
I realise this may be a bit out of context for this PR, but I can't find any clear definition of when the handshake is complete other than this being magically spawned from the inner workings of TLS.
Previous discussions have established the CFIN is HoL blocking, partially because even though it's not strictly necessary, if client auth is in use, it's critical to receive the client's entire Handshake flight before the server processes 1RTT packets. I don't think the current TLS text is sufficiently clear(and normative) about that. Section 4.1.1 has: "Important: Until the handshake is reported as complete, the connection and key exchange are not properly authenticated at the server. Even though 1-RTT keys are available to a server after receiving the first handshake messages from a client, the server cannot consider the client to be authenticated until it receives and validates the client's Finished message. The requirement for the server to wait for the client Finished message creates a dependency on that message being delivered. A client can avoid the potential for head-of-line blocking that this implies by sending a copy of the CRYPTO frame that carries the Finished message in multiple packets. This enables immediate server processing for those packets." URL
I agree, perhaps this section needs to say something along the lines of:
How is this not a duplicate of ?
Nevermind, I can fix this easily.

Revised text:
though 1-RTT keys are available to a server after receiving the first handshake messages from a client, the server cannot consider the client to be authenticated until it receives and validates the  <ins> client's Finished message.  A server MUST NOT process 1-RTT packets until the handshake is complete.  A server MAY buffer or discard 1-RTT packets that it cannot read. </ins> The requirement for the server to wait for the client Finished message creates a dependency on that message being delivered.  A
Original text:
contain frames. QUIC payloads MUST contain at least one frame, and MAY contain <del> multiple frames and multiple frame types. </del>  <del> Frames MUST fit within a single QUIC packet and MUST NOT span a QUIC packet boundary.  Each frame begins with a Frame Type, indicating its type, followed by additional type-dependent fields: </del>  The frame types defined in this specification are listed in frame- types.  The Frame Type in ACK, STREAM, MAX_STREAMS, STREAMS_BLOCKED,

Reviewer comments:
This was always intended (and also written in the description of FRAMEENCODINGERROR), but didn't show up in the text somehow.
I agree with NAME about the MUSTs that you shuffled around are statements of fact, not interoperability requirements, but the addition is fine.

Revised text:
contain frames. QUIC payloads MUST contain at least one frame, and MAY contain  <ins> multiple frames and multiple frame types.  Frames MUST fit within a single QUIC packet and MUST NOT span a QUIC packet boundary. </ins>  <ins> Each frame begins with a Frame Type, indicating its type, followed by additional type-dependent fields: </ins> The frame types defined in this specification are listed in frame- types.  The Frame Type in ACK, STREAM, MAX_STREAMS, STREAMS_BLOCKED,
Original text:
the frame.  These frames are explained in more detail in frame- formats.  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.

Reviewer comments:
This was always intended (and also written in the description of FRAMEENCODINGERROR), but didn't show up in the text somehow.
I agree with NAME about the MUSTs that you shuffled around are statements of fact, not interoperability requirements, but the addition is fine.

Revised text:
the frame.  These frames are explained in more detail in frame- formats. <ins> An endpoint MUST treat the receipt of a frame of unknown type as a connection error of type FRAME_ENCODING_ERROR. </ins> 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.
Original text:
Before a TLS ciphersuite can be used with QUIC, a header protection algorithm MUST be specified for the AEAD used with that ciphersuite. This document defines algorithms for AEAD_AES_128_GCM, <del> AEAD_AES_128_CCM, AEAD_AES_256_GCM, AEAD_AES_256_CCM (all AES AEADs are defined in AEAD), and AEAD_CHACHA20_POLY1305 CHACHA.  Prior to TLS selecting a ciphersuite, AES header protection is used (hp-aes), matching the AEAD_AES_128_GCM packet protection. </del>  5.4.2.

Reviewer comments:
draft-ietf-quic-tls currently mentions AEADAES256CCM, however there is no way to use that AEAD in TLS 1.3 - TLSAES256CCMSHA256 does not appear in the . If I understand this correctly, the presence of AEADAES256CCM in the document was an editorial oversight.
Thanks. This was extremely confusing: you meant CCM, but wrote GCM in tons of places.

Revised text:
Before a TLS ciphersuite can be used with QUIC, a header protection algorithm MUST be specified for the AEAD used with that ciphersuite. This document defines algorithms for AEAD_AES_128_GCM,  <ins> AEAD_AES_128_CCM, AEAD_AES_256_GCM (all AES AEADs are defined in AEAD), and AEAD_CHACHA20_POLY1305 CHACHA.  Prior to TLS selecting a ciphersuite, AES header protection is used (hp-aes), matching the AEAD_AES_128_GCM packet protection. </ins> 5.4.2.
Original text:
5.4.3. This section defines the packet protection algorithm for <del> AEAD_AES_128_GCM, AEAD_AES_128_CCM, AEAD_AES_256_GCM, and AEAD_AES_256_CCM.  AEAD_AES_128_GCM and AEAD_AES_128_CCM use 128-bit AES AES in electronic code-book (ECB) mode.  AEAD_AES_256_GCM, and AEAD_AES_256_CCM use 256-bit AES in ECB mode. </del>  This algorithm samples 16 bytes from the packet ciphertext.  This value is used as the input to AES-ECB.  In pseudocode:

Reviewer comments:
draft-ietf-quic-tls currently mentions AEADAES256CCM, however there is no way to use that AEAD in TLS 1.3 - TLSAES256CCMSHA256 does not appear in the . If I understand this correctly, the presence of AEADAES256CCM in the document was an editorial oversight.
Thanks. This was extremely confusing: you meant CCM, but wrote GCM in tons of places.

Revised text:
5.4.3. This section defines the packet protection algorithm for  <ins> AEAD_AES_128_GCM, AEAD_AES_128_CCM, and AEAD_AES_256_GCM. AEAD_AES_128_GCM and AEAD_AES_128_CCM use 128-bit AES AES in electronic code-book (ECB) mode.  AEAD_AES_256_GCM uses 256-bit AES in ECB mode. </ins> This algorithm samples 16 bytes from the packet ciphertext.  This value is used as the input to AES-ECB.  In pseudocode:
Original text:
8.1. <del> The QUIC version negotiation mechanism is used to negotiate the version of QUIC that is used prior to the completion of the handshake.  However, this packet is not authenticated, enabling an active attacker to force a version downgrade. To ensure that a QUIC version downgrade is not forced by an attacker, version information is copied into the TLS handshake, which provides integrity protection for the QUIC negotiation.  This does not prevent version downgrade prior to the completion of the handshake, though it means that a downgrade causes a handshake failure. </del> QUIC requires that the cryptographic handshake provide authenticated protocol negotiation.  TLS uses Application Layer Protocol Negotiation (ALPN) RFC7301 to select an application protocol.  Unless

Reviewer comments:
I must have missed this when making the PR to remove the version negotiation text. Thanks NAME !
I wasn’t aware that there was an issue. Sorry for that!
No worries, thanks for doing this!
We can probably remove big chunks of section "8.1. Protocol and Version Negotiation" since we don't do version negotiation anymore in v1.
Fixed with . Thanks NAME

Revised text:
8.1.  QUIC requires that the cryptographic handshake provide authenticated protocol negotiation.  TLS uses Application Layer Protocol Negotiation (ALPN) RFC7301 to select an application protocol.  Unless
Original text:
The most appropriate error code (error-codes) SHOULD be included in the frame that signals the error.  Where this specification identifies error conditions, it also identifies the error code that <del> is used. </del>  A stateless reset (stateless-reset) is not suitable for any error that can be signaled with a CONNECTION_CLOSE or RESET_STREAM frame.

Reviewer comments:
This just writes down what was proposed in .
Looks fine, but what about some guidance on stream vs connection errors? And also the principle of nearly always choosing a hard protocol violation error, or a more granular error with same effect?
Stream vs. connection is something that application protocols (like HTTP) need to worry about. The transport only concerns itself with connection errors. The idea that you pick the most helpful error is not something that we need to codify (in my view).
Isn't that worth mentioning? Or do we already have such text?
This is already discussed in Section 11, which makes me wonder if it would make more sense for text on this PR to be placed there too.
This I do not disagree with. I was merely suggesting that we explain why, as a general rule, a hard error is preferred as a design principle, not the nature of the error message which I do think should have a large degree of freedom.
Maybe there is a followup needed for the HTTP draft. If the principles are generally the same, we can copy the text and then add some more to cover the idea that we make most errors fatal to the connection rather than the stream.
I like Lucas suggestion of adding this text to the existing and already fairly complete text in section 11.
I moved the second paragraph up to the error handling section, but the text about how codes are selected really belongs with the codes themselves.
We don't really have any real principles that we agree on for deciding what error codes we are describing. Proposal: if the error carries distinct semantics (like stream rejection in HTTP), then it gets a new error code if the error is frequent or particularly significant, then it gets a new error code otherwise, target a more generic error code that identifies the broad area of the protocol finally, if there is no more specific applicable error code, use PROTOCOL_VIOLATION
is example of an issue discussed where it would have been useful to have principles.

Revised text:
The most appropriate error code (error-codes) SHOULD be included in the frame that signals the error.  Where this specification identifies error conditions, it also identifies the error code that  <ins> is used; though these are worded as requirements, different implementation strategies might lead to different errors being reported.  In particular, an endpoint MAY use any applicable error code when it detects an error condition; a generic error code (such as PROTOCOL_VIOLATION or INTERNAL_ERROR) can always be used in place of specific error codes. </ins> A stateless reset (stateless-reset) is not suitable for any error that can be signaled with a CONNECTION_CLOSE or RESET_STREAM frame.