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

Commentary: This has already been done at but somehow got reverted .
Paragraph (version A):
Once all accepted requests and pushes have been processed, the
endpoint can permit the connection to become idle, or MAY initiate an
immediate closure of the connection.  An endpoint that completes a
graceful shutdown SHOULD use the HTTP_NO_ERROR code when closing the
connection.
Paragraph (version B):
Once all accepted requests and pushes have been processed, the
endpoint can permit the connection to become idle, or MAY initiate an
immediate closure of the connection.  An endpoint that completes a
graceful shutdown SHOULD use the H3_NO_ERROR code when closing the
connection.
Draft: draft-ietf-quic-http

Commentary: Addresses comments on . While this adds a new MUST NOT , I believe it 's editorial because it 's simply stating the implicit result of the " MUST verify " in that PR . If anyone disagrees , speak up and I 'll change it . Separately , I think there 's a case for this " MUST NOT " to be a " SHOULD NOT , " as we all know there are situations in which clients proceed through a certificate warning . It 's a reasonable semantic distinction whether the client does not consider the server authoritative but processes the result anyway ( MUST NOT ) , or considers the server authoritative because the user told it to ( SHOULD NOT ) . Opinions on the bikeshed welcome .
Paragraph (version A):
Once a connection exists to a server endpoint, this connection MAY be
reused for requests with multiple different URI authority components.
In general, a server is considered authoritative for all URIs with
the "https" scheme for which the hostname in the URI is present in
the authenticated certificate provided by the server, either as the
CN field of the certificate subject or as a dNSName in the
subjectAltName field of the certificate (see RFC6125).  For a host
that is an IP address, the client MUST verify that the address
appears as an iPAddress in the subjectAltName field of the
certificate.
Paragraph (version B):
Once a connection exists to a server endpoint, this connection MAY be
reused for requests with multiple different URI authority components.
In general, a server is considered authoritative for all URIs with
the "https" scheme for which the hostname in the URI is present in
the authenticated certificate provided by the server, either as the
CN field of the certificate subject or as a dNSName in the
subjectAltName field of the certificate (see RFC6125).  For a host
that is an IP address, the client MUST verify that the address
appears as an iPAddress in the subjectAltName field of the
certificate.  If the hostname or address is not present in the
certificate, the client MUST NOT consider the server authoritative
for origins containing that hostname or address.  See Section 5.4 of
SEMANTICS for more detail on authoritative access.
Draft: draft-ietf-quic-transport

Commentary: This just writes down what suggested in . 
 Two things need to be clarified around SPA : The CID is not path - specific ; it 's there to ensure that the client has a second CID before the handshake completes . If the client opts not to migrate , the client can use that CID on the The IP addresses in the SPA are only for use in the transition post - handshake ; the client should not cache the IP addresses for any other use . 
 ( Just filling in the text here ) on the original address from the server , which is the existing connection , not - migrated . +1 to the second point 
 If the server is telling the client to migrate to a SPA , should this be changed to " the client MUST select one of the two server 's preferred addresses ... " ? If the text remains a SHOULD , and the client stays on the old server address , what can the server do if it is only willing to continue with the new connection on the SPA ? The server could close the initial connection using the old server address but there is n't a transport error code ( e.g. MIGRATION_ERROR ) that would explicitly tell the client why the connection is being closed . 
 The " SHOULD " is intentional . A server can not rely on clients moving . 
 Then perhaps a cautionary note such as " If the client opts not to migrate to a preferred address , the server may [ lower case ] decide to close the connection ( e.g. SERVER_BUSY ) " . 
 If the server is n't willing at all to handle connections on its published IP address , then ( naively ) it should n't accept connections on that IP address and should publish the other one instead . The scenario this targets is that it 's somehow better for the client to use a different address , but that other address ca n't necessarily be known in advance . 
 Migrating to a unicast address avoids having to perform connection - based routing through a load balancer .
