jiebi/ids-paragraph-commentary-corpus huggingface dataset:
Draft: draft-ietf-masque-h3-datagram

Commentary: The draft currently states : However in PR , points out that this " state " is not well defined . I agree , we should fix it . Thinking about this more , I do n't think we need the concept of related state . We can instead just say that received datagrams MUST be silently dropped if the stream receive side is closed . 
 I agree with removing the concept of state is better . I do n't want to be overly nitty and the proposed sentence is better but there also nothing like " the stream receive side " , as there can be multiple streams ( open and closed ) , that 's why I proposed Or if we do n't want state , then it would be : 
 That 's not quite right : there can not be multiple streams , as datagrams are strongly associated with a client - initiated bidirectional stream . I 'd phrase the paragraph as : open . If a datagram is received after the receive side of the corresponding stream is closed , the received datagrams MUST be silently dropped . 
 That works . Thanks ! 
 This answer is necessary because QUIC does n't guarantee ordering , but is this necessarily true indefinitely ? But can I regard a datagram that arrives an hour after the stream closes as an error ? 
 If you keep track of QUIC packet numbers , you can see that the peer closed the stream before it sent the datagram which means they violated a MUST . You 're welcome to error if you detect that , but I do n't think we should mandate this level of tracking . 
 I 'm not sure that that is a good strategy given how some deployments manage their packet numbers . I 'm talking about maybe running a really long timer . 
 That introduces a way for an attacker to cause connection closure by delaying a specific packet . What problem are you trying to solve ? 
 Good point . I thought that we did similar in a few places in QUIC . As you say , it 's possible to enforce , but tricky . The concern I 'd have is that this effectively forbids enforcement , but maybe that 's OK .
HTTP/3 Datagrams MUST NOT be sent unless the corresponding stream's
send side is open.  Once the receive side of a stream is closed,
incoming datagrams for this stream are no longer expected so related
state can be released.  State MAY be kept for a short time to account
for reordering.  Once the state is released, the received associated
datagrams MUST be silently dropped.
HTTP/3 Datagrams MUST NOT be sent unless the corresponding stream's
send side is open.  If a datagram is received after the corresponding
stream's receive side is closed, the received datagrams MUST be
silently dropped.
Draft: draft-ietf-masque-h3-datagram

Commentary: The text of the draft currently defines how the header works , but there 's no RFC 2119 text explaining whether the client MUST or MAY send it ( and the corresponding receiver behavior in case the header is missing ) . 
 The draft currently states - right now it 's up to CONNECT - UDP / WebTransport , etc to define this normative text . Is that acceptable ? 
 Sure , but it 's not clear from the current text that the drafts have to give the specific guidance about the use of the header ( the WebTransport draft currently does not ) . 
 Fair enough . I suggest we replace that sentence with something along the lines of :
Definitions of new HTTP Upgrade Tokens that use the Capsule Protocol
MAY use the Capsule-Protocol header field to simplify intermediary
processing.
HTTP endpoints SHOULD use the Capsule-Protocol header field to
simplify intermediary processing.  Definitions of new HTTP Upgrade
Tokens that use the Capsule Protocol MAY alter this recommendation.
Draft: draft-ietf-masque-h3-datagram

Commentary: make HTTP version refs smarter ref something for upgrade token ref structured fields smarter
This specification introduces the Capsule Protocol.  The Capsule
Protocol is a sequence of type-length-value tuples that new HTTP
Upgrade Tokens can choose to use.  It allows endpoints to reliably
communicate request-related information end-to-end on HTTP request
streams, even in the presence of HTTP intermediaries.  The Capsule
Protocol can be used to exchange HTTP Datagrams when HTTP is running
over a transport that does not support the QUIC DATAGRAM frame.
This specification introduces the Capsule Protocol.  The Capsule
Protocol is a sequence of type-length-value tuples that new HTTP
Upgrade Tokens (see Section 16.7 of HTTP) can choose to use.  It
allows endpoints to reliably communicate request-related information
end-to-end on HTTP request streams, even in the presence of HTTP
intermediaries.  The Capsule Protocol can be used to exchange HTTP
Datagrams when HTTP is running over a transport that does not support
the QUIC DATAGRAM frame.
When an error occurs processing the capsule protocol, the receiver
MUST treat the message as malformed or incomplete, according to the
underlying transport protocol.  For HTTP/3, the handling of malformed
messages is described in section 4.1.3 of H3.  For HTTP/2, the
handling of malformed messages is described in section 8.1.2.6 of H2.
For HTTP/1.1, the handling of incomplete messages is described in
section 8 of CORE-MESSAGING.
When an error occurs processing the capsule protocol, the receiver
MUST treat the message as malformed or incomplete, according to the
underlying transport protocol.  For HTTP/3, the handling of malformed
messages is described in Section 4.1.3 of H3.  For HTTP/2, the
handling of malformed messages is described in Section 8.1.1 of H2.
For HTTP/1.1, the handling of incomplete messages is described in
Section 8 of H1.
Draft: draft-ietf-masque-h3-datagram

