jiebi/ids-paragraph-commentary-corpus huggingface dataset:
Draft: draft-ietf-masque-connect-udp

Commentary: This was prompted by . 
 LGTM . Nice and tight .
There exist software and network deployments that perform access
control checks based on the source IP address of incoming requests.
For example, some software allows unauthenticated configuration
changes if they originated from 127.0.0.1.  Such software could be
running on the same host as the UDP proxy, or in the same broadcast
domain.  Proxied UDP traffic would then be received with a source IP
address belonging to the UDP proxy.  If this source address is used
for access control, UDP proxying clients could use the UDP proxy to
escalate their access privileges beyond those they might otherwise
have.  This could lead to unauthorized access by UDP proxying clients
unless the UDP proxy disallows UDP proxying requests to vulnerable
targets, such as localhost names and addresses, link-local addresses,
the UDP proxy's own addresses, multicast and broadcast addresses.
UDP proxies can use the destination_ip_prohibited Proxy Error Type
from PROXY-STATUS when rejecting such requests.
The security considerations described in HTTP-DGRAM also apply here.
The security considerations described in HTTP-DGRAM also apply here.
Since it is possible to tunnel IP packets over UDP, the guidance in
TUNNEL-SECURITY can apply.
Draft: draft-ietf-masque-connect-udp

Commentary: This PR addresses the DISCUSS component of . The COMMENT component of that review will be addressed in a subsequent PR . 
 LGTMNice catch , thanks Zahed
A UDP proxying request that does not conform to these restrictions is
malformed.  The recipient of such a malformed request MUST respond
with an error, and SHOULD use the 400 (Bad Request) status code.
Draft: draft-ietf-masque-connect-udp

Commentary: This PR is in response to . It improves the clarity of the Security Considerations section : the paragraph about willingness to receive needed an introductory sentence the paragraph about lifetimes no longer made sense and is removed 
 Look fine to me , posted some suggested editoiral tweaks you can take or leave
UDP proxies have similar properties to TCP proxies when it comes to
facilitating denial of service attacks.  In theory the stateful
nature of TCP provides better protection than stateless UDP but in
practice this provides negligible benefits when considering proxying.
UDP sockets for UDP proxying have a different lifetime than TCP
sockets for CONNECT, therefore implementors would be well served to
follow the advice in handling if they base their UDP proxying
implementation on a preexisting implementation of CONNECT.
Draft: draft-ietf-masque-connect-udp

Commentary: Thanks  !
If the client detects that 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 UDP proxy.  While clients
SHOULD validate the requirements above, some clients MAY use a
general-purpose URI Template implementation that lacks this specific
validation.
Clients SHOULD validate the requirements above; however, clients MAY
use a general-purpose URI Template implementation that lacks this
specific validation.  If a client detects that 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 UDP proxy.
UDP proxies SHOULD strive to avoid increasing burstiness of UDP
traffic: they SHOULD NOT queue packets in order to increase batching.
Bursty traffic can often lead to temporally correlated packet losses,
which in turn can lead to suboptimal responses from congestion
controllers in protocols running over UDP.  To avoid this, UDP
proxies SHOULD strive to avoid increasing burstiness of UDP traffic:
they SHOULD NOT queue packets in order to increase batching.
Draft: draft-ietf-masque-connect-udp

Commentary: PR in response to Al 's OPSDIR review --
Clients MAY optimistically start sending UDP packets in HTTP
Datagrams before receiving the response to its UDP proxying request.
However, implementors should note that such proxied packets may not
be processed by the UDP proxy if it responds to the request with a
failure, or if the proxied packets are received by the UDP proxy
before the request.
If a UDP proxy receives an HTTP Datagram before it has received the
corresponding request, it SHALL either drop that HTTP Datagram
silently or buffer it temporarily (on the order of a round trip)
while awaiting the corresponding request.
Note that buffering datagrams (either because the request was not yet
received, or because the Context ID is not yet known) consumes
resources.  Receivers that buffer datagrams SHOULD apply buffering
limits in order to reduce the risk of resource exhaustion occuring.
For example, receivers can limit the total number of buffered
datagrams, or the cumulative size of buffered datagrams, on a per-
stream, per-context, or per-connection basis.
A client MAY optimistically start sending UDP packets in HTTP
Datagrams before receiving the response to its UDP proxying request.
However, implementors should note that such proxied packets may not
be processed by the UDP proxy if it responds to the request with a
failure, or if the proxied packets are received by the UDP proxy
before the request and the UDP proxy chooses to not buffer them.
Draft: draft-ietf-masque-connect-udp