Paragraph (version B):
The addresses that a server provides in the preferred_address
transport parameter are only valid for the connection in which they
are provided.  A client MUST NOT use these for other connections,
including connections that are resumed from the current connection.
Paragraph (version B):
The connection ID provided in the preferred_address transport
parameter is not specific to the addresses that are provided.  This
connection ID is provided to ensure that the client has a connection
ID available for migration, but the client MAY use this connection ID
on any path.
Draft: draft-ietf-quic-recovery

Commentary: Feel free to suggest better text or other reasons , but this is what I came up with . 
 QUIC spec uses kMinimumWindow of 2 MSS compared to TCP 's 1 MSS . Let 's state the deviation and add justifiaiton text . 
 LGTM , modulo one suggestion
Paragraph (version B):
TCP uses a minimum congestion window of one packet.  However, loss of
that single packet means that the sender needs to waiting for a PTO
(pto) to recover, which can be much longer than a round-trip time.
Sending a single ack-eliciting packet also increases the chances of
incurring additional latency when a receiver delays its
acknowledgement.
Paragraph (version B):
QUIC therefore recommends that the minimum congestion window be two
packets.  While this increases network load, it is considered safe,
since the sender will still reduce its sending rate exponentially
under persistent congestion (pto).
Draft: draft-ietf-quic-transport

Commentary: This is based on and is targeted for that . Careful . I did a bit of language tweaking to the 2 < sup60</suplimits on the MAX_STREAMS frame to make it a little more useful . The text there was a little old .
Paragraph (version A):
A count of the cumulative number of streams of the corresponding
type that can be opened over the lifetime of the connection.
Stream IDs cannot exceed 2^62-1, as it is not possible to encode
stream IDs larger than this value.  Receipt of a frame that
permits opening of a stream larger than this limit MUST be treated
as a FRAME_ENCODING_ERROR.
Paragraph (version B):
A count of the cumulative number of streams of the corresponding
type that can be opened over the lifetime of the connection.  This
value cannot exceed 2^60, as it is not possible to encode stream
IDs larger than 2^62-1.  Receipt of a frame that permits opening
of a stream larger than this limit MUST be treated as a
FRAME_ENCODING_ERROR.
Paragraph (version A):
A variable-length integer indicating the stream limit at the time
the frame was sent.  Stream IDs cannot exceed 2^62-1, as it is not
possible to encode stream IDs larger than this value.  Receipt of
a frame that encodes a larger stream ID MUST be treated as a
STREAM_LIMIT_ERROR or a FRAME_ENCODING_ERROR.
Paragraph (version B):
A variable-length integer indicating the maximum number of streams
allowed at the time the frame was sent.  This value cannot exceed
2^60, as it is not possible to encode stream IDs larger than
2^62-1.  Receipt of a frame that encodes a larger stream ID MUST
be treated as a STREAM_LIMIT_ERROR or a FRAME_ENCODING_ERROR.
Draft: draft-ietf-quic-qpack

Commentary: The algorithm was updated at somepoint but the example was lagging . 
   will be encoded modulo 6 . If a decoder has received 10 inserts , then an encoded value of 3 indicates that the Required Insert Count is 9 for the header block . should be   will be encoded modulo 6 . If a decoder has received 10 inserts , then an encoded value of 4 indicates that the Required Insert Count is 9 for the header block . Background : I implemented ReqInsertCount for decoder . When I test it with : MaxTableCapacity = 100 EncodedInsertCount = 3 TotalNumberOfInserts = 10 My function returns 8 , not 9.I guess that  = 4 is right since ReqInsertCount for encoder calculates 4 with ReqInsertCount = 9 . pointed out that it looks like the algorithm was replaced , and the example text we are looking at is left as is .
Paragraph (version A):
For example, if the dynamic table is 100 bytes, then the Required
Insert Count will be encoded modulo 6.  If a decoder has received 10
inserts, then an encoded value of 3 indicates that the Required
Insert Count is 9 for the header block.
Paragraph (version B):
For example, if the dynamic table is 100 bytes, then the Required
Insert Count will be encoded modulo 6.  If a decoder has received 10
inserts, then an encoded value of 4 indicates that the Required
Insert Count is 9 for the header block.
Draft: draft-ietf-quic-tls

