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

Commentary: We had the following questions related to the descriptions of " HTTP Datagrams " in a few places throughout the text . a ) We see the following similar sentences in the Abstract , Introduction , and , respectively . Please review and let us know if this text should be made more uniform . Original ( Abstract ): This document describes HTTP Datagrams , a convention for conveying multiplexed , potentially unreliable datagrams inside an HTTP connection . Original ( Intro ): In , this document describes HTTP Datagrams , a convention that supports the bidirectional and optionally multiplexed exchange of data inside an HTTP connection . Original ( ): HTTP Datagrams are a convention for conveying bidirectional and potentially unreliable datagrams inside an HTTP connection , with multiplexing when possible . b ) Pending changes made in ( a ) above , we will update the first sentence of the Abstract as follows unless we hear objection Original : This document describes HTTP Datagrams , a convention for conveying multiplexed , potentially unreliable datagrams inside an HTTP connection . Perhaps : This document describes a convention for conveying multiplexed , potentially unreliable datagrams inside an HTTP connection called “ HTTP Datagrams ” . c ) This sentence , which is somewhat related , seems a bit odd in that it seems sending something " unreliably " is desired . Should any clarification here be ? Original : In HTTP/3 , HTTP Datagrams can be sent unreliably using the QUIC DATAGRAM extension . 
 a ) I 'm happy with the abstract being succinct . I think we could probably my the Intro and Section 2 more uniform . Suggest use Section 2 text in the intro . b ) I 'm not a huge fan of the scary quotes suggested here . I like what we have already TBH . c ) This seems fine . No change needed IMO 
 Fully agree with your comments
In capsule, this document describes the HTTP Capsule Protocol, which
allows the conveyance of HTTP Datagrams using reliable delivery.
This addresses HTTP/3 cases where use of the QUIC DATAGRAM frame is
unavailable or undesirable or where the transport protocol only
provides reliable delivery, such as with HTTP/1.1 H1 or HTTP/2 H2
over TCP TCP.
In capsule, this document describes HTTP Datagrams, a convention for
conveying bidirectional and potentially unreliable datagrams inside
an HTTP connection, with multiplexing when possible.  This addresses
HTTP/3 cases where use of the QUIC DATAGRAM frame is unavailable or
undesirable or where the transport protocol only provides reliable
delivery, such as with HTTP/1.1 H1 or HTTP/2 H2 over TCP TCP.
Draft: draft-ietf-masque-h3-datagram

Commentary: Is it really the Definition that performs the security analysis ? Original : Definitions of new HTTP Upgrade Tokens that use the Capsule Protocol need to perform a security analysis that considers the impact of HTTP Datagrams and Capsules in the context of their protocol . Perhaps : Definitions of new HTTP Upgrade Tokens that use the Capsule Protocol need to include a security analysis that considers the impact of HTTP Datagrams and Capsules in the context of their protocol . 
 I prefer the RFC editor suggestion here . 
 Same , works for me
Definitions of new HTTP Upgrade Tokens that use the Capsule Protocol
need to perform a security analysis that considers the impact of HTTP
Datagrams and Capsules in the context of their protocol.
Definitions of new HTTP Upgrade Tokens that use the Capsule Protocol
need to include a security analysis that considers the impact of HTTP
Datagrams and Capsules in the context of their protocol.
Draft: draft-ietf-masque-h3-datagram

Commentary: In the following text , should the names of the status codes appear as they do in the rest of the document ? Original : ... a status code that is both different from 101 and outside the 2xx range . Perhaps : ... a status code that is both different from 101 ( Switching Protocols ) and outside the 2xx ( Successful ) range . 
 solid improvement , let 's do it 
 That sounds good to me
The Capsule-Protocol header field MUST NOT be used on HTTP responses
with a status code that is both different from 101 and outside the
2xx range.
The Capsule-Protocol header field MUST NOT be used on HTTP responses
with a status code that is both different from 101 (Switching
Protocols) and outside the 2xx (Successful) range.
Draft: draft-ietf-masque-h3-datagram

