jiebi/TextFlow huggingface dataset:
Original text:
optionally indicate a preference for which address it would get assigned. <del> The ADDRESS_REQUEST capsule contains a sequence of zero or more </del>  Requested Addresses. If the IP Address is all-zero (0.0.0.0 or ::), this indicates that requested address, and that it can also assign some requested addresses but not others.  4.6.3. The ROUTE_ADVERTISEMENT capsule (see iana-types for the value of the End IP Address of A MUST be strictly less than the Start IP Address of B. <del> If an endpoint received a ROUTE_ADVERTISEMENT capsule that does not </del>  meet these requirements, it MUST abort the IP proxying request stream.

Reviewer comments:
"The ADDRESS_REQUEST capsule contains a sequence of zero or more Requested Addresses." In cases there are zero Requested Addresses what does this mean? It appears that this is an even less determined form than the all zero block , that at least indicates an address family support or preference as well as prefix length by including one or two all-zero address of the families the endpoint want assigned? Should this be explicitly stated?

Revised text:
optionally indicate a preference for which address it would get assigned.  <ins> The ADDRESS_REQUEST capsule contains a sequence of one or more </ins> Requested Addresses. If the IP Address is all-zero (0.0.0.0 or ::), this indicates that requested address, and that it can also assign some requested addresses but not others. <ins> If an endpoint receives an ADDRESS_REQUEST capsule that contains zero Requested Addresses, it MUST abort the IP proxying request stream. </ins> 4.6.3. The ROUTE_ADVERTISEMENT capsule (see iana-types for the value of the End IP Address of A MUST be strictly less than the Start IP Address of B.  <ins> If an endpoint receives a ROUTE_ADVERTISEMENT capsule that does not </ins> meet these requirements, it MUST abort the IP proxying request stream.
Original text:
"target" and "ipproto" variables MUST adhere to the format in target- format, using notation from ABNF.  Additionally: <del> if "target" contains an IPv6 literal, the colons (":") MUST be percent-encoded.  For example, if the target host is </del>  "2001:db8::42", it will be encoded in the URI as "2001%3Adb8%3A%3A42".

Reviewer comments:
So the description of target says: The variable "target" contains a hostname or IP prefix of a specific host to which the client wants to proxy packets. If the "target" variable is not specified or its value is "", the client is requesting to communicate with any allowable host. "target" supports using DNS names, IPv6 literals and IPv4 literals. Further down the the ABNF is stating: target = IPv6prefix / IPv4prefix / reg-name / "" IPv6prefix = IPv6address ["%2F" 13DIGIT] IPv4prefix = IPv4address ["%2F" 12DIGIT] ipproto = 13DIGIT / "" Thus, the text is inconsistent where the first indicates hostnames and prefixes. Second indicates hostnames (as DNS names) and IPv4/6 Literals, but not prefixes. Then the ABNF indicates Prefixes and reg-name. So if it is only the prefix construct and hostnames then the text about literals directly needs to be addressed. If it is hostnames, IPvX literals, and IPprefix the ABNF and description need to be addressed.
I think you misread the ABNF? It allows hostnames and IP prefixes, that's what the is for. Also those brackets indicate optionality of the prefix.
I think the ABNF is fine. It's the text that once talks about IP prefixes and once about IP literals.
Ah! Thank you, will fix via PR

Revised text:
"target" and "ipproto" variables MUST adhere to the format in target- format, using notation from ABNF.  Additionally:  <ins> if "target" contains an IPv6 literal or prefix, the colons (":") MUST be percent-encoded.  For example, if the target host is </ins> "2001:db8::42", it will be encoded in the URI as "2001%3Adb8%3A%3A42".
Original text:
This document describes how to proxy UDP over HTTP.  Similar to how the CONNECT method allows proxying TCP over HTTP, this document <del> defines a new mechanism to proxy UDP.  It is built using HTTP Extended CONNECT. </del>  1.

Reviewer comments:
That omits the HTTP/1.1 support that you have. Is that intentional?
You're right that should be fixed - the intro is correct but the abstract needs to be updated to look more like the corresponding text in the into

Revised text:
This document describes how to proxy UDP over HTTP.  Similar to how the CONNECT method allows proxying TCP over HTTP, this document  <ins> defines a new mechanism to proxy UDP.  When using HTTP/2 or HTTP/3, it uses Extended CONNECT; when using HTTP/1.1, it uses Upgrade. </ins> 1.
Original text:
capitals, as shown here. In this document, we use the term "proxy" to refer to the HTTP server <del> that opens the UDP socket and responds to the UDP proxying request. If there are HTTP intermediaries (as defined in HTTP) between the client and the proxy, those are referred to as "intermediaries" in this document. </del>  Note that, when the HTTP version in use does not support multiplexing streams (such as HTTP/1.1), any reference to "stream" in this

Reviewer comments:
In the notational conventions Some might argue an HTTP/3 server already opend a UDP socket :-) so you might want to tighten this a bit to say something like In this document, we use the term "proxy" to refer to the HTTP server that acts upon the client request to open a UDP socket to a target server, and generates the response to this request.

Revised text:
capitals, as shown here. In this document, we use the term "proxy" to refer to the HTTP server  <ins> that acts upon the client's UDP proxying request to open a UDP socket to a target server, and generates the response to this request.  If there are HTTP intermediaries (as defined in HTTP) between the client and the proxy, those are referred to as "intermediaries" in this document. </ins> Note that, when the HTTP version in use does not support multiplexing streams (such as HTTP/1.1), any reference to "stream" in this
Original text:
encoding, so for example if the target_host is "2001:db8::42", it will be encoded in the URI as "2001%3Adb8%3A%3A42". <del> A payload within a UDP proxying request message has no defined semantics; a UDP proxying request with a non-empty payload is malformed. </del>  Responses to UDP proxying requests are not cacheable.

Reviewer comments:
"A payload within a UDP proxying request message has no defined semantics; a UDP proxying request with a non-empty payload is malformed." "payload" here I assume is HTTP message content?
Already discussed in and fixed in
... or "message content" There's a lot of uses of UDP payload that do not qualify here. The one example I can see that would benefit from a change is please check if there are any other cases though.

Revised text:
encoding, so for example if the target_host is "2001:db8::42", it will be encoded in the URI as "2001%3Adb8%3A%3A42".  <ins> By virtue of the definition of the Capsule Protocol (see HTTP-DGRAM), UDP proxying requests do not carry any message content.  Similarly, successful UDP proxying responses also do not carry any message content. </ins> Responses to UDP proxying requests are not cacheable.
Original text:
the origin of the proxy. the request SHALL include a single "Connection" header field with <del> value "Upgrade". </del>  the request SHALL include a single "Upgrade" header field with value "connect-udp". Protocols). the reponse SHALL include a single "Connection" header field with <del> value "Upgrade". </del>  the response SHALL include a single "Upgrade" header field with value "connect-udp".