Commentary: Now that we require a minimum packet size , this is no longer true . 
 Is this no longer true for the algorithms defined in the spec , or no longer true for any packet protection algorithms for any AEAD ? It might be worth moving the note to the end of 5.4.1 instead .
Paragraph (version A):
In some cases, inputs shorter than the full size required by the
packet protection algorithm might be used.
Draft: draft-ietf-quic-recovery

Commentary: By not arming the alarm , we avoid the possibility of having the alarm expire , send nothing , and then be immediately re - armed over and over again . We 've hit bugs like that a few times in our implementation , which is why I prefer this structure of not setting the alarm if you ca n't send anything . 
 From in , this is not a nit : Prior to validating the client address , servers MUST NOT send more than three times as many bytes as the number of bytes they have received . I think that the intent was that the server limit its sending , including PTO . 
 Discussed in ZRH . Proposed resolution is " yes " . 
 Repeating what I said earlier : it 's not clear to me that not being able to arm the PTO timer when at the limit implies that PTO packets count against the amplification limit . The reason is that you could have already armed the PTO timer at the time you hit the limit . E.g. , you might be streaming 0.5RTT and so send Initial , Handshake , arm timer , < wait0.5RTT . 
 the PTO should be updated when an ack - eliciting packet is sent , since the right edge moves , so that case should already be handled correctly . I 'll write an editorial PR to try to make all this extra clear . Actually , the PTO section already has " A sender computes its PTO timer every time an ack - eliciting packet is sent . " 
 Not sure how to split the difference between the limit applying to the packet that was just sent ( causing PTO to be armed ) or the packet that arming the PTO timer implies . Personally , I would have put the test at the point that you send a packet , but that 's not how this is structured , and you do have " because packets sent on PTO count against the anti - amplification limit " , which captures the important concept neatly .
Paragraph (version A):
Until the server has validated the client's address on the path, the
amount of data it can send is limited to three times the amount of
data received, as specified in Section 8.1 of QUIC-TRANSPORT.  If no
data can be sent, then the PTO alarm MUST NOT be armed until
datagrams have been received from the client.
Paragraph (version B):
Until the server has validated the client's address on the path, the
amount of data it can send is limited to three times the amount of
data received, as specified in Section 8.1 of QUIC-TRANSPORT.  If no
additional data can be sent, the server's PTO alarm MUST NOT be armed
until datagrams have been received from the client, because packets
sent on PTO count against the anti-amplification limit.  Note that
the server could fail to validate the client's address even if 0-RTT
is accepted.
Draft: draft-ietf-quic-recovery

Commentary: Moves some RECOMMENDEDs up and removes others which are already elsewhere in the draft and reference those sections . This was intended to address , which I can still do in this PR if would like , but I still think of Min CWND and Initial CWND as constants per - connection , even if they 're not truly constants .
Paragraph (version A):
The RECOMMENDED time threshold (kTimeThreshold), expressed as a
round-trip time multiplier, is 9/8.
Paragraph (version B):
The RECOMMENDED time threshold (kTimeThreshold), expressed as a
round-trip time multiplier, is 9/8.  The RECOMMENDED value of the
timer granularity (kGranularity) is 1ms.
Paragraph (version A):
A connection MAY use the delay between sending a PATH_CHALLENGE and
receiving a PATH_RESPONSE to set the initial RTT (see kInitialRtt in
ld-consts-of-interest) for a new path, but the delay SHOULD NOT be
considered an RTT sample.
Paragraph (version B):
A connection MAY use the delay between sending a PATH_CHALLENGE and
receiving a PATH_RESPONSE to set the initial RTT (see kInitialRtt in
pto-handshake) for a new path, but the delay SHOULD NOT be considered
an RTT sample.
Paragraph (version B):
When an ACK frame is received that establishes loss of all in-flight
packets sent over a long enough period of time, the network is
considered to be experiencing persistent congestion.  Commonly, this
can be established by consecutive PTOs, but since the PTO timer is
reset when a new ack-eliciting packet is sent, an explicit duration
must be used to account for those cases where PTOs do not occur or
are substantially delayed.  The rationale for this threshold is to
enable a sender to use initial PTOs for aggressive probing, as TCP
does with Tail Loss Probe (TLP) RACK, before establishing persistent
congestion, as TCP does with a Retransmission Timeout (RTO) RFC5681.
The RECOMMENDED value for kPersistentCongestionThreshold is 3, which
is approximately equivalent to two TLPs before an RTO in TCP.
Draft: draft-ietf-quic-transport

