Ignore:
Timestamp:
25/05/13 06:55:38 (7 years ago)
Author:
fielding@…
Message:

Define ordering for Upgrade; addresses #445

File:
1 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>.
Note: See TracChangeset for help on using the changeset viewer.