Reviewer comments:
This is really about case-sensitivity. The Connection header field value is case-insensitive - URL The requirement is uppercase but example uses lowercase. Without citing or mentioning the case sensitivity, readers might be confused, and pedants might complain

Revised text:
the origin of the proxy. the request SHALL include a single "Connection" header field with  <ins> value "Upgrade" (note that this requirement is case-insensitive as per HTTP). </ins> the request SHALL include a single "Upgrade" header field with value "connect-udp". Protocols). the reponse SHALL include a single "Connection" header field with  <ins> value "Upgrade" (note that this requirement is case-insensitive as per HTTP). </ins> the response SHALL include a single "Upgrade" header field with value "connect-udp".
Original text:
3.4. <del> When using HTTP/2 H2 or HTTP/3 H3, UDP proxying requests use HTTP pseudo-header fields with the following requirements: </del>  The ":method" pseudo-header field SHALL be "CONNECT".

Reviewer comments:
It's mentioned in the abstract and intro but I think it would be useful to remind people that there are prerequisites required to use extended CONNECT in the section that details the specific requirements.

Revised text:
3.4.  <ins> When using HTTP/2 H2 or HTTP/3 H3, UDP proxying requests use Extended CONNECT.  This requires that servers send an HTTP Setting as specified in EXT-CONNECT2 and EXT-CONNECT3, and that requests use HTTP pseudo-header fields with the following requirements: </ins> The ":method" pseudo-header field SHALL be "CONNECT".
Original text:
IDs are client-allocated, and odd-numbered context IDs are proxy- allocated.  The context ID namespace is tied to a given HTTP request: it is possible for a context ID with the same numeric value to be <del> simultaneously assigned different semantics in distinct requests, potentially with different semantics.  Context IDs MUST NOT be re- allocated within a given HTTP namespace but MAY be allocated in any order.  Once allocated, any context ID can be used by both client and proxy - only allocation carries separate namespaces to avoid requiring synchronization. </del>  Registration is the action by which an endpoint informs its peer of the semantics and format of a given context ID.  This document does

