Merge pull request #3340 from httpwg/incremental-ad

Mike's AD review

Author: kazuho

draft-ietf-httpbis-incremental.md

@@ -82,9 +82,14 @@ an intermediary that tries to buffer entire messages --
 either request or response -- prevents any data from being delivered.
 
 To help avoid such behavior, this document specifies the "Incremental" HTTP header
-field, which instructs HTTP intermediaries to begin forwarding the HTTP message
+field, which requests that HTTP intermediaries begin forwarding the HTTP message
 downstream before receiving the complete message.
 
+This indication is advisory.
+Intermediaries that are unaware of this field will not change their behavior.
+intermediaries that support the field might choose instead to reject a request;
+see {{security}}.
+
 
 # Conventions and Definitions
 
@@ -136,7 +141,7 @@ sections of the message before forwarding them downstream.
 If an intermediary decides outright to refuse forwarding the message body
 incrementally, the intermediary MUST generate an error response rather than
 buffering an entire message before forwarding. Typical scenarios under which an
-intermediary might refuse are discussed in {{security-considerations}}.
+intermediary might refuse are discussed in {{security}}.
 
 The request to use incremental forwarding also applies to HTTP implementations.
 Though most HTTP APIs provide the ability to incrementally transfer message content,
@@ -151,8 +156,8 @@ incrementally. Clients can rely on prior knowledge or probe for support on
 individual resources.
 
 The Incremental header field facilitates the establishment of a bidirectional
-byte channel over HTTP, as its presence in both requests and responses instructs
-intermediaries to forward early responses ({{Section 7.5 of HTTP}}) and to
+byte channel over HTTP, as its presence in both requests and responses requests that
+intermediaries forward early responses ({{Section 7.5 of HTTP}}) and to
 transmit message contents incrementally in both directions.  However, when developing
 bidirectional protocols over HTTP, Extended CONNECT {{?RFC8441}}{{?RFC9220}} is
 generally more consistent with HTTP's architecture.
@@ -162,12 +167,15 @@ value, but future documents might define parameters. Receivers MUST ignore
 unknown parameters.
 
 
-# Security Considerations
+# Security Considerations {#security}
 
 When receiving a request or response that asks for incremental forwarding,
-intermediaries might reject the request due to security concerns. The following
-subsections explore typical scenarios under which the intermediaries might
-reject requests.
+intermediaries might reject the HTTP request due to security concerns.
+The following subsections explore typical scenarios
+under which the intermediaries might reject requests.
+
+Note that rejecting requests based on the value of the Incremental field
+only occurs when an intermediary understands the field.
 
 
 ## Permanent Rejection
@@ -238,7 +246,7 @@ Reference:
 
 Comments:
 : None
-{: spacing="compact"}
+{:compact}
 
 An HTTP Proxy Error Type is registered in the HTTP Proxy Error Types registry as
 shown below:
@@ -261,6 +269,7 @@ Response Only Generated By Intermediaries:
 
 Reference:
 : This document
+{:compact}
 
 --- back