1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
|
---
title: 協議升級機制
slug: Web/HTTP/Protocol_upgrade_mechanism
translation_of: Web/HTTP/Protocol_upgrade_mechanism
---
<div>
<p>{{HTTPSidebar}}</p>
<p><a href="/zh-TW/docs/Web/HTTP">HTTP/1.1 協議</a>提供了一種特殊的機制，這一機制允許將一個已建立的連接升級成新的、不相容的協議。這篇指南涵蓋了其運作原理和使用場景。</p>
<p>通常來說這一機制總是由客戶端發起的 （不過也有例外，比如說可以由服務端發起{{anch("Server-initiated upgrade to TLS", "升級到傳輸層安全協議（TLS）")}}）， 服務端可以選擇是否要升級到新協議。借助這一技術，連接可以以常用的協議啟動（如HTTP/1.1），隨後再升級到HTTP2甚至是WebSockets.</p>
<p>注意：HTTP/2 明確禁止使用此機制，這個機制只屬於 HTTP/1.1</p>
</div>
<h2 id="升级_HTTP1.1_連線">升级 HTTP/1.1 連線</h2>
<p><br>
協議升級請求總是由客戶端發起的；暫時沒有服務端請求協議更改的機制。當客戶端試圖升級到一個新的協議時，可以先發送一個普通的請求（{{HTTPMethod("GET")}}，{{HTTPMethod("POST")}}等），不過這個請求需要進行特殊配置以包含升級請求。<br>
Upgrade 請求看起來就像：</p>
<pre>GET /index.html HTTP/1.1
Host: www.example.com
Connection: upgrade
Upgrade: example/1, foo/2
</pre>
<p><br>
根據之前的請求的協議，可能需要其他頭部信息，例如：從HTTP/1.1升級到WebSocket 允許配置有關 WebSocket 連接的頭部詳細信息，以及在連接時提供一定程度的安全性。查看 <a href="#upgrading_to_a_websocket_connection">Upgrading to a WebSocket connection</a> 獲取更多信息。</p>
<p>如果服務器決定升級這次連接，就會返回一個 {{HTTPStatus(101, "101 Switching Protocols")}} 響應狀態碼，和一個要切換到的協議的頭部字段Upgrade。 如果服務器沒有（或者不能）升級這次連接，它會忽略客戶端發送的 "Upgrade 頭部字段，返回一個常規的響應：例如一個{{HTTPStatus(200, "200 OK")}}).</p>
<p>服務在發送 101 狀態碼之後，就可以使用新的協議，並可以根據需要執行任何其他協議指定的握手。實際上，一旦這次升級完成了，連接就變成了雙向管道。並且可以通過新協議完成啟動升級的請求。</p>
<h2 id="Common_uses_for_this_mechanism">Common uses for this mechanism</h2>
<p>Here we look at the most common use cases for the {{HTTPHeader("Upgrade")}} header.</p>
<h3 id="Upgrading_to_a_WebSocket_connection">Upgrading to a WebSocket connection</h3>
<p>By far, the most common use case for upgrading an HTTP connection is to use WebSockets, which are always implemented by upgrading an HTTP or HTTPS connection. Keep in mind that if you're opening a new connection using the <a href="/en-US/docs/Web/API/WebSocket">WebSocket API</a>, or any library that does WebSockets, most or all of this is done for you. For example, opening a WebSocket connection is as simple as:</p>
<pre class="brush: js">webSocket = new WebSocket("ws://destination.server.ext", "optionalProtocol");</pre>
<p>The {{domxref("WebSocket.WebSocket", "WebSocket()")}} constructor does all the work of creating an initial HTTP/1.1 connection then handling the handshaking and upgrade process for you.</p>
<div class="note">
<p>You can also use the <code>"wss://"</code> URL scheme to open a secure WebSocket connection.</p>
</div>
<p>If you need to create a WebSocket connection from scratch, you'll have to handle the handshaking process yourself. After creating the initial HTTP/1.1 session, you need to request the upgrade by adding to a standard request the {{HTTPHeader("Upgrade")}} and {{HTTPHeader("Connection")}} headers, as follows:</p>
<pre>Connection: Upgrade
Upgrade: websocket</pre>
<h3 id="WebSocket-specific_headers">WebSocket-specific headers</h3>
<p>The following headers are involved in the WebSocket upgrade process. Other than the {{HTTPHeader("Upgrade")}} and {{HTTPHeader("Connection")}} headers, the rest are generally optional or handled for you by the browser and server when they're talking to each other.</p>
<h4 id="HTTPHeaderSec-WebSocket-Extensions">{{HTTPHeader("Sec-WebSocket-Extensions")}}</h4>
<p>Specifies one or more protocol-level WebSocket extensions to ask the server to use. Using more than one <code>Sec-WebSocket-Extension</code> header in a request is permitted; the result is the same as if you included all of the listed extensions in one such header.</p>
<pre class="syntaxbox">Sec-WebSocket-Extensions: <var>extensions</var></pre>
<dl>
<dt><code><var>extensions</var></code></dt>
<dd>A comma-separated list of extensions to request (or agree to support). These should be selected from the <a href="https://www.iana.org/assignments/websocket/websocket.xml#extension-name">IANA WebSocket Extension Name Registry</a>. Extensions which take parameters do so by using semicolon delineation.</dd>
</dl>
<p>For example:</p>
<pre>Sec-WebSocket-Extensions: superspeed, colormode; depth=16</pre>
<h4 id="HTTPHeaderSec-WebSocket-Key">{{HTTPHeader("Sec-WebSocket-Key")}}</h4>
<p>Provides information to the server which is needed in order to confirm that the client is entitled to request an upgrade to WebSocket. This header can be used when insecure (HTTP) clients wish to upgrade, in order to offer some degree of protection against abuse. The value of the key is computed using an algorithm defined in the WebSocket specification, so this <em>does not provide security</em>. Instead, it helps to prevent non-WebSocket clients from inadvertently, or through misuse, requesting a WebSocket connection. In essence, then, this key simply confirms that "Yes, I really mean to open a WebSocket connection."</p>
<p>This header is automatically added by clients that choose to use it; it cannot be added using the {{domxref("XMLHttpRequest.setRequestHeader()")}} method.</p>
<pre class="syntaxbox">Sec-WebSocket-Key: <var>key</var></pre>
<dl>
<dt><code><var>key</var></code></dt>
<dd>The key for this request to upgrade. The client adds this if it wishes to do so, and the server will include in the response a key of its own, which the client will validate before delivering the upgrade response to you.</dd>
</dl>
<p>The server's response's {{HTTPHeader("Sec-WebSocket-Accept")}} header will have a value computed based upon the specified <code><var>key</var></code>.</p>
<h4 id="HTTPHeaderSec-WebSocket-Protocol">{{HTTPHeader("Sec-WebSocket-Protocol")}}</h4>
<p>The <code>Sec-WebSocket-Protocol</code> header specifies one or more WebSocket protocols that you wish to use, in order of preference. The first one that is supported by the server will be selected and returned by the server in a <code>Sec-WebSocket-Protocol</code> header included in the response. You can use this more than once in the header, as well; the result is the same as if you used a comma-delineated list of subprotocol identifiers in a single header.</p>
<pre class="syntaxbox">Sec-WebSocket-Protocol: <var>subprotocols</var></pre>
<dl>
<dt><code><var>subprotocols</var></code></dt>
<dd>A comma-separated list of subprotocol names, in the order of preference. The subprotocols may be selected from the <a href="https://www.iana.org/assignments/websocket/websocket.xml#subprotocol-name">IANA WebSocket Subprotocol Name Registry</a> or may be a custom name jointly understood by the client and the server.</dd>
</dl>
<h4 id="HTTPHeaderSec-WebSocket-Version">{{HTTPHeader("Sec-WebSocket-Version")}}</h4>
<h5 id="Request_header">Request header</h5>
<p>Specifies the WebSocket protocol version the client wishes to use, so the server can confirm whether or not that version is supported on its end.</p>
<pre class="syntaxbox">Sec-WebSocket-Version: <var>version</var></pre>
<dl>
<dt><code><var>version</var></code></dt>
<dd>The WebSocket protocol version the client wishes to use when communicating with the server. This number should be the most recent version possible listed in the <a href="https://www.iana.org/assignments/websocket/websocket.xml#version-number">IANA WebSocket Version Number Registry</a>. The most recent final version of the WebSocket protocol is version 13.</dd>
</dl>
<h5 id="Response_header">Response header</h5>
<p>If the server can't communicate using the specified version of the WebSocket protocol, it will respond with an error (such as 426 Upgrade Required) that includes in its headers a <code>Sec-WebSocket-Version</code> header with a comma-separated list of the supported protocol versions. If the server does support the requested protocol version, no <code>Sec-WebSocket-Version</code> header is included in the response.</p>
<pre class="syntaxbox">Sec-WebSocket-Version: <var>supportedVersions</var></pre>
<dl>
<dt><code><var>supportedVersions</var></code></dt>
<dd>A comma-delineated list of the WebSocket protocol versions supported by the server.</dd>
</dl>
<h3 id="Response-only_headers">Response-only headers</h3>
<p>The response from the server may include these.</p>
<h4 id="HTTPHeaderSec-WebSocket-Accept">{{HTTPHeader("Sec-WebSocket-Accept")}}</h4>
<p>Included in the response message from the server during the opening handshake process when the server is willing to initiate a WebSocket connection. It will appear no more than once in the response headers.</p>
<pre class="syntaxbox">Sec-WebSocket-Accept: <var>hash</var></pre>
<dl>
<dt><code><var>hash</var></code></dt>
<dd>If a {{HTTPHeader("Sec-WebSocket-Key")}} header was provided, the value of this header is computed by taking the value of the key, concatenating the string "258EAFA5-E914-47DA-95CA-C5AB0DC85B11" to it, taking the {{interwiki("wikipedia", "SHA-1")}} hash of that concatenated string, resulting in a 20-byte value. That value is then <a href="/en-US/docs/Web/API/WindowBase64/Base64_encoding_and_decoding">base64</a> encoded to obtain the value of this property.</dd>
</dl>
<h2 id="References">References</h2>
<ul>
<li><a href="/en-US/docs/Web/API/WebSocket">WebSocket API</a></li>
<li><a href="/en-US/docs/Web/HTTP">HTTP</a></li>
<li>Specifications and RFCs:
<ul>
<li>{{RFC(7230)}}</li>
<li>{{RFC(6455)}}</li>
<li>{{RFC(7540)}}</li>
</ul>
</li>
</ul>
|