Commentary: In Section 2 we start with the statement So let 's just use that clearer description in the abstract and introduction too ,
The QUIC DATAGRAM extension provides application protocols running
over QUIC with a mechanism to send unreliable data while leveraging
the security and congestion-control properties of QUIC.  However,
QUIC DATAGRAM frames do not provide a means to demultiplex
application contexts.  This document describes how to use QUIC
DATAGRAM frames when the application protocol running over QUIC is
HTTP/3.  It associates datagrams with client-initiated bidirectional
streams.  Additionally, this document defines the Capsule Protocol
that can convey datagrams over prior versions of HTTP.
The QUIC DATAGRAM extension provides application protocols running
over QUIC with a mechanism to send unreliable data while leveraging
the security and congestion-control properties of QUIC.  However,
QUIC DATAGRAM frames do not provide a means to demultiplex
application contexts.  This document describes how to use QUIC
DATAGRAM frames with HTTP/3 by association with HTTP requests.
Additionally, this document defines the Capsule Protocol that can
convey datagrams over prior versions of HTTP.
The QUIC DATAGRAM extension DGRAM provides application protocols
running over QUIC QUIC with a mechanism to send unreliable data while
leveraging the security and congestion-control properties of QUIC.
However, QUIC DATAGRAM frames do not provide a means to demultiplex
application contexts.  This document describes how to use QUIC
DATAGRAM frames when the application protocol running over QUIC is
HTTP/3 H3.  It associates datagrams with client-initiated
bidirectional streams.  Additionally, this document defines the
Capsule Protocol that can convey datagrams over prior versions of
HTTP.
The QUIC DATAGRAM extension DGRAM provides application protocols
running over QUIC QUIC with a mechanism to send unreliable data while
leveraging the security and congestion-control properties of QUIC.
However, QUIC DATAGRAM frames do not provide a means to demultiplex
application contexts.  This document describes how to use QUIC
DATAGRAM frames with HTTP/3 H3 by association with HTTP requests.
Additionally, this document defines the Capsule Protocol that can
convey datagrams over prior versions of HTTP.
Draft: draft-ietf-masque-h3-datagram

Commentary: When reviewing the latest editors copy , the document structure leaps out at a bit odd by jumping from section 3 to section 5 . That indicates to me these concepts are linked and also independent of the capsule protocol . So here I propose a minor restructure by moving the H3_DATAGRAM setting stuff to be a subsection of the HTTP/3 datagram format . This makes all the top - layer sections loosely coupled , which is nicer in my opinion .
format defines how QUIC DATAGRAM frames are used with HTTP/3.
setting defines an HTTP/3 setting that endpoints can use to
advertise support of the frame.
format defines how QUIC DATAGRAM frames are used with HTTP/3.
setting defines an HTTP/3 setting that endpoints can use to
advertise support of the frame.
Draft: draft-ietf-masque-h3-datagram