Commentary: We suggest rephrasing this sentence . The phrase " might have practical barriers to determining ... " is difficult to parse . Does the suggested text below accurately convey the intended meaning ? Original : 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 . Perhaps : Generating an error is not mandatory in this case because HTTP/3 implementations might present practical barriers when determining the active stream concurrency limit that is applied by the QUIC layer . 
 The point we 're making here is that the implementations might encounter barriers , either because they contain them , or the API the are using presents them . The suggestion does n't cover these two response . Alternative Perhaps : Generating an error is not mandatory in this case because there might be practical barriers that prevent HTTP/3 implementations from determining the active stream concurrency at the QUIC layer . 
 How about we just nuke this sentence ? 
 I 've just rememberd this text is verbatim copied from ADs seem to like justifcations for SHOULD requirements . If we 're worried about verbosity , then how about  an error is not mandatory because the QUIC stream limit may be unknown to the HTTP/3 layer . 
 That works for me
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 an HTTP/3 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.
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 an HTTP/3 connection error of
type H3_ID_ERROR.  Generating an error is not mandatory because the
QUIC stream limit might be unknown to the HTTP/3 layer.
Draft: draft-ietf-masque-h3-datagram

Commentary: To what does " these goals " refer ? Original : When HTTP Datagrams are conveyed on an HTTP/3 connection , the QUIC DATAGRAM frame can be used to achieve these goals , including unreliable delivery ; see 
 yeah , this text seems weird . Perhaps 
 Or how about simply 
 I made typos in my suggestion that does n't help , sorry . IIRC the original text is a roundabout way of saying - we use a special payload in QUIC datagrams in order to achieve unreliable datagram multiplexing . This makes more sense in the context of the next that then states HTTP/2 frames provide demultiplexing . 
 Right , how about
When HTTP Datagrams are conveyed on an HTTP/3 connection, the QUIC
DATAGRAM frame can be used to achieve these goals, including
unreliable delivery; see format.  Negotiating the use of QUIC
DATAGRAM frames for HTTP Datagrams is achieved via the exchange of
HTTP/3 settings; see setting.
When HTTP Datagrams are conveyed on an HTTP/3 connection, the QUIC
DATAGRAM frame can be used to provide demultiplexing and unreliable
delivery; see format.  Negotiating the use of QUIC DATAGRAM frames
for HTTP Datagrams is achieved via the exchange of HTTP/3 settings;
see setting.
Draft: draft-ietf-masque-h3-datagram

Commentary: Written in response to 
 From in reference to the text in this PR :
Definitions of new HTTP Upgrade Tokens that use the Capsule Protocol
need to perform a security analysis that considers the impact of HTTP
Datagrams and Capsules in the context of their protocol.
Draft: draft-ietf-masque-h3-datagram

Commentary: This adds a few statements through the text that explains that data streams are subject to any flow control provided by layers lower down . Wih that in mind , the potential for problem deadlocks should be clearer when we state it . 
 This is a non - blocking comment from AD review . I have no concerns if the authors choose to close it with no action . It might be worthwhile to discuss the interaction of stream flow control with capsule / datagram conversions . With other HTTP transactions , intermediaries can deliver whatever in - order bytes of the stream they have . When receiving capsules and emitting datagrams , if the stream flow control window is too small to accept the datagram size , there can be a deadlock . A sentence about this special case could avoid a silly implementer mistake . 
 I think this goes beyond just intermediaries . Instead it applies to any consumer of capsules where they might be tempted to try and buffer the capsule , in the data stream , in its entirety before processing or consuming it . That might be obvious as a " bad thing " for implementers that are already used to handling H2 or H3 frames . However , you identify that the DATAGRAM capsule is particularly tempting to buffer because it should be handled atomically . So I think it might help to briefly point out some deadlock considerations about flow window sizes in relation to capsule sizes , and processing / release of further window credits . 
 Adding a little bit of text to warn against such cases SGTM
