Changeset 2274 for draft-ietf-httpbis/latest

Timestamp:

25/05/13 06:55:38 (7 years ago)

Author:

fielding@…

Message:

Define ordering for Upgrade; addresses #445

Location:

draft-ietf-httpbis/latest

Files:

• p1-messaging.html (modified) (4 diffs)
• p1-messaging.xml (modified) (6 diffs)

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

@@ -2106 +2106 @@
       <h2 id="rfc.section.6.7"><a href="#rfc.section.6.7">6.7</a>&nbsp;<a id="header.upgrade" href="#header.upgrade">Upgrade</a></h2>
       <p id="rfc.section.6.7.p.1">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 <em class="bcp14">MAY</em> 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 <em class="bcp14">MUST</em> send an Upgrade header field in <a href="p2-semantics.html#status.101" class="smpl">101 (Switching
-            Protocols)</a> responses to indicate which protocol(s) are being switched to, and <em class="bcp14">MUST</em> send it in <a href="p2-semantics.html#status.426" class="smpl">426 (Upgrade Required)</a> responses to indicate acceptable protocols. A server <em class="bcp14">MAY</em> 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.
+         on the same connection. A client <em class="bcp14">MAY</em> 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,
+         in order of descending preference, before sending the final response. A server <em class="bcp14">MAY</em> ignore a received Upgrade header field if it wishes to continue using the current protocol on that connection.
       </p>
       <div id="rfc.figure.u.57"></div><pre class="inline"><span id="rfc.iref.g.94"></span>  <a href="#header.upgrade" class="smpl">Upgrade</a>          = 1#<a href="#header.upgrade" class="smpl">protocol</a>
@@ -2116 +2114 @@
   <a href="#header.upgrade" class="smpl">protocol-name</a>    = <a href="#rule.token.separators" class="smpl">token</a>
   <a href="#header.upgrade" class="smpl">protocol-version</a> = <a href="#rule.token.separators" class="smpl">token</a>
-</pre><div id="rfc.figure.u.58"></div>
+</pre><p id="rfc.section.6.7.p.3">A server that sends a <a href="p2-semantics.html#status.101" class="smpl">101 (Switching Protocols)</a> response <em class="bcp14">MUST</em> send an Upgrade header field to indicate the new protocol(s) to which the connection is being switched; if multiple protocol
+         layers are being switched, the new protocols <em class="bcp14">MUST</em> be listed in layer-ascending order. A server <em class="bcp14">MUST NOT</em> switch to a protocol that was not indicated by the client in the corresponding request's Upgrade header field. A server <em class="bcp14">MAY</em> choose to ignore the order of preference indicated by the client and select the new protocol(s) based on other factors, such
+         as the nature of the request or the current load on the server.
+      </p>
+      <p id="rfc.section.6.7.p.4">A server that sends a <a href="p2-semantics.html#status.426" class="smpl">426 (Upgrade Required)</a> response <em class="bcp14">MUST</em> send an Upgrade header field to indicate the acceptable protocols, in order of descending preference.
+      </p>
+      <p id="rfc.section.6.7.p.5">A server <em class="bcp14">MAY</em> send an Upgrade header field in any other response to advertise that it implements support for upgrading to the listed protocols,
+         in order of descending preference, when appropriate for a future request.
+      </p>
+      <div id="rfc.figure.u.58"></div>
       <p>The following is a hypothetical example sent by a client:</p><pre class="text2">GET /hello.txt HTTP/1.1
 Host: www.example.com
@@ -2122 +2129 @@
 Upgrade: HTTP/2.0, SHTTP/1.3, IRC/6.9, RTA/x11
 
-</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
-         more commonly supported protocol while indicating to the server that it would like to use a "better" protocol if available
-         (where "better" is determined by the server, possibly according to the nature of the request method or target resource).
-      </p>
-      <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
-         and nature of the application-level communication after the protocol change is entirely dependent upon the new protocol chosen,
-         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.
-      </p>
-      <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
-         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
+</pre><p id="rfc.section.6.7.p.7">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-level communication after the protocol change is entirely dependent upon the new protocol(s)
+         chosen, 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.
+      </p>
+      <p id="rfc.section.6.7.p.8">For example, if the Upgrade header field is received in a GET request and the server decides to switch protocols, it 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
          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 <em class="bcp14">MUST NOT</em> switch protocols unless the received message semantics can be honored by the new protocol; an OPTIONS request can be honored
@@ -2143 +2146 @@
 [... data stream switches to HTTP/2.0 with an appropriate response
 (as defined by new protocol) to the "GET /hello.txt" request ...]
-</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
+</pre><p id="rfc.section.6.7.p.10">When Upgrade is sent, the 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 an "upgrade" connection option, in order to prevent Upgrade from being accidentally forwarded by intermediaries
          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.
       </p>