Commentary: This just stuck out as something worth explicitly mentioning in the abstract ( and therefore the intro ) .
The QUIC DATAGRAM extension provides application protocols running
over QUIC with a mechanism to send unreliable data while leveraging
the security and congestion-control properties of QUIC.  However,
QUIC DATAGRAM frames do not provide a means to demultiplex
application contexts.  This document describes how to use QUIC
DATAGRAM frames when the application protocol running over QUIC is
HTTP/3.  It associates datagrams with client-initiated bidirectional
streams.  Additionally, this document defines a mechanism to convey
datagrams over prior versions of HTTP.
The QUIC DATAGRAM extension provides application protocols running
over QUIC with a mechanism to send unreliable data while leveraging
the security and congestion-control properties of QUIC.  However,
QUIC DATAGRAM frames do not provide a means to demultiplex
application contexts.  This document describes how to use QUIC
DATAGRAM frames when the application protocol running over QUIC is
HTTP/3.  It associates datagrams with client-initiated bidirectional
streams.  Additionally, this document defines the Capsule Protocol
that can convey datagrams over prior versions of HTTP.
The QUIC DATAGRAM extension DGRAM provides application protocols
running over QUIC QUIC with a mechanism to send unreliable data while
leveraging the security and congestion-control properties of QUIC.
However, QUIC DATAGRAM frames do not provide a means to demultiplex
application contexts.  This document describes how to use QUIC
DATAGRAM frames when the application protocol running over QUIC is
HTTP/3 H3.  It associates datagrams with client-initiated
bidirectional streams.  Additionally, this document defines a
mechanism to convey datagrams over prior versions of HTTP.
The QUIC DATAGRAM extension DGRAM provides application protocols
running over QUIC QUIC with a mechanism to send unreliable data while
leveraging the security and congestion-control properties of QUIC.
However, QUIC DATAGRAM frames do not provide a means to demultiplex
application contexts.  This document describes how to use QUIC
DATAGRAM frames when the application protocol running over QUIC is
HTTP/3 H3.  It associates datagrams with client-initiated
bidirectional streams.  Additionally, this document defines the
Capsule Protocol that can convey datagrams over prior versions of
HTTP.
Draft: draft-ietf-masque-h3-datagram

Commentary: We say : This has some parallels to Extensible Priorities where we are expected to handling an H3 frame that might reference a stream that has not yet been created ( most likely due to reordering ) . We ca n't avoid reordering but we can be more conservative on the frames that do get buffered . says : We can probably recommend something similar here . 
 This makes sense , sending an HTTP Datagram for a stream that you 're not yet allowed to create violates a MUST in a detectable way so we can recommend punishment . Though I doubt that we 'd implement this check .
If an HTTP/3 datagram is received and its Quarter Stream ID maps to a
stream that cannot be created due to client-initiated bidirectional
stream limits, it SHOULD be treated as a connection error of type
H3_ID_ERROR.  Generating an error is not mandatory in this case
because HTTP/3 implementations might have practical barriers to
determining the active stream concurrency limit that is applied by
the QUIC layer.
Draft: draft-ietf-masque-h3-datagram

Commentary: The doc has evolved from just HTTP/3 Datagram , to define Capsule protocol and HTTP datagrams over capsule . In Security Considerations , we say It 's a little ambiguous what " this feature " on face value . Arguably , the recommendation to always send the setting could be done in the section that defines the setting . Some editorial work would address these concerns . 
 Agreed 
 The intent is much clearer to me now , thanks !
It is RECOMMENDED that implementations that support receiving HTTP
Datagrams using QUIC always send the H3_DATAGRAM SETTINGS parameter
with a value of 1, even if the application does not intend to use
HTTP Datagrams.  This helps to avoid "sticking out"; see security.
Since this feature requires sending an HTTP/3 Settings parameter, it
"sticks out".  In other words, probing clients can learn whether a
server supports this feature.  Implementations that support this
feature SHOULD always send this Settings parameter to avoid leaking
the fact that there are applications using HTTP/3 datagrams enabled
on this endpoint.
Since transmitting HTTP Datagrams using QUIC DATAGRAM frames requires
sending an HTTP/3 Settings parameter, it "sticks out".  In other
words, probing clients can learn whether a server supports HTTP
Datagrams over QUIC DATAGRAM frames.  As some servers might wish to
obfuscate the fact that they offer application services that use HTTP
datagrams, it's best for all implementations that support this
feature to always send this Settings parameter, see setting.
Draft: draft-ietf-masque-h3-datagram

Commentary: cc 
 I think that this is right , but we should be more precise about what this means . That is , if the method is CONNECT and either : intermediary understands the : protocol selection , or request includes Capsule - Protocol Then the intermediary can forward DATAGRAM capsules as QUIC DATAGRAM frames or forward QUIC DATAGRAM frames as DATAGRAM capsules . Those conditions could be spelled out more clearly . 
 I agree . I 'll add this to the . Note that this was filed on the wrong repository , is the droid you 're looking for . 
 Oops . You should be able to move the issue . 
 Ah right , thanks ! I 've moved the issue .