Data streams are subject to the flow control mechanisms of the
underlying layers (for example, HTTP/2 stream flow control, HTTP/2
connection flow control, and TCP flow control).
When processing capsules, a receiver might tempted to accumulate the
full length of the capsule value in the data stream before handling
it.  This approach can consume flow control in underlying layers,
which might lead to deadlocks if the capsule data exhausts the flow
control window.
Since QUIC DATAGRAM frames are required to fit within a QUIC packet,
implementations that reencode DATAGRAM capsules into QUIC DATAGRAM
frames might be tempted to accumulate the entire capsule before
reencoding it.  This can cause flow control problems; see capsule-
protocol.
Draft: draft-ietf-masque-h3-datagram

Commentary: Issue created in reponse to considerations section seems straightforward . extensions " at first , but from context , I 'm guessing it 's used loosely to mean any addition to HTTP ? I found RFC 2774 when I was looking to see if it meant something specific , but I 'm guessing it 's not a reference to a 20 + year old experimental RFC ? The term HTTP extensions is defined in . Since we already have a normative reference to that document , I propose to resolve this issue by adding a reference to that section in our introduction . 
 Lgtm
HTTP extensions sometimes need to access underlying transport
protocol features such as unreliable delivery (as offered by DGRAM)
to enable desirable features.  For example, this could allow
introducing an unreliable version of the CONNECT method, or adding
unreliable delivery to WebSockets RFC6455.
HTTP extensions (as defined in HTTP) sometimes need to access
underlying transport protocol features such as unreliable delivery
(as offered by DGRAM) to enable desirable features.  For example,
this could allow introducing an unreliable version of the CONNECT
method, or adding unreliable delivery to WebSockets RFC6455.
Draft: draft-ietf-masque-h3-datagram

Commentary: Inspired by    suggestion to reference integer encoding more directly , this change just sticks it all in one place and makes it clear that there is no expectation to minimally - encode varints . Styled on similar references to QUIC made in
This document uses terminology from QUIC.
Where this document defines protocol types, the definition format
uses the notation from QUIC.  Where fields within types are integers,
they are encoded using the variable-length integer encoding from
QUIC.  Integer values do not need to be encoded on the minimum number
of bytes necessary.
Draft: draft-ietf-masque-h3-datagram

Commentary: Nit from AD review : The original sentence is ambiguously worded , and could be interpreted as saying that there could not be normal HTTP requests prior to the capsule protocol . 
 Thanks , this is an important clarification that makes clearer the original intent of the statement .
In HTTP/1.x, the data stream consists of all bytes on the connection
that follow the blank line that concludes either the request header
section, or the response header section.  As a result, only a single
HTTP request starting the capsule protocol can be sent on HTTP/1.x
connections.
In HTTP/1.x, the data stream consists of all bytes on the connection
that follow the blank line that concludes either the request header
section, or the response header section.  As a result, only the last
HTTP request on an HTTP/1.x connection can start the capsule
protocol.
Draft: draft-ietf-masque-h3-datagram

Commentary: Seeing support and hearing no pushback , merging this as today marks the end of WGLC 
 When the first IANA registry was to this document , it used " First Come First Served " to save time . This got carried over through the various changes and now the new " Capsule Type " registry is still marked that way . But in that corresponding time , the QUIC WG came up with a very good IANA policy for varint registries and documented it in RFC 9000 . We should adopt that policy for Capsule Types . 
 I would like to note that changes like this is not editorial , it is something that should have consensus call . 
 Hi Magnus , I agree that this issue is not editorial . That 's why I brought it up on this list over a week ago in its own thread ( ) . This received two approvals on and no other comments or concerns .