-      <p id="rfc.section.6.7.p.9">The Upgrade header field only applies to switching application-level protocols on the existing connection; it cannot be used
-         to switch to a protocol on a different connection. For that purpose, it is more appropriate to use a <a href="p2-semantics.html#status.3xx" class="smpl">3xx (Redirection)</a> response (<a href="p2-semantics.html#status.3xx" title="Redirection 3xx">Section 6.4</a> of <a href="#Part2" id="rfc.xref.Part2.26"><cite title="Hypertext Transfer Protocol (HTTP/1.1): Semantics and Content">[Part2]</cite></a>).
-      </p>
-      <p id="rfc.section.6.7.p.10">This specification only defines the protocol name "HTTP" for use by the family of Hypertext Transfer Protocols, as defined
+      <p id="rfc.section.6.7.p.11">The Upgrade header field only applies to switching protocols on top of the existing connection; it cannot be used to switch
+         the underlying connection (transport) protocol, nor to switch the existing communication to a different connection. For those
+         purposes, it is more appropriate to use a <a href="p2-semantics.html#status.3xx" class="smpl">3xx (Redirection)</a> response (<a href="p2-semantics.html#status.3xx" title="Redirection 3xx">Section 6.4</a> of <a href="#Part2" id="rfc.xref.Part2.26"><cite title="Hypertext Transfer Protocol (HTTP/1.1): Semantics and Content">[Part2]</cite></a>).
+      </p>
+      <p id="rfc.section.6.7.p.12">This specification only defines the protocol name "HTTP" for use by the family of Hypertext Transfer Protocols, as defined
          by the HTTP version rules of <a href="#http.version" title="Protocol Versioning">Section&nbsp;2.6</a> and future updates to this specification. Additional tokens ought to be registered with IANA using the registration procedure
          defined in <a href="#upgrade.token.registry" title="Upgrade Token Registry">Section&nbsp;7.5</a>.

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

@@ -3087 +3087 @@
    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.
+   more of those protocols, in order of descending preference, before sending
+   the final response. A server &MAY; ignore a received Upgrade header field
+   if it wishes to continue using the current protocol on that connection.
 </t>
 <figure><artwork type="abnf2616"><iref primary="true" item="Grammar" subitem="Upgrade"/>
@@ -3103 +3098 @@
   <x:ref>protocol-version</x:ref> = <x:ref>token</x:ref>
 </artwork></figure>
+<t>
+   A server that sends a <x:ref>101 (Switching Protocols)</x:ref> response
+   &MUST; send an Upgrade header field to indicate the new protocol(s) to
+   which the connection is being switched; if multiple protocol layers are
+   being switched, the new protocols &MUST; be listed in layer-ascending
+   order. A server &MUST-NOT; switch to a protocol that was not indicated by
+   the client in the corresponding request's Upgrade header field.
+   A server &MAY; choose to ignore the order of preference indicated by the
+   client and select the new protocol(s) based on other factors, such as the
+   nature of the request or the current load on the server.
+</t>
+<t>
+   A server that sends a <x:ref>426 (Upgrade Required)</x:ref> response
+   &MUST; send an Upgrade header field to indicate the acceptable protocols,
+   in order of descending preference.
+</t>
+<t>
+   A server &MAY; send an Upgrade header field in any other response to
+   advertise that it implements support for upgrading to the listed protocols,
+   in order of descending preference, when appropriate for a future request.
+</t>
 <figure><preamble>
    The following is a hypothetical example sent by a client:
@@ -3113 +3129 @@
 </artwork></figure>
 <t>
-   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
-   to use a "better" protocol if available (where "better" is determined
-   by the server, possibly according to the nature of the request method
-   or target resource).
-</t>
-<t>
    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-level communication after the protocol change is entirely
-   dependent upon the new protocol chosen, although the first action
+   dependent upon the new protocol(s) chosen, although the first action
    after changing the protocol &MUST; be a response to the initial HTTP
    request that contained the Upgrade header field.
@@ -3130 +3138 @@
 <t>
    For example, if the Upgrade header field is received in a GET request
-   and the server decides to switch protocols, then it first responds
+   and the server decides to switch protocols, it first responds
    with a <x:ref>101 (Switching Protocols)</x:ref> message in HTTP/1.1 and
    then immediately follows that with the new protocol's equivalent of a
@@ -3150 +3158 @@
 </artwork></figure>
 <t>
-   When Upgrade is sent, a sender &MUST; also send a 
+   When Upgrade is sent, the sender &MUST; also send a 
    <x:ref>Connection</x:ref> header field (<xref target="header.connection"/>)
-   that contains the "upgrade" connection option, in order to prevent Upgrade
+   that contains an "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
@@ -3158 +3166 @@
 </t>
 <t>
-   The Upgrade header field only applies to switching application-level
-   protocols on the existing 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;).
+   The Upgrade header field only applies to switching protocols on top of the
+   existing connection; it cannot be used to switch the underlying connection
+   (transport) protocol, nor to switch the existing communication to a
+   different connection. For those purposes, it is more appropriate to use a
+   <x:ref>3xx (Redirection)</x:ref> response (&status-3xx;).
 </t>
 <t>