Changeset 1863 for draft-ietf-httpbis/latest/p1-messaging.xml

Timestamp:

Sep 4, 2012, 1:58:08 AM (7 years ago)

Author:

fielding@…

Message:

Rewrite the persistent connection and Upgrade requirements to be
actionable by role and consistent with the rest of HTTP.

File:

• draft-ietf-httpbis/latest/p1-messaging.xml (modified) (20 diffs)

draft-ietf-httpbis/latest/p1-messaging.xml

@@ -1267 +1267 @@
 </t>
 <t anchor="rule.BWS">
-   BWS is used where the grammar allows optional whitespace for historical
-   reasons but senders &SHOULD-NOT; produce it in messages. HTTP/1.1
+   BWS is used where the grammar allows optional whitespace, for historical
+   reasons, but senders &SHOULD-NOT; produce it in messages;
    recipients &MUST; accept such bad optional whitespace and remove it before
    interpreting the field value or forwarding the message downstream.
@@ -1356 +1356 @@
   <x:anchor-alias value="special"/>
   <x:anchor-alias value="word"/>
-   Many HTTP/1.1 header field values consist of words (token or quoted-string)
+   Many HTTP header field values consist of words (token or quoted-string)
    separated by whitespace or special characters. These special characters
    &MUST; be in a quoted string to be used within a parameter value (as defined
@@ -1741 +1741 @@
    Request messages that are prematurely terminated, possibly due to a
    canceled connection or a server-imposed time-out exception, &MUST;
-   result in closure of the connection; sending an HTTP/1.1 error response
+   result in closure of the connection; sending an error response
    prior to closing the connection is &OPTIONAL;.
 </t>
@@ -1841 +1841 @@
 </artwork></figure>
 <t>
-   All transfer-coding values are case-insensitive.
-   The HTTP Transfer Coding registry is defined in
+   All transfer-coding values are case-insensitive and &SHOULD; be registered
+   within the HTTP Transfer Coding registry, as defined in
    <xref target="transfer.coding.registry"/>.
-   HTTP/1.1 uses transfer-coding values in the <x:ref>TE</x:ref> header field
-   (<xref target="header.te"/>) and in the <x:ref>Transfer-Encoding</x:ref>
-   header field (<xref target="header.transfer-encoding"/>).
+   They are used in the <x:ref>TE</x:ref> (<xref target="header.te"/>) and
+   <x:ref>Transfer-Encoding</x:ref> (<xref target="header.transfer-encoding"/>)
+   header fields.
 </t>
 
@@ -1980 +1980 @@
 </artwork></figure>
 <t>
-   All HTTP/1.1 applications &MUST; be able to receive and decode the
+   All recipients &MUST; be able to receive and decode the
    "chunked" transfer-coding and &MUST; ignore chunk-ext extensions
    they do not understand.
@@ -2324 +2324 @@
 </t>
 <t>
-   When an HTTP/1.1 proxy receives a request with an absolute-form of
+   When a proxy receives a request with an absolute-form of
    request-target, the proxy &MUST; ignore the received
    Host header field (if any) and instead replace it with the host
@@ -2678 +2678 @@
   <iref primary="true" item="Connection header field" x:for-anchor=""/>
   <iref primary="true" item="Header Fields" subitem="Connection" x:for-anchor=""/>
+  <iref primary="true" item="close" x:for-anchor=""/>
   <x:anchor-alias value="Connection"/>
   <x:anchor-alias value="connection-option"/>
@@ -2715 +2716 @@
 </artwork></figure>
 <t>
-   Connection options are compared case-insensitively.
+   Connection options are case-insensitive.
 </t>
 <t>
@@ -2747 +2748 @@
 </t>
 <t>
-   HTTP/1.1 defines the "<x:dfn>close</x:dfn>" connection option for the
+   The "<x:dfn>close</x:dfn>" connection option is defined for a
    sender to signal that this connection will be closed after completion of
    the response. For example,
@@ -2757 +2758 @@
    in either the request or the response header fields indicates that
    the connection &SHOULD; be closed after the current request/response
-   is complete (<xref target="persistent.connections"/>).
-</t>
-<t>
-   An HTTP/1.1 client that does not support persistent connections &MUST;
-   include the "close" connection option in every request message.
-</t>
-<t>
-   An HTTP/1.1 server that does not support persistent connections &MUST;
-   include the "close" connection option in every response message that
+   is complete (<xref target="persistent.tear-down"/>).
+</t>
+<t>
+   A client that does not support persistent connections &MUST;
+   send the "close" connection option in every request message.
+</t>
+<t>
+   A server that does not support persistent connections &MUST;
+   send the "close" connection option in every response message that
    does not have a <x:ref>1xx (Informational)</x:ref> status code.
 </t>
@@ -2827 +2828 @@
 <section title="Establishment" anchor="persistent.establishment">
 <t>
+   It is beyond the scope of this specification to describe how connections
+   are established via various transport or session-layer protocols.
    Each connection applies to only one transport link.
 </t>
 <t>
-   An HTTP/1.1 server &MAY; assume that a HTTP/1.1 client intends to
-   maintain a persistent connection unless a <x:ref>Connection</x:ref> header
-   field including the connection option "close" was sent in the request.
-</t>
-<t>
-   An HTTP/1.1 client &MAY; expect a connection to remain open, but would
-   decide to keep it open based on whether the response from a server
-   contains a <x:ref>Connection</x:ref> header field with the connection option
-   "close".
-</t>
-<t>
-   Clients and servers &SHOULD-NOT;  assume that a persistent connection is
-   maintained for HTTP versions less than 1.1 unless it is explicitly
-   signaled. See <xref target="compatibility.with.http.1.0.persistent.connections"/> for more information on backward
-   compatibility with HTTP/1.0 clients.
-</t>
-<t>
-   A proxy server &MUST-NOT; establish a HTTP/1.1 persistent connection
-   with an HTTP/1.0 client (but see <xref x:sec="19.7.1" x:fmt="of" target="RFC2068"/>
-   for information and discussion of the problems with the Keep-Alive header field
+   A recipient determines whether a connection is persistent or not based on
+   the most recently received message's protocol version and
+   <x:ref>Connection</x:ref> header field (if any):
+   <list style="symbols">
+     <t>If the <x:ref>close</x:ref> connection option is present, the
+        connection will not persist after the current response; else,</t>
+     <t>If the received protocol is HTTP/1.1 (or later), the connection will
+        persist after the current response; else,</t>
+     <t>If the received protocol is HTTP/1.0, the "keep-alive"
+        connection option is present, the recipient is not a proxy, and
+        the recipient wishes to honor the HTTP/1.0 "keep-alive" mechanism,
+        the connection will persist after the current response; otherwise,</t>
+     <t>The connection will close after the current response.</t>
+   </list>
+</t>
+<t>
+   A proxy server &MUST-NOT; maintain a persistent connection with an
+   HTTP/1.0 client (see <xref x:sec="19.7.1" x:fmt="of" target="RFC2068"/> for
+   information and discussion of the problems with the Keep-Alive header field
    implemented by many HTTP/1.0 clients).
 </t>
@@ -2856 +2858 @@
 <section title="Reuse" anchor="persistent.reuse">
 <t>
-   Unless otherwise indicated, the client
-   &SHOULD; assume that the server will maintain a persistent connection,
-   even after error responses from the server.
-</t>
-<t>
-   In order to remain persistent, all messages on the connection &MUST;
+   In order to remain persistent, all messages on a connection &MUST;
    have a self-defined message length (i.e., one not defined by closure
    of the connection), as described in <xref target="message.body"/>.
+</t>
+<t>
+   A server &MAY; assume that an HTTP/1.1 client intends to maintain a
+   persistent connection until a <x:ref>close</x:ref> connection option
+   is received in a request.
+</t>
+<t>
+   A client &MAY; reuse a persistent connection until it sends or receives
+   a <x:ref>close</x:ref> connection option or receives an HTTP/1.0 response
+   without a "keep-alive" connection option.
+</t>
+<t>
+   Clients and servers &SHOULD-NOT; assume that a persistent connection is
+   maintained for HTTP versions less than 1.1 unless it is explicitly
+   signaled.
+   See <xref target="compatibility.with.http.1.0.persistent.connections"/>
+   for more information on backward compatibility with HTTP/1.0 clients.
 </t>
 
@@ -2911 +2925 @@
 <section title="Concurrency" anchor="persistent.concurrency">
 <t>
-   Clients (including proxies) &SHOULD; limit the number of simultaneous
-   connections that they maintain to a given server (including proxies).
+   Clients &SHOULD; limit the number of simultaneous
+   connections that they maintain to a given server.
 </t>
 <t>
@@ -2922 +2936 @@
 </t>
 <t>
-   In particular, while using multiple connections avoids the "head-of-line
-   blocking" problem (whereby a request that takes significant server-side
-   processing and/or has a large payload can block subsequent requests on the
-   same connection), each connection used consumes server resources (sometimes
-   significantly), and furthermore using multiple connections can cause
-   undesirable side effects in congested networks. 
+   Multiple connections are typically used to avoid the "head-of-line
+   blocking" problem, wherein a request that takes significant server-side
+   processing and/or has a large payload blocks subsequent requests on the
+   same connection. However, each connection consumes server resources.
+   Furthermore, using multiple connections can cause undesirable side effects
+   in congested networks. 
 </t>
 <t>
@@ -2961 +2975 @@
 </t>
 <t>
-   HTTP/1.1 servers &SHOULD; maintain persistent connections and use TCP's
-   flow control mechanisms to resolve temporary overloads, rather than
-   terminating connections with the expectation that clients will retry.
+   Servers &SHOULD; maintain persistent connections and allow the underlying
+   transport's flow control mechanisms to resolve temporary overloads, rather
+   than terminate connections with the expectation that clients will retry.
    The latter technique can exacerbate network congestion.
 </t>
 <t>
-   An HTTP/1.1 (or later) client sending a message body &SHOULD; monitor
+   A client sending a message body &SHOULD; monitor
    the network connection for an error status code while it is transmitting
    the request. If the client sees an error status code, it &SHOULD;
@@ -2975 +2989 @@
    
 <section title="Tear-down" anchor="persistent.tear-down">
-<t>
-   Persistent connections provide a mechanism by which a client and a
-   server can signal the close of a TCP connection. This signaling takes
-   place using the <x:ref>Connection</x:ref> header field
-   (<xref target="header.connection"/>). Once a close has been signaled, the
-   client &MUST-NOT; send any more requests on that
-   connection.
-</t>
-<t>
-   If either the client or the server sends the "close" option in the
-   <x:ref>Connection</x:ref> header field, that request/response pair
-   becomes the last one for the connection.
-</t>
-<t>
-   If the server chooses to close the connection immediately after sending the
-   response, it &SHOULD; send a Connection header field including the
-   connection option "close".
-</t>
-<t>
-   In case the client does not want to maintain a connection for more
-   than that request, it &SHOULD; send a Connection header field including the
-   connection option "close".
-</t>
-<t>
-   If the client is sending data, a server implementation using TCP
-   &SHOULD; be careful to ensure that the client acknowledges receipt of
-   the packet(s) containing the response, before the server closes the
-   input connection. If the client continues sending data to the server
-   after the close, the server's TCP stack will send a reset packet to
-   the client, which might erase the client's unacknowledged input buffers
-   before they can be read and interpreted by the HTTP application.
+  <iref primary="false" item="Connection header field" x:for-anchor=""/>
+  <iref primary="false" item="close" x:for-anchor=""/>
+<t>
+   The <x:ref>Connection</x:ref> header field
+   (<xref target="header.connection"/>) provides a "<x:ref>close</x:ref>"
+   connection option that a sender &SHOULD; send when it wishes to close
+   the connection after the current request/response pair.
+</t>
+<t>
+   A client that sends a <x:ref>close</x:ref> connection option &MUST-NOT;
+   send further requests on that connection (after the one containing
+   <x:ref>close</x:ref>) and &MUST; close the connection after reading the
+   final response message corresponding to this request.
+</t>
+<t>
+   A server that receives a <x:ref>close</x:ref> connection option &MUST;
+   initiate a lingering close of the connection after it sends the final
+   response to the request that contained <x:ref>close</x:ref>.
+   The server &SHOULD; include a <x:ref>close</x:ref> connection option
+   in its final response on that connection. The server &MUST-NOT; process
+   any further requests received on that connection.
+</t>
+<t>
+   A server that sends a <x:ref>close</x:ref> connection option &MUST;
+   initiate a lingering close of the connection after it sends the
+   response containing <x:ref>close</x:ref>. The server &MUST-NOT; process
+   any further requests received on that connection.
+</t>
+<t>
+   A client that receives a <x:ref>close</x:ref> connection option &MUST;
+   cease sending requests on that connection and close the connection
+   after reading the response message containing the close; if additional
+   pipelined requests had been sent on the connection, the client &SHOULD;
+   assume that they will not be processed by the server.
+</t>
+<t>
+   If a server performs an immediate close of a TCP connection, there is a
+   significant risk that the client will not be able to read the last HTTP
+   response.  If the server receives additional data from the client on a
+   fully-closed connection, such as another request that was sent by the
+   client before receiving the server's response, the server's TCP stack will
+   send a reset packet to the client; unfortunately, the reset packet might
+   erase the client's unacknowledged input buffers before they can be read
+   and interpreted by the client's HTTP parser.
+</t>
+<t>
+   To avoid the TCP reset problem, a server can perform a lingering close on a
+   connection by closing only the write side of the read/write connection
+   (a half-close) and continuing to read from the connection until the
+   connection is closed by the client or the server is reasonably certain
+   that its own TCP stack has received the client's acknowledgement of the
+   packet(s) containing the server's last response. It is then safe for the
+   server to fully close the connection.
+</t>
+<t>
+   It is unknown whether the reset problem is exclusive to TCP or might also
+   be found in other transport connection protocols.
 </t>
 </section>
@@ -3018 +3058 @@
   <x:anchor-alias value="protocol-version"/>
 <t>
-   The "Upgrade" header field allows the client to specify what
-   additional communication protocols it would like to use, if the server 
-   chooses to switch protocols. Servers can use it to indicate what protocols
-   they are willing to switch to.
+   The "Upgrade" header field is intended to provide a simple mechanism
+   for transitioning from HTTP/1.1 to some other protocol on the same
+   connection.  A client &MAY; send a list of protocols in the Upgrade
+   header field of a request to invite the server to switch to one or
+   more of those protocols before sending the final response.
+   A server &MUST; send an Upgrade header field in <x:ref>101 (Switching
+   Protocols)</x:ref> responses to indicate which protocol(s) are being
+   switched to, and &MUST; send it in <x:ref>426 (Upgrade Required)</x:ref>
+   responses to indicate acceptable protocols.
+   A server &MAY; send an Upgrade header field in any other response to
+   indicate that they might be willing to upgrade to one of the
+   specified protocols for a future request.
 </t>
 <figure><artwork type="abnf2616"><iref primary="true" item="Grammar" subitem="Upgrade"/>
@@ -3037 +3085 @@
 </artwork></figure>
 <t>
-   The Upgrade header field is intended to provide a simple mechanism
-   for transitioning from HTTP/1.1 to some other, incompatible protocol. It
-   does so by allowing the client to advertise its desire to use another
-   protocol, such as a later version of HTTP with a higher major version
-   number, even though the current request has been made using HTTP/1.1.
-   This eases the difficult transition between incompatible protocols by
+   Upgrade eases the difficult transition between incompatible protocols by
    allowing the client to initiate a request in the more commonly
    supported protocol while indicating to the server that it would like
@@ -3050 +3093 @@
 </t>
 <t>
-   The Upgrade header field only applies to switching application-layer
-   protocols upon the existing transport-layer connection. Upgrade
-   cannot be used to insist on a protocol change; its acceptance and use
-   by the server is optional. The capabilities and nature of the
+   Upgrade cannot be used to insist on a protocol change; its acceptance and
+   use by the server is optional. The capabilities and nature of the
    application-layer communication after the protocol change is entirely
    dependent upon the new protocol chosen, although the first action
    after changing the protocol &MUST; be a response to the initial HTTP
-   request containing the Upgrade header field.
-</t>
-<t>
-   The Upgrade header field only applies to the immediate connection.
-   Therefore, the upgrade keyword &MUST; be supplied within a
+   request that contained the Upgrade header field.
+</t>
+<t>
+   For example, if the Upgrade header field is received in a GET request
+   and the server decides to switch protocols, then it &MUST; first respond
+   with a <x:ref>101 (Switching Protocols)</x:ref> message in HTTP/1.1 and
+   then immediately follow that with the new protocol's equivalent of a
+   response to a GET on the target resource.  This allows a connection to be
+   upgraded to protocols with the same semantics as HTTP without the
+   latency cost of an additional round-trip.  A server &MUST-NOT; switch
+   protocols unless the received message semantics can be honored by the new
+   protocol; an OPTIONS request can be honored by any protocol.
+</t>
+<t>
+   When Upgrade is sent, a sender &MUST; also send a 
    <x:ref>Connection</x:ref> header field (<xref target="header.connection"/>)
-   whenever Upgrade is present in an HTTP/1.1 message.
-</t>
-<t>
-   The Upgrade header field cannot be used to indicate a switch to a
-   protocol on a different connection. For that purpose, it is more
-   appropriate to use a <x:ref>3xx (Redirection)</x:ref> response (&status-3xx;).
-</t>
-<t>
-   Servers &MUST; include the "Upgrade" header field in <x:ref>101 (Switching
-   Protocols)</x:ref> responses to indicate which protocol(s) are being switched to,
-   and &MUST; include it in <x:ref>426 (Upgrade Required)</x:ref> responses to indicate
-   acceptable protocols to upgrade to. Servers &MAY; include it in any other
-   response to indicate that they are willing to upgrade to one of the
-   specified protocols.
+   that contains the "upgrade" connection option, in order to prevent Upgrade
+   from being accidentally forwarded by intermediaries that might not implement
+   the listed protocols.  A server &MUST; ignore an Upgrade header field that
+   is received in an HTTP/1.0 request.
+</t>
+<t>
+   The Upgrade header field only applies to switching application-layer
+   protocols on the existing transport-layer connection; it cannot be used
+   to switch to a protocol on a different connection. For that purpose, it is
+   more appropriate to use a <x:ref>3xx (Redirection)</x:ref> response
+   (&status-3xx;).
 </t>
 <t>
@@ -3086 +3134 @@
 </t>
 </section>
-
 </section>