Reviewer comments:
I'm having trouble grokking this, is the mention of "different semantics" duplicate text or is it meant to apply to different things?

Revised text:
IDs are client-allocated, and odd-numbered context IDs are proxy- allocated.  The context ID namespace is tied to a given HTTP request: it is possible for a context ID with the same numeric value to be  <ins> simultaneously allocated in distinct requests, potentially with different semantics.  Context IDs MUST NOT be re-allocated within a given HTTP namespace but MAY be allocated in any order.  Once allocated, any context ID can be used by both client and proxy - only allocation carries separate namespaces to avoid requiring synchronization. </ins> Registration is the action by which an endpoint informs its peer of the semantics and format of a given context ID.  This document does
Original text:
header fields or capsules to register contexts.  Depending on the method being used, it is possible for datagrams to be received with Context IDs which have not yet been registered, for instance due to <del> reordering of the datagram and the registration packets during transmission. </del>  5.

Reviewer comments:
There's a danger people read too much into "datagram packets" or "registration packets". I think it would be clearer to say something like "due to reordering of packets that contain datagrams or registration messages"

Revised text:
header fields or capsules to register contexts.  Depending on the method being used, it is possible for datagrams to be received with Context IDs which have not yet been registered, for instance due to  <ins> reordering of the packet containing the datagram and the packet containing the registration message during transmission. </ins> 5.
Original text:
However, in practice denial of service attacks target open TCP ports so the TCP SYN-ACK does not offer much protection in real scenarios.  8. 8.1.

Reviewer comments:
All of these should apply here, doesn't hurt to remind people. Especially the bit in the other spec that says Tokens, it is not accessible from Web Platform APIs (such as those commonly accessed via JavaScript in web browsers).

Revised text:
However, in practice denial of service attacks target open TCP ports so the TCP SYN-ACK does not offer much protection in real scenarios. <ins> The security considerations described in HTTP-DGRAM also apply here. </ins> 8. 8.1.
Original text:
request with a failure, or if the datagrams are received by the proxy before the request. <del> Endpoints MUST NOT send HTTP Datagrams with payloads longer than 65527 using Context ID zero.  An endpoint that receives a DATAGRAM capsule using Context ID zero whose payload is longer than 65527 MUST </del>  abort the stream.  If a proxy knows it can only send out UDP packets of a certain length due to its underlying link MTU, it SHOULD discard <del> incoming DATAGRAM capsules using Context ID zero whose payload is longer than that limit without buffering the capsule contents. </del>  6.

Reviewer comments:
The last paragraph of section 5, considers payload length There's a small chance for confusion here, because the DATAGRAM capsule format has a field and has a field. Consider therefore explicitly illustrating the maths that is required to determine the payload for which your 65527 limit MUST apply. I.e. this would be calculated by looking at the Capsule's length value and subtracting the encoded length of the Context ID field. (or whatever the answer is, in case I got it wrong)

Revised text:
request with a failure, or if the datagrams are received by the proxy before the request.  <ins> By virtue of the definition of the UDP header UDP, it is not possible to encode UDP payloads longer than 65527 bytes.  Therefore, endpoints MUST NOT send HTTP Datagrams with a Payload field longer than 65527 using Context ID zero.  An endpoint that receives a DATAGRAM capsule using Context ID zero whose Payload field is longer than 65527 MUST </ins> abort the stream.  If a proxy knows it can only send out UDP packets of a certain length due to its underlying link MTU, it SHOULD discard  <ins> incoming DATAGRAM capsules using Context ID zero whose Payload field is longer than that limit without buffering the capsule contents. </ins> 6.
Original text:
octets" in UDP). Clients MAY optimistically start sending proxied UDP packets before <del> receiving the response to its UDP proxying request, noting however that those may not be processed by the proxy if it responds to the request with a failure, or if the datagrams are received by the proxy before the request. </del>  By virtue of the definition of the UDP header UDP, it is not possible to encode UDP payloads longer than 65527 bytes.  Therefore, endpoints