Registrations follow the "First Come First Served" policy (see
Section 4.4 of IANA-POLICY) where two registrations MUST NOT have the
same Type.
This document establishes a registry for HTTP capsule type codes.
The "HTTP Capsule Types" registry governs a 62-bit space, and
operates under the QUIC registration policy documented in QUIC.  This
new registry includes the common set of fields listed in QUIC.  In
addition to those common fields, all registrations in this registry
MUST include a "Capsule Type" field which contains a short name or
label for the capsule type.
Permanent registrations in this registry are assigned using the
Specification Required policy (IANA-POLICY), except for values
between 0x00 and 0x3f (in hexadecimal; inclusive), which are assigned
using Standards Action or IESG Approval as defined in Sections IANA-
POLICY and IANA-POLICY of IANA-POLICY.
Capsule types with a value of the form 41 * N + 23 for integer values
of N are reserved to exercise the requirement that unknown capsule
types be ignored.  These capsules have no semantics and can carry
arbitrary values.  These values MUST NOT be assigned by IANA and MUST
NOT appear in the listing of assigned values.
Draft: draft-ietf-masque-h3-datagram

Commentary: Section 1 : To my understanding WebSockets have no partial reliability features per that specification . So I think the formulation is missleading . To enable this in WebSockets , would it not require an update to WebSockets . I thought WebTrans is basically that update . So why not reference WebTrans here instead , it will anyway be an informational reference . 
 These are examples of potential future extensions that serve to illustrate the motivation . The fact that we 're not planning on building such examples does not diminish their usefulness . Readers might be more familiar with WebSocket than with WebTransport at this point .
HTTP extensions sometimes need to access underlying transport
protocol features such as unreliable delivery (as offered by DGRAM)
to enable desirable features like an unreliable version of the
CONNECT method, and unreliable delivery in WebSockets RFC6455 (or its
successors).
HTTP extensions sometimes need to access underlying transport
protocol features such as unreliable delivery (as offered by DGRAM)
to enable desirable features.  For example, this could allow
introducing an unreliable version of the CONNECT method, or adding
unreliable delivery to WebSockets RFC6455.
Draft: draft-ietf-masque-h3-datagram

Commentary: Using a slight variation of  's proposed text on the issue . 
 In Section 2 : " Negotiation is achieved using a setting ; see Section 2.1.1 . " So first I though this was just lacking an " HTTP " prior to the setting . But , I think this glosses over the general negotiation complications across versions . In this section when the high level functionality is defined , I think actually the question of negotiation in general needs to be discussed , not only for HTTP/3 . 
 I do n't understand this issue , could you elaborate ? I 'm assuming you are talking about Section 2 para 2 , which says : The remaining paragraphs deal with consideration of other versions , and mention negotiation . 
 I think we can improve clarity here . Right now we have in the " HTTP Datagrams " section . We should spell it out better , maybe : 
 WFM
When HTTP Datagrams are conveyed on an HTTP/3 connection, the QUIC
DATAGRAM frame can be used to achieve these goals, including
unreliable delivery; see format.  Negotiation is achieved using a
setting; see setting.
When HTTP Datagrams are conveyed on an HTTP/3 connection, the QUIC
DATAGRAM frame can be used to achieve these goals, including
unreliable delivery; see format.  Negotiating the use of QUIC
DATAGRAM frames for HTTP Datagrams is achieved via the exchange of
HTTP/3 settings; see setting.
Draft: draft-ietf-masque-h3-datagram

Commentary: ... and indirectly associated with streams 
 Section 2 : " HTTP Datagrams MUST only be sent with an association to a stream whose HTTP semantics explicitly supports HTTP Datagrams . " I think the reference to " stream " is unclear here . Is the intention here to refer to " HTTP Message " or " HTTP Method " that would then in HTTP/2 and HTTP/3 map to a stream ? Anyway align with next paragraph that uses " Method " . 
 The subsequent use of " method " is not great . I would substitute both with " request " e.g. " HTTP Datagrams MUST only be sent with an association to an HTTP request that explicitly supports them . " ... " If an HTTP Datagram is received and it is associated with a request that does not support HTTP Datagrams , the receiver MUST terminate the request .... " 
 Agreed , switching to request would be clearer