Commentary: I assume this has been the intention all along , but I do not find normative language in the current draft .
Paragraph (version A):
An endpoint that receives a STREAM frame for a send-only stream MUST
terminate the connection with error STREAM_STATE_ERROR.
Paragraph (version B):
An endpoint MUST terminate the connection with error
STREAM_STATE_ERROR if it receives a STREAM frame for a locally-
initiated stream that has not yet been created, or for a send-only
stream.
Draft: draft-ietf-quic-transport

Commentary: A sender can intentionally skip a packet number , causing the receiver to treat a packet as " Out - of - order " . From comment on
Paragraph (version A):
A packet that does not increase the largest received packet number
for its packet number space (packet-numbers) by exactly one.  A
packet can arrive out of order if it is delayed or if earlier
packets are lost or delayed.
Paragraph (version B):
A packet that does not increase the largest received packet number
for its packet number space (packet-numbers) by exactly one.  A
packet can arrive out of order if it is delayed, if earlier
packets are lost or delayed, or if the sender intentionally skips
a packet number.
Draft: draft-ietf-quic-recovery

Commentary: Let 's use the text from Section 9.1 of RFC 8126 with no embellishment .
Paragraph (version A):
This document has no IANA actions.  Yet.
Paragraph (version B):
This document has no IANA actions.
Draft: draft-ietf-quic-qpack

Commentary: This is for consistency with the HTTP/3 draft . Error codes were changed in .
Paragraph (version A):
HTTP/3 endpoints contain a QPACK encoder and decoder.  Each endpoint
MUST initiate at most one encoder stream and at most one decoder
stream.  Receipt of a second instance of either stream type MUST be
treated as a connection error of type HTTP_STREAM_CREATION_ERROR.
These streams MUST NOT be closed.  Closure of either unidirectional
stream type MUST be treated as a connection error of type
HTTP_CLOSED_CRITICAL_STREAM.
Paragraph (version B):
HTTP/3 endpoints contain a QPACK encoder and decoder.  Each endpoint
MUST initiate at most one encoder stream and at most one decoder
stream.  Receipt of a second instance of either stream type MUST be
treated as a connection error of type H3_STREAM_CREATION_ERROR.
These streams MUST NOT be closed.  Closure of either unidirectional
stream type MUST be treated as a connection error of type
H3_CLOSED_CRITICAL_STREAM.
Draft: draft-ietf-quic-recovery

Commentary: Another editorial PR to address comment .
Paragraph (version A):
A recovery period is entered when loss or ECN-CE marking of a packet
is detected in congestion avoidance but after the congestion window
and slow start threshold has been adapted.  A recovery period ends
when a packet sent during the recovery period is acknowledged.  This
is slightly different from TCP's definition of recovery, which ends
when the lost packet that started recovery is acknowledged.
Paragraph (version B):
A recovery period is entered when loss or ECN-CE marking of a packet
is detected in congestion avoidance after the congestion window and
slow start threshold have been decreased.  A recovery period ends
when a packet sent during the recovery period is acknowledged.  This
is slightly different from TCP's definition of recovery, which ends
when the lost packet that started recovery is acknowledged.
Draft: draft-ietf-quic-recovery

Commentary: The recovery draft says : " Resumed connections over the same network SHOULD use the previous connection 's final smoothed RTT value as the resumed connection 's initial RTT . " I wonder if we should change this to a MAY , as there is also a temporal aspect . Or maybe we should say more about this ? Also note that draft - ietf - tcpm-2140bis is probably related . 
 I would agree with switching to MAY . Even mentioning this leads to some incentive to implement , so the effect on implementation is similar . But we really do n't need to recommend something like this .
