Changeset 2274 for draft-ietf-httpbis/latest
- Timestamp:
- 25/05/13 06:55:38 (10 years ago)
- Location:
- draft-ietf-httpbis/latest
- Files:
-
- 2 edited
Legend:
- Unmodified
- Added
- Removed
-
draft-ietf-httpbis/latest/p1-messaging.html
r2273 r2274 2106 2106 <h2 id="rfc.section.6.7"><a href="#rfc.section.6.7">6.7</a> <a id="header.upgrade" href="#header.upgrade">Upgrade</a></h2> 2107 2107 <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. 2112 2110 </p> 2113 2111 <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> 2117 2115 <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> 2119 2126 <p>The following is a hypothetical example sent by a client:</p><pre class="text2">GET /hello.txt HTTP/1.1 2120 2127 Host: www.example.com … … 2122 2129 Upgrade: HTTP/2.0, SHTTP/1.3, IRC/6.9, RTA/x11 2123 2130 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 2134 2137 resource. This allows a connection to be upgraded to protocols with the same semantics as HTTP without the latency cost of 2135 2138 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 2144 2147 (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 6.1</a>) that contains the"upgrade" connection option, in order to prevent Upgrade from being accidentally forwarded by intermediaries2148 </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 6.1</a>) that contains an "upgrade" connection option, in order to prevent Upgrade from being accidentally forwarded by intermediaries 2146 2149 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. 2147 2150 </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 2152 2156 by the HTTP version rules of <a href="#http.version" title="Protocol Versioning">Section 2.6</a> and future updates to this specification. Additional tokens ought to be registered with IANA using the registration procedure 2153 2157 defined in <a href="#upgrade.token.registry" title="Upgrade Token Registry">Section 7.5</a>. -
draft-ietf-httpbis/latest/p1-messaging.xml
r2271 r2274 3087 3087 connection. A client &MAY; send a list of protocols in the Upgrade 3088 3088 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. 3097 3092 </t> 3098 3093 <figure><artwork type="abnf2616"><iref primary="true" item="Grammar" subitem="Upgrade"/> … … 3103 3098 <x:ref>protocol-version</x:ref> = <x:ref>token</x:ref> 3104 3099 </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> 3105 3121 <figure><preamble> 3106 3122 The following is a hypothetical example sent by a client: … … 3113 3129 </artwork></figure> 3114 3130 <t> 3115 Upgrade eases the difficult transition between incompatible protocols by3116 allowing the client to initiate a request in the more commonly3117 supported protocol while indicating to the server that it would like3118 to use a "better" protocol if available (where "better" is determined3119 by the server, possibly according to the nature of the request method3120 or target resource).3121 </t>3122 <t>3123 3131 Upgrade cannot be used to insist on a protocol change; its acceptance and 3124 3132 use by the server is optional. The capabilities and nature of the 3125 3133 application-level communication after the protocol change is entirely 3126 dependent upon the new protocol chosen, although the first action3134 dependent upon the new protocol(s) chosen, although the first action 3127 3135 after changing the protocol &MUST; be a response to the initial HTTP 3128 3136 request that contained the Upgrade header field. … … 3130 3138 <t> 3131 3139 For example, if the Upgrade header field is received in a GET request 3132 and the server decides to switch protocols, thenit first responds3140 and the server decides to switch protocols, it first responds 3133 3141 with a <x:ref>101 (Switching Protocols)</x:ref> message in HTTP/1.1 and 3134 3142 then immediately follows that with the new protocol's equivalent of a … … 3150 3158 </artwork></figure> 3151 3159 <t> 3152 When Upgrade is sent, asender &MUST; also send a3160 When Upgrade is sent, the sender &MUST; also send a 3153 3161 <x:ref>Connection</x:ref> header field (<xref target="header.connection"/>) 3154 that contains the"upgrade" connection option, in order to prevent Upgrade3162 that contains an "upgrade" connection option, in order to prevent Upgrade 3155 3163 from being accidentally forwarded by intermediaries that might not implement 3156 3164 the listed protocols. A server &MUST; ignore an Upgrade header field that … … 3158 3166 </t> 3159 3167 <t> 3160 The Upgrade header field only applies to switching application-level3161 protocols on the existing connection; it cannot be used3162 to switch to a protocol on a different connection. For that purpose, it is3163 more appropriate to use a <x:ref>3xx (Redirection)</x:ref> response3164 (&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;). 3165 3173 </t> 3166 3174 <t>
Note: See TracChangeset
for help on using the changeset viewer.