HTTP Datagrams MUST only be sent with an association to a stream
whose HTTP semantics explicitly supports HTTP Datagrams.  For
example, existing HTTP methods GET and POST do not define semantics
for associated HTTP Datagrams; therefore, HTTP Datagrams cannot be
sent associated with GET or POST request streams.
If an HTTP Datagram associated with a method that has no known
semantics for HTTP Datagrams is received, the receiver MUST abort the
corresponding stream; if HTTP/3 is in use, the stream MUST be aborted
with H3_DATAGRAM_ERROR.  HTTP extensions can override these
requirements by defining a negotiation mechanism and semantics for
HTTP Datagrams.
HTTP Datagrams MUST only be sent with an association to an HTTP
request that explicitly supports them.  For example, existing HTTP
methods GET and POST do not define semantics for associated HTTP
Datagrams; therefore, HTTP Datagrams cannot be sent associated with
GET or POST request streams.
If an HTTP Datagram is received and it is associated with a request
that has no known semantics for HTTP Datagrams, the receiver MUST
terminate the request; if HTTP/3 is in use, the request stream MUST
be aborted with H3_DATAGRAM_ERROR.  HTTP extensions can override
these requirements by defining a negotiation mechanism and semantics
for HTTP Datagrams.
Draft: draft-ietf-masque-h3-datagram

Commentary: In Abstract : " Both are intended for use by HTTP extensions , not applications . " I think instead of using Both which is unclear , rather say HTTP Datagram and Capsule Protocol . That is at least what I interpret it to be in reference to . 
  , we should just write this out explicitly . 
 SGTM
Both are intended for use by HTTP extensions, not applications.
HTTP Datagrams and the Capsule Protocol are intended for use by HTTP
extensions, not applications.
Draft: draft-ietf-masque-h3-datagram

Commentary: The current text talks about " supporting " HTTP/3 datagrams . It seems we could tighten this up to be more about the willingness to receive datagrams a la 
 SGTM
Implementations of HTTP/3 that support HTTP Datagrams can indicate
that to their peer by sending the H3_DATAGRAM SETTINGS parameter with
a value of 1.
The value of the H3_DATAGRAM SETTINGS parameter MUST be either 0 or
the H3_DATAGRAM SETTINGS parameter is received with a value that is
neither 0 or 1, the receiver MUST terminate the connection with error
H3_SETTINGS_ERROR.
Implementations of HTTP/3 that are willing to receive HTTP Datagrams
can indicate that to their peer by sending the H3_DATAGRAM SETTINGS
parameter with a value of 1.
The value of the H3_DATAGRAM SETTINGS parameter MUST be either 0 or
receive HTTP Datagrams.  If the H3_DATAGRAM SETTINGS parameter is
received with a value that is neither 0 or 1, the receiver MUST
terminate the connection with error H3_SETTINGS_ERROR.
Draft: draft-ietf-masque-h3-datagram

Commentary: End of section 3.3 . ( error handing ) says : Not sure I can parse that sentence correctly . Is that ? 
 " terminates cleanly " is an abstract way of covering all HTTP versions notion of a stream FIN . This is not well defined ( maybe lost in one of the restructuring edits ? ) . If we think of HTTP/3 and the request stream being FIN'd at a particular offset , that is independent of a parser acting on the data in the stream . I think the way to make this clearer is to define or reference stream closures in respective HTTP docs . 
 How about this ? 
 I do n't understand the sentence structure here : When ... , if ... , then . Why is there a when and an if with a comma ? May this should be : When ... and if ... , then ? Sorry if that is grammatically correct but it really confuses me what the sentence is supposed to say ... P.S. : clarifying the term " terminates cleanly " is also a good idea though . 
 We could rephrase as How does that sound ? 
 Yes , that works for me . Thanks ! 
 LGTM modulo nit
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.
If the receive side of a stream carrying capsules is terminated
cleanly (for example, in HTTP/3 this is defined as receiving a QUIC
STREAM frame with the FIN bit set) and the last capsule on the stream
was truncated, this MUST be treated as a malformed or incomplete
message.