Capsules MUST be forwarded unmodified by intermediaries, with the
exception of the DATAGRAM capsule; see datagram-capsule.  An
intermediary that understands the request semantics enough to know
that capsules are in use MAY convert between QUIC DATAGRAM frames and
DATAGRAM capsules.  Definitions of new Capsule Types MAY specify
optional custom intermediary processing.
Capsules MUST be forwarded unmodified by intermediaries, with the
exception of the DATAGRAM capsule; see datagram-capsule.  An
intermediary can identify the use of the capsule protocol either
through the presence of the Capsule-Protocol header field (hdr) or by
understanding the chosen HTTP Upgrade token.  An intermediary that
identifies the use of the capsule protocol MAY convert between
DATAGRAM capsules and QUIC DATAGRAM frames when forwarding.
Definitions of new Capsule Types MAY specify optional custom
intermediary processing.
Draft: draft-ietf-masque-h3-datagram

Commentary: Borrowing text from H3 . Also I do n't think there is a ' FRAMEENCODINGERROR ' defined anywhere . 
 Thanks ! Approved pending some minor tweaks
Receipt of a QUIC DATAGRAM frame whose payload is too short to allow
parsing the Quarter Stream ID field MUST be treated as an HTTP/3
connection error of type H3_GENERAL_PROTOCOL_ERROR.
Receipt of a QUIC DATAGRAM frame whose payload is too short to allow
parsing the Quarter Stream ID field MUST be treated as an HTTP/3
connection error of type H3_DATAGRAM_ERROR.
When an error occurs processing the capsule protocol, the receiver
MUST treat the message as malformed or incomplete, according to the
underlying transport protocol.  For HTTP/3, the handling of malformed
messages is described in section 4.1.3 of H3.  For HTTP/2, the
handling of malformed messages is described in section 8.1.2.6 of H2.
For HTTP/1.1, the handling of incomplete messages is described in
section 8 of CORE-MESSAGING.
Each capsule's payload MUST contain exactly the fields identified in
its description.  A capsule payload that contains additional bytes
after the identified fields or a capsule payload that terminates
before the end of the identified fields MUST be treated as a
malformed or incomplete message.  In particular, redundant length
encodings MUST be verified to be self-consistent.
When a stream carrying capsules terminates cleanly, if the last
capsule on the stream was truncated, this MUST be treated as a
malformed or incomplete message.
Draft: draft-ietf-masque-h3-datagram

Commentary: Most likely just need a sentence saying that the data stream is treated the same regardless if capsules are used or not . 
 Adding that sentence sounds fine by me .
Data streams (see capsule-protocol) can be prioritized using any
means suited to stream or request prioritization.  For example,
Section 11 of PRIORITY.
Draft: draft-ietf-masque-h3-datagram

Commentary: … king hte law Also , switch to format to beatuiful superscript HTML rendering as used by RFC 9000 . 
 Stating the obvious here . But we 're using value with a legal range larger than semantically legal . RFC 9000 has some similar caveats with MAXSTREAMS To address this , the suggestion is to add something like 
 That suggestion sounds good to me .
Contexts are optional, whether to use them or not is decided by the
client on each request stream using registration capsules, see
register-capsule and register-no-context-capsule.  When contexts are
used, they are identified within the scope of a given request by a
numeric value, referred to as the context ID.  A context ID is a
62-bit integer (0 to 2^62-1).
Draft: draft-ietf-masque-h3-datagram

Commentary: err'ing on the side of succinct 
 There 's now several different concepts to wrangle in this document . Reading from the top , we first tackle multiplexing ( the major motivation for the document ) , then the frame , then capsules . Capsules underpin the mechanics of multiplexing . I do n't think we can fix this chicken and egg problem but adding a brief overview of the concepts and terms before they are tackled in the prose could help readability . 
 I think that sounds like a great idea ! 
 Thanks for doing this !
multiplexing presents core concepts for multiplexing across HTTP
versions.
datagram-contexts defines datagram contexts, an optional end-
to-end multiplexing concept scoped to each HTTP request.
datagram-formats defines datagram formats, which are scoped to
contexts.  Formats communicate the format and encoding of
datagrams sent using the associated context.
Contexts are identified using a variable-length integer.
Requirements for allocating identifier values are detailed in
context-id-alloc.
format defines how QUIC DATAGRAM frames are used with HTTP/3.
setting defines an HTTP/3 setting that endpoints can use to
advertise support of the frame.
capsule introduces the Capsule Protocol and the "data stream"
concept.  Data streams are initiated using special-purpose HTTP
requests, after which Capsules, an end-to-end message, can be
sent.
Draft: draft-ietf-masque-h3-datagram