Reviewer comments:
This is a long sentence that mixes singular and plural terms, for different concepts. I think this needs some editing to improve readability.

Revised text:
octets" in UDP). Clients MAY optimistically start sending proxied UDP packets before  <ins> receiving the response to its UDP proxying request.  However, implementors should note that such proxied packets may not be processed by the proxy if it responds to the request with a failure, or if the proxied packets are received by the proxy before the request. </ins> By virtue of the definition of the UDP header UDP, it is not possible to encode UDP payloads longer than 65527 bytes.  Therefore, endpoints
Original text:
Template TEMPLATE with the variables "target_host" and "target_port". Examples are shown below: <del> The URI Template MUST be a level 3 template or lower.  The URI Template MUST be in absolute form, and MUST include non-empty scheme, authority and path components.  The path component of the URI Template MUST start with a slash "/".  All template variables MUST be within the path component of the URI.  The URI template MUST contain the two variables "target_host" and "target_port" and MAY contain other variables.  The URI Template MUST NOT contain any non-ASCII unicode characters and MUST only contain ASCII characters in the range 0x21-0x7E inclusive (note that percent-encoding is allowed). The URI Template MUST NOT use Reserved Expansion ("+" operator), Fragment Expansion ("#" operator), Label Expansion with Dot-Prefix, Path Segment Expansion with Slash-Prefix, nor Path-Style Parameter Expansion with Semicolon-Prefix.  If any of the requirements above are not met by a URI Template, the client MUST reject its configuration and fail the request without sending it to the proxy. </del>  Since the original HTTP CONNECT method allowed conveying the target host and port but not the scheme, proxy authority, path, nor query,

Reviewer comments:
This single paragraph has ~150 words and about 10 normative requirements of the MUST / MUST NOT variety. Personally I find this quite a dense presentation of information. But I'll leave it up to your editorial discretion to fix or not.

Revised text:
Template TEMPLATE with the variables "target_host" and "target_port". Examples are shown below:  <ins> The following requirements apply to the URI Template: The URI Template MUST be a level 3 template or lower. The URI Template MUST be in absolute form, and MUST include non- empty scheme, authority and path components. The path component of the URI Template MUST start with a slash "/". All template variables MUST be within the path component of the URI. The URI template MUST contain the two variables "target_host" and "target_port" and MAY contain other variables. The URI Template MUST NOT contain any non-ASCII unicode characters and MUST only contain ASCII characters in the range 0x21-0x7E inclusive (note that percent-encoding is allowed). The URI Template MUST NOT use Reserved Expansion ("+" operator), Fragment Expansion ("#" operator), Label Expansion with Dot- Prefix, Path Segment Expansion with Slash-Prefix, nor Path-Style Parameter Expansion with Semicolon-Prefix. If any of the requirements above are not met by a URI Template, the client MUST reject its configuration and fail the request without sending it to the proxy. </ins> Since the original HTTP CONNECT method allowed conveying the target host and port but not the scheme, proxy authority, path, nor query,
Original text:
it is possible for a context ID with the same numeric value to be simultaneously allocated in distinct requests, potentially with different semantics.  Context IDs MUST NOT be re-allocated within a <del> given HTTP namespace but MAY be allocated in any order.  Once allocated, any context ID can be used by both client and proxy - only allocation carries separate namespaces to avoid requiring synchronization. </del>  Registration is the action by which an endpoint informs its peer of the semantics and format of a given context ID.  This document does