Paragraph (version A):
The initial probe timeout for a new connection or new path SHOULD be
set to twice the initial RTT.  Resumed connections over the same
network SHOULD use the previous connection's final smoothed RTT value
as the resumed connection's initial RTT.  If no previous RTT is
available, the initial RTT SHOULD be set to 500ms, resulting in a 1
second initial timeout as recommended in RFC6298.
Paragraph (version B):
The initial probe timeout for a new connection or new path SHOULD be
set to twice the initial RTT.  Resumed connections over the same
network MAY use the previous connection's final smoothed RTT value as
the resumed connection's initial RTT.  If no previous RTT is
available, the initial RTT SHOULD be set to 500ms, resulting in a 1
second initial timeout as recommended in RFC6298.
Draft: draft-ietf-quic-recovery

Commentary: Clarifies exactly what the implications of not arming PTO for ApplicationData prior to handshake complete . This came from a discussion with a coworker who read the transport and recovery drafts , but not TLS . 
 Thanks ! I think this is much clearer from implementation perspective .
Paragraph (version A):
A sender computes its PTO timer every time an ack-eliciting packet is
sent.  When ack-eliciting packets are in-flight in multiple packet
number spaces, the timer MUST be set for the packet number space with
the earliest timeout, except for ApplicationData, which MUST be
ignored until the handshake completes; see Section 4.1.1 of QUIC-TLS.
Not arming the PTO for ApplicationData prioritizes completing the
handshake and prevents the server from sending a 1-RTT packet on a
PTO before before it has the keys to process a 1-RTT packet.
Paragraph (version B):
A sender computes its PTO timer every time an ack-eliciting packet is
sent.  When ack-eliciting packets are in-flight in multiple packet
number spaces, the timer MUST be set for the packet number space with
the earliest timeout, except for ApplicationData, which MUST be
ignored until the handshake completes; see Section 4.1.1 of QUIC-TLS.
Not arming the PTO for ApplicationData prevents a client from
retransmitting a 0-RTT packet on a PTO expiration before confirming
that the server is able to decrypt 0-RTT packets, and prevents a
server from sending a 1-RTT packet on a PTO expiration before it has
the keys to process an acknowledgement.
Draft: draft-ietf-quic-transport

Commentary: This is n't strictly necessary , as it might be implied by the definition of a connection ID . I tried tweaking the connection ID definition , but it is hard to say anything concrete because of the way that addressing can also be used in combination with connection IDs to identify a connection at an endpoint . So I left that alone . 
 I agree that a connection ID identifies one session , and due to forbidden correlation , it is clear that a connection ID in use can not proliferate . However , this is not implied for newly issued connection IDs . There is precedence for new tokens which do apply to new connections , so I think it is worth being precise here . 
 the text " Connection IDs that are issued and not retired are considered active ; any active connection ID is valid for use at any time , in any packet type . " As far as I can tell there is no text specifying that an issued connection ID can not be used with subsequent connections . The introduction to connection IDs state that there must not be correlation across connections , but if an issued connection ID was never consumed , there would be no correlation because it was transmitted encrypted . 
 Not really sure if this is necessary . The text around this sentence implies that connection IDs identify one connection ( which should n't be too surprising in the first place ) . It 's only when you take this one sentence out of context , that the " problem " of occurs .
Paragraph (version A):
When an endpoint issues a connection ID, it MUST accept packets that
carry this connection ID for the duration of the connection or until
its peer invalidates the connection ID via a RETIRE_CONNECTION_ID
frame (frame-retire-connection-id).  Connection IDs that are issued
and not retired are considered active; any active connection ID is
valid for use at any time, in any packet type.  This includes the
connection ID issued by the server via the preferred_address
transport parameter.
Paragraph (version B):
When an endpoint issues a connection ID, it MUST accept packets that
carry this connection ID for the duration of the connection or until
its peer invalidates the connection ID via a RETIRE_CONNECTION_ID
frame (frame-retire-connection-id).  Connection IDs that are issued
and not retired are considered active; any active connection ID is
valid for use with the current connection at any time, in any packet
type.  This includes the connection ID issued by the server via the
preferred_address transport parameter.