Commentary: Nit from the AD review . Reading this sentence , it took me a moment to figure out if we were talking about config on the client or the on the proxy .
Since the original HTTP CONNECT method allowed conveying the target
host and port but not the scheme, proxy authority, path, nor query,
there exist proxy configuration interfaces that only allow the user
to configure the proxy host and the proxy port.  Client
implementations of this specification that are constrained by such
limitations MAY attempt to access UDP proxying capabilities using the
default template, which is defined as:
"https://$PROXY_HOST:$PROXY_PORT/.well-known/masque/
udp/{target_host}/{target_port}/" where $PROXY_HOST and $PROXY_PORT
are the configured host and port of the UDP proxy respectively.  UDP
proxy deployments SHOULD offer service at this location if they need
to interoperate with such clients.
Since the original HTTP CONNECT method allowed conveying the target
host and port but not the scheme, proxy authority, path, nor query,
there exist clients with proxy configuration interfaces that only
allow the user to configure the proxy host and the proxy port.
Client implementations of this specification that are constrained by
such limitations MAY attempt to access UDP proxying capabilities
using the default template, which is defined as:
"https://$PROXY_HOST:$PROXY_PORT/.well-known/masque/
udp/{target_host}/{target_port}/" where $PROXY_HOST and $PROXY_PORT
are the configured host and port of the UDP proxy respectively.  UDP
proxy deployments SHOULD offer service at this location if they need
to interoperate with such clients.
Draft: draft-ietf-masque-connect-udp

Commentary: From AD Review : Expand the acronym and add a ( normative ! ) reference . 
 I 'm going to mark this editorial since it 's just clarifying what ECN is , and I do n't believe we 've had any confusion on that point among working group members . 
 The second commit explicitly mentions the TCP ECN feedback mechanism , for completeness . And yes , this is editorial .
If a client or UDP proxy with a connection containing a UDP proxying
request stream disables congestion control, it MUST NOT signal ECN
support on that connection.  That is, it MUST mark all IP headers
with the Not-ECT codepoint.  It MAY continue to report ECN feedback
via ACK_ECN frames, as the peer may not have disabled congestion
control.
If a client or UDP proxy with a connection containing a UDP proxying
request stream disables congestion control, it MUST NOT signal
Explicit Congestion Notification (ECN) ECN support on that
connection.  That is, it MUST mark all IP headers with the Not-ECT
codepoint.  It MAY continue to report ECN feedback via QUIC ACK_ECN
frames or the TCP "ECE" bit, as the peer may not have disabled
congestion control.
Draft: draft-ietf-masque-connect-udp

Commentary: Looking at the changes in the document I think I have picked up on another potential issue . Due to the discussion in I have to ask what happens if the client issues an Connect request over HTTP/2 that is then changed into an HTTP/1.1 request by an intermediate HTTP proxy in front of the actual MASQUE server . I do n’t think this issue is discussed and what a MASQUE server does if it gets a CONNECT request with an Connect - UDP upgrade header . 
 In that scenario , the client will send : and the intermediary converting from HTTP/2 to HTTP/1.1 will convert that to : That works as expected . Are you saying there 's a problem here ? 
 Probably worth a mention in this spec , like CONNECT already does , that a proxy can forward CONNECT - UDP requests to a proxy it has configured . I do n't think much more detail is required than that . Such a proxy needs to follow the normative requirements set out else where . Concerns about converting requests between HTTP versions are common and not terribly unique here . 
 That sounds like a worthwhile clarification . Tagging as editorial . 
 LGTM , parity with HTTP without compromising existing tone / style