Reviewer comments:
Section 4, second paragrap: 'The context ID namespace is tied to a given HTTP request: it is possible for a context ID with the same numeric value to be simultaneously assigned different semantics in distinct requests, potentially with different semantics. Context IDs MUST NOT be re-allocated within a given HTTP namespace but MAY be allocated in any order.' I found this text initially confusing. I think what I was missing initially was a reminder that the HTTP datagram will be either in the communication context of the HTTP Request (HTTP 1.x) or the HTTP datagram will contain the quarter stream ID, and thus be in context. So an potential improvement here would be to add a clarification before this to remind that HTTP datagram will always be in context of a given HTTP request.
Fixed by
Section 4 last sentence 2 paragraph is: Why is there a "-"? Actually not sure what the second is supposed to say. Is there anything missing?
The dash has meaning similar to parentheses: it is equivalent to (see ). This parenthetical clause adds context to the main clause: allocation is separate but usage is not.
Do you have a suggestion for text that would be better?
I find the use of namespace in the quoted text unhelpful. You might editorialize this sentence a bit anyway to improve the clarity. Something like "Context ID allocation depends on restrictions to the use of even- and odd-numbered context IDs in order to avoid the need for synchronisation. However, once a context has been allocated, those restrictions no longer apply and context IDs can be used by any client or proxy, independent of who initially allocated them.
Lucas thanks that's much better! (I think this "allocation carries" wording confused me a bit)
:shipit:

Revised text:
it is possible for a context ID with the same numeric value to be simultaneously allocated in distinct requests, potentially with different semantics.  Context IDs MUST NOT be re-allocated within a  <ins> given HTTP namespace but MAY be allocated in any order.  The context ID allocation restrictions to the use of even-numbered and odd- numbered context IDs exist in order to avoid the need for synchronisation between endpoints.  However, once a context ID has been allocated, those restrictions do not apply to the use of the context ID: it can be used by any client or proxy, independent of which endpoint initially allocated it. </ins> Registration is the action by which an endpoint informs its peer of the semantics and format of a given context ID.  This document does
Original text:
5. <del> When associated with UDP proxying request streams, the HTTP Datagram Payload field of HTTP Datagrams (see HTTP-DGRAM) has the format </del>  defined in dgram-format.  Note that when HTTP Datagrams are encoded using QUIC DATAGRAM frames, the Context ID field defined below directly follows the Quarter Stream ID field which is at the start of

Reviewer comments:
I had to read the first sentence multiple time to parse it: When associated with UDP proxying request streams, the HTTP Datagram Payload field of HTTP Datagrams (see [HTTP-DGRAM]) has the format defined in [Figure 6]. I think turning the sentence around would make it slightly easier tor read: The HTTP Datagram Payload field of HTTP Datagrams (see [HTTP-DGRAM]) has the format defined in [Figure 6], when associated with streams of UDP proxying requests.
I think I find it easier to read the other way around
Or split the difference
that works too. I also found the term "UDP proxying request streams" a bit clumsy. but the new sentence works much better. Thanks!

Revised text:
5.  <ins> When HTTP Datagrams (see HTTP-DGRAM) are associated with UDP proxying request streams, the HTTP Datagram Payload field has the format </ins> defined in dgram-format.  Note that when HTTP Datagrams are encoded using QUIC DATAGRAM frames, the Context ID field defined below directly follows the Quarter Stream ID field which is at the start of
Original text:
Therefore it needs to respond to the request without waiting for a packet from the target.  However, if the target_host is a DNS name, the proxy MUST perform DNS resolution before replying to the HTTP <del> request.  If DNS resolution fails, the proxy MUST fail the request and SHOULD send details using the Proxy-Status header field PROXY- STATUS. </del>  Proxies can use connected UDP sockets if their operating system supports them, as that allows the proxy to rely on the kernel to only

Reviewer comments:
Section 3.1 mentions proxy handling requirements and notes a DNS failure SHOULD be communicated in the response using Proxy-Status. Is that the only case? Maybe it's worth mentioning that the header can be used for any other type of failure too.
It's linked to a SHOULD requirement
Fair enough. Let it be known that by this issue, NAME has volunteered to become Area Director.
I have been volunteered many times by other people, I don't think this one will change anything

Revised text:
Therefore it needs to respond to the request without waiting for a packet from the target.  However, if the target_host is a DNS name, the proxy MUST perform DNS resolution before replying to the HTTP  <ins> request.  If errors occur during this process (for example, a DNS resolution failure), the proxy MUST fail the request and SHOULD send details using the Proxy-Status header field PROXY-STATUS. </ins> Proxies can use connected UDP sockets if their operating system supports them, as that allows the proxy to rely on the kernel to only