forked from mdn/content
-
Notifications
You must be signed in to change notification settings - Fork 0
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
HTTP Sec-WebSocket-* headers (mdn#35606)
* Sec-WebSocket-Protocol docs * Sec-WebSocket-Protocol fix * Sec-WebSocket-Version - add docs * Sec-WebSocket-Extensions - add docs * Cross link the headers * Update files/en-us/web/api/websocket/websocket/index.md Co-authored-by: Joshua Chen <[email protected]> * Update files/en-us/web/http/headers/sec-websocket-protocol/index.md Co-authored-by: Joshua Chen <[email protected]> * Apply suggestions from code review Co-authored-by: Brian Thomas Smith <[email protected]> * Apply suggestions from code review * Update files/en-us/web/api/websockets_api/index.md Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com> * Update files/en-us/web/api/websockets_api/index.md Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com> * Update files/en-us/web/api/websockets_api/index.md --------- Co-authored-by: Joshua Chen <[email protected]> Co-authored-by: Brian Thomas Smith <[email protected]> Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>
- Loading branch information
4 people
authored
Sep 9, 2024
1 parent
f1b0f87
commit c69e369
Showing
8 changed files
with
351 additions
and
12 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
106 changes: 106 additions & 0 deletions
106
files/en-us/web/http/headers/sec-websocket-extensions/index.md
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,106 @@ | ||
| --- | ||
| title: Sec-WebSocket-Extensions | ||
| slug: Web/HTTP/Headers/Sec-WebSocket-Extensions | ||
| page-type: http-header | ||
| browser-compat: http.headers.Sec-WebSocket-Extensions | ||
| spec-urls: https://datatracker.ietf.org/doc/html/rfc6455#section-11.3.2 | ||
| --- | ||
|
|
||
| {{HTTPSidebar}} | ||
|
|
||
| The **Sec-WebSocket-Extensions** HTTP {{glossary("request header", "request")}} and {{glossary("response header")}} is used in the [WebSocket](/en-US/docs/Web/API/WebSockets_API) opening [handshake](/en-US/docs/Web/API/WebSockets_API/Writing_WebSocket_servers#the_websocket_handshake) to negotiate a protocol extension used by the client and server. | ||
|
|
||
| In a request the header specifies one or more extensions that the web application would like to use, in order of preference. | ||
| These can be added as in multiple headers, or as comma separate values added to a single header. | ||
|
|
||
| In a response the header can only appear once, where it specifies the extension selected by the server from the client's preferences. | ||
| This value must be the first extension that the server supports from the list provided in the request header. | ||
|
|
||
| The request header is automatically added by the browser based on its own capabilities, and does not depend on parameters passed to the constructor when the `WebSocket` is created. | ||
|
|
||
| <table class="properties"> | ||
| <tbody> | ||
| <tr> | ||
| <th scope="row">Header type</th> | ||
| <td>{{Glossary("Request header")}}, {{Glossary("Response header")}}</td> | ||
| </tr> | ||
| <tr> | ||
| <th scope="row">{{Glossary("Forbidden header name")}}</th> | ||
| <td>yes</td> | ||
| </tr> | ||
| </tbody> | ||
| </table> | ||
|
|
||
| ## Syntax | ||
|
|
||
| Request | ||
|
|
||
| ```http | ||
| Sec-WebSocket-Extensions: <extensions> | ||
| ``` | ||
|
|
||
| Response | ||
|
|
||
| ```http | ||
| Sec-WebSocket-Extensions: <selected-extension> | ||
| ``` | ||
|
|
||
| ## Directives | ||
|
|
||
| - `<extensions>` | ||
| - : A comma-separated list of extensions to request (or for the server to agree to support). | ||
| These should be selected from the [IANA WebSocket Extension Name Registry](https://www.iana.org/assignments/websocket/websocket.xml#extension-name). | ||
| Extensions which take parameters delineate them with semicolons. | ||
|
|
||
| ## Examples | ||
|
|
||
| The HTTP request below shows the opening handshake where a client supports the `permessage-deflate` and `client_max_window_bits` extensions. | ||
|
|
||
| ```http | ||
| GET /chat HTTP/1.1 | ||
| Host: example.com:8000 | ||
| Upgrade: websocket | ||
| Connection: Upgrade | ||
| Sec-WebSocket-Key: dGhlIHNhbXBsZSBub25jZQ== | ||
| Sec-WebSocket-Version: 13 | ||
| Sec-WebSocket-Extensions: permessage-deflate; client_max_window_bits | ||
| ``` | ||
|
|
||
| The request below with separate headers for each extension is equivalent: | ||
|
|
||
| ```http | ||
| GET /chat HTTP/1.1 | ||
| Host: example.com:8000 | ||
| Upgrade: websocket | ||
| Connection: Upgrade | ||
| Sec-WebSocket-Key: dGhlIHNhbXBsZSBub25jZQ== | ||
| Sec-WebSocket-Version: 13 | ||
| Sec-WebSocket-Extensions: permessage-deflate | ||
| Sec-WebSocket-Extensions: client_max_window_bits | ||
| ``` | ||
|
|
||
| The response below might be sent from a server to indicate that it will support the `permessage-deflate` extension: | ||
|
|
||
| ```http | ||
| HTTP/1.1 101 Switching Protocols | ||
| Upgrade: websocket | ||
| Connection: Upgrade | ||
| Sec-WebSocket-Accept: s3pPLMBiTxaQ9kYGzzhZRbK+xOo= | ||
| Sec-WebSocket-Extensions: permessage-deflate | ||
| ``` | ||
|
|
||
| ## Specifications | ||
|
|
||
| {{Specifications}} | ||
|
|
||
| ## Browser compatibility | ||
|
|
||
| {{Compat}} | ||
|
|
||
| ## See also | ||
|
|
||
| - {{HTTPHeader("Sec-WebSocket-Accept")}} | ||
| - {{HTTPHeader("Sec-WebSocket-Key")}} | ||
| - {{HTTPHeader("Sec-WebSocket-Version")}} | ||
| - {{HTTPHeader("Sec-WebSocket-Protocol")}} | ||
| - [The WebSocket handshake](/en-US/docs/Web/API/WebSockets_API/Writing_WebSocket_servers#the_websocket_handshake) and [Subprotocols](/en-US/docs/Web/API/WebSockets_API/Writing_WebSocket_servers#subprotocols) in _Writing WebSocket servers_ |
103 changes: 103 additions & 0 deletions
103
files/en-us/web/http/headers/sec-websocket-protocol/index.md
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,103 @@ | ||
| --- | ||
| title: Sec-WebSocket-Protocol | ||
| slug: Web/HTTP/Headers/Sec-WebSocket-Protocol | ||
| page-type: http-header | ||
| browser-compat: http.headers.Sec-WebSocket-Protocol | ||
| spec-urls: https://datatracker.ietf.org/doc/html/rfc6455#section-11.3.4 | ||
| --- | ||
|
|
||
| {{HTTPSidebar}} | ||
|
|
||
| The **`Sec-WebSocket-Protocol`** HTTP {{glossary("request header", "request")}} and {{glossary("response header")}} is used in the [WebSocket](/en-US/docs/Web/API/WebSockets_API) opening [handshake](/en-US/docs/Web/API/WebSockets_API/Writing_WebSocket_servers#the_websocket_handshake) to negotiate a [sub-protocol](/en-US/docs/Web/API/WebSockets_API/Writing_WebSocket_servers#subprotocols) to use in the communication. | ||
| This can be a well understood protocol, such as SOAP or WAMP, or a custom protocol understood by the client and server. | ||
|
|
||
| In a request the header specifies one or more WebSocket sub-protocols that the web application would like to use, in order of preference. | ||
| These can be added as protocol values in multiple headers, or as comma separate values added to a single header. | ||
|
|
||
| In a response it specifies the sub-protocol selected by the server. | ||
| This must be the first sub-protocol that the server supports from the list provided in the request header. | ||
|
|
||
| The request header is automatically added and populated by the browser using values specified by the application in the [`protocols`](/en-US/docs/Web/API/WebSocket/WebSocket#protocols) argument to the `WebSocket()`. | ||
| The sub-protocol selected by the server is made available to the web application in {{domxref("WebSocket.protocol")}}. | ||
|
|
||
| <table class="properties"> | ||
| <tbody> | ||
| <tr> | ||
| <th scope="row">Header type</th> | ||
| <td>{{Glossary("Request header")}}, {{Glossary("Response header")}}</td> | ||
| </tr> | ||
| <tr> | ||
| <th scope="row">{{Glossary("Forbidden header name")}}</th> | ||
| <td>yes</td> | ||
| </tr> | ||
| </tbody> | ||
| </table> | ||
|
|
||
| ## Syntax | ||
|
|
||
| Request: | ||
|
|
||
| ```http | ||
| Sec-WebSocket-Protocol: <sub-protocols> | ||
| ``` | ||
|
|
||
| Response: | ||
|
|
||
| ```http | ||
| Sec-WebSocket-Protocol: <selected-sub-protocol> | ||
| ``` | ||
|
|
||
| ## Directives | ||
|
|
||
| - `<sub-protocols>` | ||
| - : A comma-separated list of sub-protocol names, in the order of preference. | ||
| The sub-protocols may be selected from the [IANA WebSocket Subprotocol Name Registry](https://www.iana.org/assignments/websocket/websocket.xml#subprotocol-name), or may be a custom name jointly understood by the client and the server. | ||
|
|
||
| ## Examples | ||
|
|
||
| The sub-protocol is specified in the original WebSocket [handshake request](/en-US/docs/Web/API/WebSockets_API/Writing_WebSocket_servers#the_websocket_handshake). | ||
| The request below shows that the client prefers `soap`, but also supports `wamp`. | ||
|
|
||
| ```http | ||
| GET /chat HTTP/1.1 | ||
| Host: example.com:8000 | ||
| Upgrade: websocket | ||
| Connection: Upgrade | ||
| Sec-WebSocket-Key: dGhlIHNhbXBsZSBub25jZQ== | ||
| Sec-WebSocket-Version: 13 | ||
| Sec-WebSocket-Protocol: soap, wamp | ||
| ``` | ||
|
|
||
| Specifying the protocols like this has the same effect: | ||
|
|
||
| ```http | ||
| Sec-WebSocket-Protocol: soap | ||
| Sec-WebSocket-Protocol: wamp | ||
| ``` | ||
|
|
||
| The response from the server will include the `Sec-WebSocket-Protocol` header, selecting the first sub-protocol that it supports from the client's preferences. | ||
| Below that is shown as `soap`: | ||
|
|
||
| ```http | ||
| HTTP/1.1 101 Switching Protocols | ||
| Upgrade: websocket | ||
| Connection: Upgrade | ||
| Sec-WebSocket-Accept: s3pPLMBiTxaQ9kYGzzhZRbK+xOo= | ||
| Sec-WebSocket-Protocol: soap | ||
| ``` | ||
|
|
||
| ## Specifications | ||
|
|
||
| {{Specifications}} | ||
|
|
||
| ## Browser compatibility | ||
|
|
||
| {{Compat}} | ||
|
|
||
| ## See also | ||
|
|
||
| - {{HTTPHeader("Sec-WebSocket-Accept")}} | ||
| - {{HTTPHeader("Sec-WebSocket-Key")}} | ||
| - {{HTTPHeader("Sec-WebSocket-Version")}} | ||
| - {{HTTPHeader("Sec-WebSocket-Extensions")}} | ||
| - [The WebSocket handshake](/en-US/docs/Web/API/WebSockets_API/Writing_WebSocket_servers#the_websocket_handshake) and [Subprotocols](/en-US/docs/Web/API/WebSockets_API/Writing_WebSocket_servers#subprotocols) in _Writing WebSocket servers_ |
Oops, something went wrong.