Commentary: The thing that sucks here is that the diagram wo n't auto expand , so we ca n't easily ref the section . Manually referring to the section is a maintenance pain . So instead just state the actual type in the text an the diagram . I have a feeling you were linking to the section to avoid the maintenance hassle of updating type codes in multiple place . But I 'm quite happy to take that burden because I find it more pleasant to read this way . 
 Perfectly reasonable 
 QUIC and HTTP/3 style is to define the general format and then in each instance define the object including all of its fields . This would look like This can later be updated with the actual type value once things settle down 
 Fine by me . 
 There 's a disparity between the largest flow ID that can be carried in the DATAGRAM frame and the largest that we can express in Datagram - Flow - Id. Draft 00 prevents a flow ID allocation of = 10 ^ 15 - 1 but does n't seem to address the case where a DATAGRAM frame contains that value . This is clearly an error , and I 'd suggest that it is a connection error ; probably or some new codepoint if we really wanted . 
 I do n't think that needs to be an error , we can simply treat this like any other unknown flow ID ? 
 IMO this is clearly a situation that should n't happen and indicates the sending endpoint probably has some bug . I 'm not sure on what being silent on the matter helps . 
 This issue is no longer relevant now that we have merged , closing .
The REGISTER_DATAGRAM_CONTEXT capsule (see iana-types for the value
of the capsule type) allows an endpoint to inform its peer of the
encoding and semantics of datagrams associated with a given context
ID.
The REGISTER_DATAGRAM_NO_CONTEXT capsule (see iana-types for the
value of the capsule type) allows a client to inform the server that
datagram contexts will not be used with this stream.  It also informs
the server of the encoding and semantics of datagrams associated with
this stream.
The CLOSE_DATAGRAM_CONTEXT capsule (see iana-types for the value of
the capsule type) allows an endpoint to inform its peer that it will
no longer send or parse received datagrams associated with a given
context ID.
The DATAGRAM capsule (see iana-types for the value of the capsule
type) allows an endpoint to send a datagram frame over an HTTP
stream.  This is particularly useful when using a version of HTTP
that does not support QUIC DATAGRAM frames.
Draft: draft-ietf-masque-h3-datagram

Commentary: It does n't appear that the peer has any say in the allocation of context IDs . If not , they 're not really " negotiated . " Perhaps better to say that they are " declared " or merge with " allocated . "
Contexts are optional, their use is negotiated on each request stream
using registration capsules, see register-capsule and register-no-
context-capsule.  When contexts are used, they are identified within
the scope of a given request by a numeric value, referred to as the
context ID.  A context ID is a 62-bit integer (0 to 2^62-1).
Contexts are optional, whether to use them or not is decided by the
client on each request stream using registration capsules, see
register-capsule and register-no-context-capsule.  When contexts are
used, they are identified within the scope of a given request by a
numeric value, referred to as the context ID.  A context ID is a
62-bit integer (0 to 2^62-1).
Intermediaries parse the Quarter Stream ID field in order to
associate the QUIC DATAGRAM frame with a stream.  If an intermediary
receives a QUIC DATAGRAM frame whose payload is too short to allow
parsing the Quarter Stream ID field, the intermediary MUST treat it
as an HTTP/3 connection error of type H3_GENERAL_PROTOCOL_ERROR.  The
Context ID field is optional and its use is negotiated end-to-end,
see register-no-context-capsule.  Therefore intermediaries cannot
know whether the Context ID field is present or absent and they MUST
ignore any HTTP/3 Datagram fields after the Quarter Stream ID.
Intermediaries parse the Quarter Stream ID field in order to
associate the QUIC DATAGRAM frame with a stream.  If an intermediary
receives a QUIC DATAGRAM frame whose payload is too short to allow
parsing the Quarter Stream ID field, the intermediary MUST treat it
as an HTTP/3 connection error of type H3_GENERAL_PROTOCOL_ERROR.  The
Context ID field is optional and whether it is present or not is
decided end-to-end by the client, see register-no-context-capsule.
Therefore intermediaries cannot know whether the Context ID field is
present or absent and they MUST ignore any HTTP/3 Datagram fields
after the Quarter Stream ID.
Extensions MAY define a different mechanism to negotiate the presence
of contexts, and they MAY do so in a way which is opaque to
intermediaries.
Extensions MAY define a different mechanism to communicate whether
contexts are in use, and they MAY do so in a way which is opaque to
intermediaries.