Changeset 2274


Ignore:
Timestamp:
May 24, 2013, 11:55:38 PM (7 years ago)
Author:
fielding@…
Message:

Define ordering for Upgrade; addresses #445

Location:
draft-ietf-httpbis/latest
Files:
2 edited

Legend:

Unmodified
Added
Removed
  • draft-ietf-httpbis/latest/p1-messaging.html

    r2273 r2274  
    21062106      <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>
    21072107      <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
    2108          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
    2109          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
    2110             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
    2111          protocols for a future request.
     2108         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,
     2109         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.
    21122110      </p>
    21132111      <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>
     
    21162114  <a href="#header.upgrade" class="smpl">protocol-name</a>    = <a href="#rule.token.separators" class="smpl">token</a>
    21172115  <a href="#header.upgrade" class="smpl">protocol-version</a> = <a href="#rule.token.separators" class="smpl">token</a>
    2118 </pre><div id="rfc.figure.u.58"></div>
     2116</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
     2117         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
     2118         as the nature of the request or the current load on the server.
     2119      </p>
     2120      <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.
     2121      </p>
     2122      <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,
     2123         in order of descending preference, when appropriate for a future request.
     2124      </p>
     2125      <div id="rfc.figure.u.58"></div>
    21192126      <p>The following is a hypothetical example sent by a client:</p><pre class="text2">GET /hello.txt HTTP/1.1
    21202127Host: www.example.com
     
    21222129Upgrade: HTTP/2.0, SHTTP/1.3, IRC/6.9, RTA/x11
    21232130
    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
    2125          more commonly supported protocol while indicating to the server that it would like to use a "better" protocol if available
    2126          (where "better" is determined by the server, possibly according to the nature of the request method or target resource).
    2127       </p>
    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
    2129          and nature of the application-level communication after the protocol change is entirely dependent upon the new protocol chosen,
    2130          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.
    2131       </p>
    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
    2133          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
     2131</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
     2132         and nature of the application-level communication after the protocol change is entirely dependent upon the new protocol(s)
     2133         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.
     2134      </p>
     2135      <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
     2136         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
    21342137         resource. This allows a connection to be upgraded to protocols with the same semantics as HTTP without the latency cost of
    21352138         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
     
    21432146[... data stream switches to HTTP/2.0 with an appropriate response
    21442147(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
     2148</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
    21462149         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.
    21472150      </p>
    2148       <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
    2149          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>).
    2150       </p>
    2151       <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
     2151      <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
     2152         the underlying connection (transport) protocol, nor to switch the existing communication to a different connection. For those
     2153         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>).
     2154      </p>
     2155      <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
    21522156         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
    21532157         defined in <a href="#upgrade.token.registry" title="Upgrade Token Registry">Section&nbsp;7.5</a>.
  • draft-ietf-httpbis/latest/p1-messaging.xml

    r2271 r2274  
    30873087   connection.  A client &MAY; send a list of protocols in the Upgrade
    30883088   header field of a request to invite the server to switch to one or
    3089    more of those protocols before sending the final response.
    3090    A server &MUST; send an Upgrade header field in <x:ref>101 (Switching
    3091    Protocols)</x:ref> responses to indicate which protocol(s) are being
    3092    switched to, and &MUST; send it in <x:ref>426 (Upgrade Required)</x:ref>
    3093    responses to indicate acceptable protocols.
    3094    A server &MAY; send an Upgrade header field in any other response to
    3095    indicate that they might be willing to upgrade to one of the
    3096    specified protocols for a future request.
     3089   more of those protocols, in order of descending preference, before sending
     3090   the final response. A server &MAY; ignore a received Upgrade header field
     3091   if it wishes to continue using the current protocol on that connection.
    30973092</t>
    30983093<figure><artwork type="abnf2616"><iref primary="true" item="Grammar" subitem="Upgrade"/>
     
    31033098  <x:ref>protocol-version</x:ref> = <x:ref>token</x:ref>
    31043099</artwork></figure>
     3100<t>
     3101   A server that sends a <x:ref>101 (Switching Protocols)</x:ref> response
     3102   &MUST; send an Upgrade header field to indicate the new protocol(s) to
     3103   which the connection is being switched; if multiple protocol layers are
     3104   being switched, the new protocols &MUST; be listed in layer-ascending
     3105   order. A server &MUST-NOT; switch to a protocol that was not indicated by
     3106   the client in the corresponding request's Upgrade header field.
     3107   A server &MAY; choose to ignore the order of preference indicated by the
     3108   client and select the new protocol(s) based on other factors, such as the
     3109   nature of the request or the current load on the server.
     3110</t>
     3111<t>
     3112   A server that sends a <x:ref>426 (Upgrade Required)</x:ref> response
     3113   &MUST; send an Upgrade header field to indicate the acceptable protocols,
     3114   in order of descending preference.
     3115</t>
     3116<t>
     3117   A server &MAY; send an Upgrade header field in any other response to
     3118   advertise that it implements support for upgrading to the listed protocols,
     3119   in order of descending preference, when appropriate for a future request.
     3120</t>
    31053121<figure><preamble>
    31063122   The following is a hypothetical example sent by a client:
     
    31133129</artwork></figure>
    31143130<t>
    3115    Upgrade eases the difficult transition between incompatible protocols by
    3116    allowing the client to initiate a request in the more commonly
    3117    supported protocol while indicating to the server that it would like
    3118    to use a "better" protocol if available (where "better" is determined
    3119    by the server, possibly according to the nature of the request method
    3120    or target resource).
    3121 </t>
    3122 <t>
    31233131   Upgrade cannot be used to insist on a protocol change; its acceptance and
    31243132   use by the server is optional. The capabilities and nature of the
    31253133   application-level communication after the protocol change is entirely
    3126    dependent upon the new protocol chosen, although the first action
     3134   dependent upon the new protocol(s) chosen, although the first action
    31273135   after changing the protocol &MUST; be a response to the initial HTTP
    31283136   request that contained the Upgrade header field.
     
    31303138<t>
    31313139   For example, if the Upgrade header field is received in a GET request
    3132    and the server decides to switch protocols, then it first responds
     3140   and the server decides to switch protocols, it first responds
    31333141   with a <x:ref>101 (Switching Protocols)</x:ref> message in HTTP/1.1 and
    31343142   then immediately follows that with the new protocol's equivalent of a
     
    31503158</artwork></figure>
    31513159<t>
    3152    When Upgrade is sent, a sender &MUST; also send a
     3160   When Upgrade is sent, the sender &MUST; also send a
    31533161   <x:ref>Connection</x:ref> header field (<xref target="header.connection"/>)
    3154    that contains the "upgrade" connection option, in order to prevent Upgrade
     3162   that contains an "upgrade" connection option, in order to prevent Upgrade
    31553163   from being accidentally forwarded by intermediaries that might not implement
    31563164   the listed protocols.  A server &MUST; ignore an Upgrade header field that
     
    31583166</t>
    31593167<t>
    3160    The Upgrade header field only applies to switching application-level
    3161    protocols on the existing connection; it cannot be used
    3162    to switch to a protocol on a different connection. For that purpose, it is
    3163    more appropriate to use a <x:ref>3xx (Redirection)</x:ref> response
    3164    (&status-3xx;).
     3168   The Upgrade header field only applies to switching protocols on top of the
     3169   existing connection; it cannot be used to switch the underlying connection
     3170   (transport) protocol, nor to switch the existing communication to a
     3171   different connection. For those purposes, it is more appropriate to use a
     3172   <x:ref>3xx (Redirection)</x:ref> response (&status-3xx;).
    31653173</t>
    31663174<t>
Note: See TracChangeset for help on using the changeset viewer.