Ignore:
Timestamp:
21/05/13 22:00:59 (10 years ago)
Author:
fielding@…
Message:

addresses #446 p1 editorial feedback

File:
1 edited

Legend:

Unmodified
Added
Removed

  • draft-ietf-httpbis/latest/p1-messaging.html

    r2269 r2270  
    855855         or provide adequate warning for security or privacy options. In the few cases where this specification requires reporting
    856856         of errors to the user, it is acceptable for such reporting to only be observable in an error console or log file. Likewise,
    857          requirements that an automated action be confirmed by the user before proceeding can be met via advance configuration choices,
    858          run-time options, or simply not proceeding with the unsafe action.
     857         requirements that an automated action be confirmed by the user before proceeding might be met via advance configuration choices,
     858         run-time options, or simple avoidance of the unsafe action; confirmation does not imply any specific user interface or interruption
     859         of normal processing if the user has already made that choice.
    859860      </p>
    860861      <div id="rfc.iref.i.1"></div>
    … …  
    872873         the chain. Although the diagram is linear, each participant might be engaged in multiple, simultaneous communications. For
    873874         example, B might be receiving requests from many clients other than A, and/or forwarding requests to servers other than C,
    874          at the same time that it is handling A's request.
     875         at the same time that it is handling A's request. Likewise, later requests might be sent through a different path of connections,
     876         often based on dynamic configuration for load balancing.
    875877      </p>
    876878      <p id="rfc.section.2.3.p.4"> <span id="rfc.iref.u.2"></span><span id="rfc.iref.d.1"></span>  <span id="rfc.iref.i.2"></span><span id="rfc.iref.o.2"></span> We use the terms "<dfn>upstream</dfn>" and "<dfn>downstream</dfn>" to describe various requirements in relation to the directional flow of a message: all messages flow from upstream to downstream.
    … …  
    891893         a given message, we use the term "<dfn>non-transforming proxy</dfn>" to target requirements that preserve HTTP message semantics. See <a href="p2-semantics.html#status.203" title="203 Non-Authoritative Information">Section 6.3.4</a> of <a href="#Part2" id="rfc.xref.Part2.3"><cite title="Hypertext Transfer Protocol (HTTP/1.1): Semantics and Content">[Part2]</cite></a> and <a href="p6-cache.html#header.warning" title="Warning">Section 7.5</a> of <a href="#Part6" id="rfc.xref.Part6.2"><cite title="Hypertext Transfer Protocol (HTTP/1.1): Caching">[Part6]</cite></a> for status and warning codes related to transformations.
    892894      </p>
    893       <p id="rfc.section.2.3.p.7"><span id="rfc.iref.g.13"></span><span id="rfc.iref.r.4"></span>  <span id="rfc.iref.a.1"></span> A "<dfn>gateway</dfn>" (a.k.a., "<dfn>reverse proxy</dfn>") is a receiving agent that acts as a layer above some other server(s) and translates the received requests to the underlying
    894          server's protocol. Gateways are often used to encapsulate legacy or untrusted information services, to improve server performance
    895          through "<dfn>accelerator</dfn>" caching, and to enable partitioning or load-balancing of HTTP services across multiple machines.
    896       </p>
    897       <p id="rfc.section.2.3.p.8">A gateway behaves as an origin server on its outbound connection and as a user agent on its inbound connection. All HTTP requirements
    898          applicable to an origin server also apply to the outbound communication of a gateway. A gateway communicates with inbound
    899          servers using any protocol that it desires, including private extensions to HTTP that are outside the scope of this specification.
    900          However, an HTTP-to-HTTP gateway that wishes to interoperate with third-party HTTP servers <em class="bcp14">MUST</em> conform to HTTP user agent requirements on the gateway's inbound connection and <em class="bcp14">MUST</em> implement the <a href="#header.connection" class="smpl">Connection</a> (<a href="#header.connection" id="rfc.xref.header.connection.1" title="Connection">Section&nbsp;6.1</a>) and <a href="#header.via" class="smpl">Via</a> (<a href="#header.via" id="rfc.xref.header.via.1" title="Via">Section&nbsp;5.7.1</a>) header fields for both connections.
     895      <p id="rfc.section.2.3.p.7"><span id="rfc.iref.g.13"></span><span id="rfc.iref.r.4"></span>  <span id="rfc.iref.a.1"></span> A "<dfn>gateway</dfn>" (a.k.a., "<dfn>reverse proxy</dfn>") is an intermediary that acts as an origin server for the outbound connection, but translates received requests and forwards
     896         them inbound to another server or servers. Gateways are often used to encapsulate legacy or untrusted information services,
     897         to improve server performance through "<dfn>accelerator</dfn>" caching, and to enable partitioning or load balancing of HTTP services across multiple machines.
     898      </p>
     899      <p id="rfc.section.2.3.p.8">All HTTP requirements applicable to an origin server also apply to the outbound communication of a gateway. A gateway communicates
     900         with inbound servers using any protocol that it desires, including private extensions to HTTP that are outside the scope of
     901         this specification. However, an HTTP-to-HTTP gateway that wishes to interoperate with third-party HTTP servers <em class="bcp14">MUST</em> conform to HTTP user agent requirements on the gateway's inbound connection and <em class="bcp14">MUST</em> implement the <a href="#header.connection" class="smpl">Connection</a> (<a href="#header.connection" id="rfc.xref.header.connection.1" title="Connection">Section&nbsp;6.1</a>) and <a href="#header.via" class="smpl">Via</a> (<a href="#header.via" id="rfc.xref.header.via.1" title="Via">Section&nbsp;5.7.1</a>) header fields for both inbound and outbound connections.
    901902      </p>
    902903      <p id="rfc.section.2.3.p.9"><span id="rfc.iref.t.2"></span> A "<dfn>tunnel</dfn>" acts as a blind relay between two connections without changing the messages. Once active, a tunnel is not considered a party
    … …  
    16691670  TE: trailers, deflate;q=0.5
    16701671</pre><p id="rfc.section.4.3.p.6">The presence of the keyword "trailers" indicates that the client is willing to accept trailer fields in a chunked transfer
    1671          coding, as defined in <a href="#chunked.encoding" title="Chunked Transfer Coding">Section&nbsp;4.1</a>, on behalf of itself and any downstream clients. For chained requests, this implies that either: (a) all downstream clients
    1672          are willing to accept trailer fields in the forwarded response; or, (b) the client will attempt to buffer the response on
    1673          behalf of downstream recipients. Note that HTTP/1.1 does not define any means to limit the size of a chunked response such
    1674          that a client can be assured of buffering the entire response.
     1672         coding, as defined in <a href="#chunked.encoding" title="Chunked Transfer Coding">Section&nbsp;4.1</a>, on behalf of itself and any downstream clients. For requests from an intermediary, this implies that either: (a) all downstream
     1673         clients are willing to accept trailer fields in the forwarded response; or, (b) the intermediary will attempt to buffer the
     1674         response on behalf of downstream recipients. Note that HTTP/1.1 does not define any means to limit the size of a chunked response
     1675         such that an intermediary can be assured of buffering the entire response.
    16751676      </p>
    16761677      <p id="rfc.section.4.3.p.7">When multiple transfer codings are acceptable, the client <em class="bcp14">MAY</em> rank the codings by preference using a case-insensitive "q" parameter (similar to the qvalues used in content negotiation
    … …  
    17031704         semantics and, if so, where that request is to be directed.
    17041705      </p>
    1705       <p id="rfc.section.5.2.p.2">If the client has a response cache and the request semantics can be satisfied by a cache (<a href="#Part6" id="rfc.xref.Part6.5"><cite title="Hypertext Transfer Protocol (HTTP/1.1): Caching">[Part6]</cite></a>), then the request is usually directed to the cache first.
     1706      <p id="rfc.section.5.2.p.2">If the client has a cache <a href="#Part6" id="rfc.xref.Part6.5"><cite title="Hypertext Transfer Protocol (HTTP/1.1): Caching">[Part6]</cite></a> and the request can be satisfied by it, then the request is usually directed there first.
    17061707      </p>
    17071708      <p id="rfc.section.5.2.p.3">If the request is not satisfied by a cache, then a typical client will check its configuration to determine whether a proxy
    … …  
    19221923         selected representation. A proxy <em class="bcp14">MAY</em> change the message body through application or removal of a transfer coding (<a href="#transfer.codings" title="Transfer Codings">Section&nbsp;4</a>).
    19231924      </p>
    1924       <p id="rfc.section.5.7.2.p.5">A non-transforming proxy <em class="bcp14">MUST</em> preserve the message payload (<a href="p2-semantics.html#payload" title="Payload Semantics">Section 3.3</a> of <a href="#Part2" id="rfc.xref.Part2.22"><cite title="Hypertext Transfer Protocol (HTTP/1.1): Semantics and Content">[Part2]</cite></a>). A transforming proxy <em class="bcp14">MUST</em> preserve the payload of a message that contains the no-transform cache-control directive.
     1925      <p id="rfc.section.5.7.2.p.5">A non-transforming proxy <em class="bcp14">MUST NOT</em> modify the message payload (<a href="p2-semantics.html#payload" title="Payload Semantics">Section 3.3</a> of <a href="#Part2" id="rfc.xref.Part2.22"><cite title="Hypertext Transfer Protocol (HTTP/1.1): Semantics and Content">[Part2]</cite></a>). A transforming proxy <em class="bcp14">MUST NOT</em> modify the payload of a message that contains the no-transform cache-control directive.
    19251926      </p>
    19261927      <p id="rfc.section.5.7.2.p.6">A transforming proxy <em class="bcp14">MAY</em> transform the payload of a message that does not contain the no-transform cache-control directive; if the payload is transformed,
    … …  
    21152116  <a href="#header.upgrade" class="smpl">protocol-name</a>    = <a href="#rule.token.separators" class="smpl">token</a>
    21162117  <a href="#header.upgrade" class="smpl">protocol-version</a> = <a href="#rule.token.separators" class="smpl">token</a>
    2117 </pre><p id="rfc.section.6.7.p.3">For example,</p>
    2118       <div id="rfc.figure.u.58"></div><pre class="text">  Upgrade: HTTP/2.0, SHTTP/1.3, IRC/6.9, RTA/x11
    2119 </pre><p id="rfc.section.6.7.p.5">Upgrade eases the difficult transition between incompatible protocols by allowing the client to initiate a request in the
     2118</pre><div id="rfc.figure.u.58"></div>
     2119      <p>The following is a hypothetical example sent by a client:</p><pre class="text2">GET /hello.txt HTTP/1.1
     2120Host: www.example.com
     2121Connection: upgrade
     2122Upgrade: HTTP/2.0, SHTTP/1.3, IRC/6.9, RTA/x11
     2123
     2124</pre><p id="rfc.section.6.7.p.4">Upgrade eases the difficult transition between incompatible protocols by allowing the client to initiate a request in the
    21202125         more commonly supported protocol while indicating to the server that it would like to use a "better" protocol if available
    21212126         (where "better" is determined by the server, possibly according to the nature of the request method or target resource).
    21222127      </p>
    2123       <p id="rfc.section.6.7.p.6">Upgrade cannot be used to insist on a protocol change; its acceptance and use by the server is optional. The capabilities
     2128      <p id="rfc.section.6.7.p.5">Upgrade cannot be used to insist on a protocol change; its acceptance and use by the server is optional. The capabilities
    21242129         and nature of the application-level communication after the protocol change is entirely dependent upon the new protocol chosen,
    21252130         although the first action after changing the protocol <em class="bcp14">MUST</em> be a response to the initial HTTP request that contained the Upgrade header field.
    21262131      </p>
    2127       <p id="rfc.section.6.7.p.7">For example, if the Upgrade header field is received in a GET request and the server decides to switch protocols, then it
     2132      <p id="rfc.section.6.7.p.6">For example, if the Upgrade header field is received in a GET request and the server decides to switch protocols, then it
    21282133         first responds with a <a href="p2-semantics.html#status.101" class="smpl">101 (Switching Protocols)</a> message in HTTP/1.1 and then immediately follows that with the new protocol's equivalent of a response to a GET on the target
    21292134         resource. This allows a connection to be upgraded to protocols with the same semantics as HTTP without the latency cost of
    … …  
    21312136         by any protocol.
    21322137      </p>
    2133       <p id="rfc.section.6.7.p.8">When Upgrade is sent, a sender <em class="bcp14">MUST</em> also send a <a href="#header.connection" class="smpl">Connection</a> header field (<a href="#header.connection" id="rfc.xref.header.connection.7" title="Connection">Section&nbsp;6.1</a>) that contains the "upgrade" connection option, in order to prevent Upgrade from being accidentally forwarded by intermediaries
     2138      <div id="rfc.figure.u.59"></div>
     2139      <p>The following is an example response to the above hypothetical request:</p><pre class="text">HTTP/1.1 101 Switching Protocols
     2140Connection: upgrade
     2141Upgrade: HTTP/2.0
     2142
     2143[... data stream switches to HTTP/2.0 with an appropriate response
     2144(as defined by new protocol) to the "GET /hello.txt" request ...]
     2145</pre><p id="rfc.section.6.7.p.8">When Upgrade is sent, a sender <em class="bcp14">MUST</em> also send a <a href="#header.connection" class="smpl">Connection</a> header field (<a href="#header.connection" id="rfc.xref.header.connection.7" title="Connection">Section&nbsp;6.1</a>) that contains the "upgrade" connection option, in order to prevent Upgrade from being accidentally forwarded by intermediaries
    21342146         that might not implement the listed protocols. A server <em class="bcp14">MUST</em> ignore an Upgrade header field that is received in an HTTP/1.0 request.
    21352147      </p>
    … …  
    25282540         that most implementations will choose substantially higher limits.
    25292541      </p>
    2530       <p id="rfc.section.8.3.p.3">This specification also provides a way for servers to reject messages that have request-targets that are too long (<a href="p2-semantics.html#status.414" title="414 URI Too Long">Section 6.5.12</a> of <a href="#Part2" id="rfc.xref.Part2.28"><cite title="Hypertext Transfer Protocol (HTTP/1.1): Semantics and Content">[Part2]</cite></a>) or request entities that are too large (<a href="p2-semantics.html#status.4xx" title="Client Error 4xx">Section 6.5</a> of <a href="#Part2" id="rfc.xref.Part2.29"><cite title="Hypertext Transfer Protocol (HTTP/1.1): Semantics and Content">[Part2]</cite></a>).
     2542      <p id="rfc.section.8.3.p.3">This specification also provides a way for servers to reject messages that have request-targets that are too long (<a href="p2-semantics.html#status.414" title="414 URI Too Long">Section 6.5.12</a> of <a href="#Part2" id="rfc.xref.Part2.28"><cite title="Hypertext Transfer Protocol (HTTP/1.1): Semantics and Content">[Part2]</cite></a>) or request entities that are too large (<a href="p2-semantics.html#status.4xx" title="Client Error 4xx">Section 6.5</a> of <a href="#Part2" id="rfc.xref.Part2.29"><cite title="Hypertext Transfer Protocol (HTTP/1.1): Semantics and Content">[Part2]</cite></a>). Additional status codes related to capacity limits have been defined by extensions to HTTP <a href="#RFC6585" id="rfc.xref.RFC6585.1"><cite title="Additional HTTP Status Codes">[RFC6585]</cite></a>.
    25312543      </p>
    25322544      <p id="rfc.section.8.3.p.4">Recipients <em class="bcp14">SHOULD</em> carefully limit the extent to which they read other fields, including (but not limited to) request methods, response status
    … …  
    27842796            </td>
    27852797         </tr>
     2798         <tr>
     2799            <td class="reference"><b id="RFC6585">[RFC6585]</b></td>
     2800            <td class="top">Nottingham, M. and R. Fielding, “<a href="http://tools.ietf.org/html/rfc6585">Additional HTTP Status Codes</a>”, RFC&nbsp;6585, April&nbsp;2012.
     2801            </td>
     2802         </tr>
    27862803      </table>
    27872804      <div class="avoidbreak">
    … …  
    29392956         indicating at least &lt;n&gt; and at most &lt;m&gt; elements, each separated by a single comma (",") and optional whitespace (OWS).
    29402957      </p>
    2941       <div id="rfc.figure.u.59"></div>
     2958      <div id="rfc.figure.u.60"></div>
    29422959      <p>Thus,</p><pre class="text">  1#element =&gt; element *( OWS "," OWS element )
    2943 </pre><div id="rfc.figure.u.60"></div>
     2960</pre><div id="rfc.figure.u.61"></div>
    29442961      <p>and:</p><pre class="text">  #element =&gt; [ 1#element ]
    2945 </pre><div id="rfc.figure.u.61"></div>
     2962</pre><div id="rfc.figure.u.62"></div>
    29462963      <p>and for n &gt;= 1 and m &gt; 1:</p><pre class="text">  &lt;n&gt;#&lt;m&gt;element =&gt; element &lt;n-1&gt;*&lt;m-1&gt;( OWS "," OWS element )
    29472964</pre><p id="rfc.section.B.p.6">For compatibility with legacy list rules, recipients <em class="bcp14">SHOULD</em> accept empty list elements. In other words, consumers would follow the list productions:
    29482965      </p>
    2949       <div id="rfc.figure.u.62"></div><pre class="text">  #element =&gt; [ ( "," / element ) *( OWS "," [ OWS element ] ) ]
     2966      <div id="rfc.figure.u.63"></div><pre class="text">  #element =&gt; [ ( "," / element ) *( OWS "," [ OWS element ] ) ]
    29502967 
    29512968  1#element =&gt; *( "," OWS ) element *( OWS "," [ OWS element ] )
    29522969</pre><p id="rfc.section.B.p.8">Note that empty elements do not contribute to the count of elements present, though.</p>
    29532970      <p id="rfc.section.B.p.9">For example, given these ABNF productions:</p>
    2954       <div id="rfc.figure.u.63"></div><pre class="text">  example-list      = 1#example-list-elmt
     2971      <div id="rfc.figure.u.64"></div><pre class="text">  example-list      = 1#example-list-elmt
    29552972  example-list-elmt = token ; see <a href="#field.components" title="Field value components">Section&nbsp;3.2.6</a>
    29562973</pre><p id="rfc.section.B.p.11">Then these are valid values for example-list (not including the double quotes, which are present for delimitation only):</p>
    2957       <div id="rfc.figure.u.64"></div><pre class="text">  "foo,bar"
     2974      <div id="rfc.figure.u.65"></div><pre class="text">  "foo,bar"
    29582975  "foo ,bar,"
    29592976  "foo , ,bar,charlie   "
    29602977</pre><p id="rfc.section.B.p.13">But these values would be invalid, as at least one non-empty element is required:</p>
    2961       <div id="rfc.figure.u.65"></div><pre class="text">  ""
     2978      <div id="rfc.figure.u.66"></div><pre class="text">  ""
    29622979  ","
    29632980  ",   ,"
    … …  
    29652982      </p>
    29662983      <h1 id="rfc.section.C"><a href="#rfc.section.C">C.</a>&nbsp;<a id="collected.abnf" href="#collected.abnf">Collected ABNF</a></h1>
    2967       <div id="rfc.figure.u.66"></div><pre class="inline"><a href="#rule.whitespace" class="smpl">BWS</a> = OWS
     2984      <div id="rfc.figure.u.67"></div><pre class="inline"><a href="#rule.whitespace" class="smpl">BWS</a> = OWS
    29682985
    29692986<a href="#header.connection" class="smpl">Connection</a> = *( "," OWS ) connection-option *( OWS "," [ OWS
    … …  
    34423459                  </li>
    34433460                  <li><em>RFC6265</em>&nbsp;&nbsp;<a href="#rfc.xref.RFC6265.1">2.7.2</a>, <a href="#rfc.xref.RFC6265.2">3.2.2</a>, <a href="#RFC6265"><b>10.2</b></a></li>
     3461                  <li><em>RFC6585</em>&nbsp;&nbsp;<a href="#rfc.xref.RFC6585.1">8.3</a>, <a href="#RFC6585"><b>10.2</b></a></li>
    34443462               </ul>
    34453463            </li>
Note: See TracChangeset for help on using the changeset viewer.