Upon receiving a UDP proxying request, the recipient UDP proxy
extracts the "target_host" and "target_port" variables from the URI
it has reconstructed from the request headers, and establishes a
tunnel by directly opening a UDP socket to the requested target.
if the recipient is configured to use another HTTP proxy, it will
act as an intermediary: it forwards the request to another HTTP
server.  Note that such intermediaries may need to reencode the
request if they forward it using a version of HTTP that is
different from the one used to receive it, as the request encoding
differs by version (see below).
otherwise, the recipient will act as a UDP proxy: it extracts the
"target_host" and "target_port" variables from the URI it has
reconstructed from the request headers, and establishes a tunnel
by directly opening a UDP socket to the requested target.
Draft: draft-ietf-masque-connect-udp

Commentary: Is this strictly necessary ? 
 You 're right , it 's unnecessary and does n't add anything . Removing via .
the request-target SHALL use absolute-form (see H1).
Draft: draft-ietf-masque-connect-udp

Commentary: Try as we might , we ca n't retroactively place this requirement on the countless deployed caches on the Internet . Given that at least over HTTP/1.1 this mechanism uses GET , it might be better to specify that the GET response needs the appropriate   . 
 Good catch . That particular text came from back when we only used CONNECT , as that 's defined as non - cacheable . Since defining how to cache Upgrade sounds like dragons holding footguns , I 'm just going to remove this text via . That way we rely on existing HTTP documents to properly define how caching works .
Responses to UDP proxying requests are not cacheable.
Draft: draft-ietf-masque-connect-udp

Commentary: The client configuration section says : ... but the examples contain : Which is it ? 
 This was an accident , I suspect it dates back to when the document referred to which contains both path and query . Fixing to mention both path and query via .
All template variables MUST be within the path component of the
URI.
All template variables MUST be within the path or query components
of the URI.
Draft: draft-ietf-masque-connect-udp

Commentary: " connect - udp " . " Single " implies that this mechanism is incompatible with any other upgrade mechanisms . If that 's actually the case , it might be good to state so explicitly , rather than rely on this single word . 
 Thanks for catching this oversight . Similar to , this was not the intent . Fixing via .
the request SHALL include a single "Upgrade" header field with
value "connect-udp".
the request SHALL include an "Upgrade" header field with value
"connect-udp".
Draft: draft-ietf-masque-connect-udp

Commentary: " Upgrade " ( note that this requirement is case - insensitive as per { { Section 7.6.1 of HTTP } } ) . " Single " implies that there ca n't be other values ( at least in other header lines , and possibly this one ) . That 's an inappropriate constraint . 
 Thanks for catching this oversight , fixing via .
the request SHALL include a single "Connection" header field with
value "Upgrade" (note that this requirement is case-insensitive as
per HTTP).
the request SHALL include a "Connection" header field with value
"Upgrade" (note that this requirement is case-insensitive as per
HTTP).
Draft: draft-ietf-masque-connect-udp

Commentary: Given that this draft is couched in terms of , the use of in HTTP/1.1 is surprising . At the least , a reason should be mentioned . 
 Closing for now , as I have more serious concerns that may make this OBE . 
 Reopening .
In HTTP/1.1, this protocol uses the GET method to mimic the design of
the WebSocket Protocol WEBSOCKET.
Draft: draft-ietf-masque-connect-udp

Commentary: Section 3 " connect - udp " uses the Capsule Protocol as defined in [ HTTP - DGRAM ] . What does " uses " here mean ? As there are situations where the Capsule Protocol and the Datagram Capsule defined in HTTP - DGRAM is not required to be used , it is not clear if it MUST be implemented and MAY be used ? 
 It would be better to link specifically to associated request 's data stream uses the Capsule Protocol . If they do so , that means that the contents of the associated request 's data stream uses the following format ... 
 and possibly forward ref to https://ietf - wg- 
 And that might be clearer , assuming that the implementation requirement is clear in those section of the HTTP datagram spec .
This document defines the "connect-udp" HTTP Upgrade Token. "connect-
udp" uses the Capsule Protocol as defined in HTTP-DGRAM.
This document defines the "connect-udp" HTTP Upgrade Token. "connect-
udp" uses the Capsule Protocol as defined in HTTP-DGRAM.  The format
of HTTP Datagrams is defined in format.
Draft: draft-ietf-masque-connect-udp

Commentary: 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 , has volunteered to become Area Director . 
 I have been volunteered many times by other people , I do n't think this one will change anything
Unlike TCP, UDP is connection-less.  The proxy that opens the UDP
socket has no way of knowing whether the destination is reachable.
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
request.  If DNS resolution fails, the proxy MUST fail the request
and SHOULD send details using the Proxy-Status header field PROXY-
STATUS.
Unlike TCP, UDP is connection-less.  The proxy that opens the UDP
socket has no way of knowing whether the destination is reachable.
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
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.
Draft: draft-ietf-masque-connect-udp

Commentary: In section 5 in this sentence the term " proxied UDP packets " is used the only time and might not be clear : How about to just say " UDP packets in HTTP datagrams " ? 
 +1 good improvement
Clients MAY optimistically start sending proxied UDP packets before
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.
Clients MAY optimistically start sending UDP packets in HTTP
Datagrams before 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.
Draft: draft-ietf-masque-connect-udp

Commentary: 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 .
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.
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.
Draft: draft-ietf-masque-connect-udp

Commentary: This is a long sentence that mixes singular and plural terms , for different concepts . I think this needs some editing to improve readability .
Clients MAY optimistically start sending proxied UDP packets before
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.
Clients MAY optimistically start sending proxied UDP packets before
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.
Draft: draft-ietf-masque-connect-udp

Commentary: 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 limit MUST apply . I.e. this would be calculated by looking at the  's length value and subtracting the encoded length of the Context ID field . ( or whatever the answer is , in case I got it wrong )
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
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
incoming DATAGRAM capsules using Context ID zero whose payload is
longer than that limit without buffering the capsule contents.
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
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
incoming DATAGRAM capsules using Context ID zero whose Payload field
is longer than that limit without buffering the capsule contents.
Draft: draft-ietf-masque-connect-udp

Commentary: All of these should apply here , does n't hurt to remind people . Especially the bit in the other spec that says  , it is not accessible from Web Platform APIs ( such as those commonly accessed via JavaScript in web browsers ) .
The security considerations described in HTTP-DGRAM also apply here.
Draft: draft-ietf-masque-connect-udp

Commentary: People shout at me for doing this , so I 'm paying it forward . Perhaps you could move the SHOULD requirement to a statement in Section 3 , so that it covers all forms of the CONNECT - UDP request .
There are significant risks in allowing arbitrary clients to
establish a tunnel to arbitrary targets, as that could allow bad
actors to send traffic and have it attributed to the proxy.  Proxies
that support UDP proxying SHOULD restrict its use to authenticated
users.
There are significant risks in allowing arbitrary clients to
establish a tunnel to arbitrary targets, as that could allow bad
actors to send traffic and have it attributed to the proxy.  Proxies
that support UDP proxying ought to restrict its use to authenticated
users.
Draft: draft-ietf-masque-connect-udp

Commentary: 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 "
Registration is the action by which an endpoint informs its peer of
the semantics and format of a given context ID.  This document does
not define how registration occurs.  Future extensions MAY use HTTP
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
reordering of the datagram and the registration packets during
transmission.
Registration is the action by which an endpoint informs its peer of
the semantics and format of a given context ID.  This document does
not define how registration occurs.  Future extensions MAY use HTTP
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
reordering of the packet containing the datagram and the packet
containing the registration message during transmission.