cid f43ae338f04376290af0511c43db8365590230ea20576c50cf1fd4d2fd0d4cc1 · original · open access · via whatwg
Title: WebSockets Standard
Authors:
Venue: whatwg
Year: 2026
Canonical: whatwg:websocket
URL: https://websocket.spec.whatwg.org/
Collector: whatwg
OA: true
ABSTRACT
WebSockets Standard WebSockets Living Standard — Last Updated 19 October 2026 Participate: GitHub whatwg/websockets (new issue, open issues) Chat on Matrix Commits: GitHub whatwg/websockets/commits Snapshot as of this commit Tests: web-platform-tests websockets/ (ongoing work) Translations (non-normative): 日本語 简体中文 한국어 Abstract This specification provides APIs to enable web applications to maintain bidirectional communications with server-side processes. 1. Introduction This section is non-normative. To enable web applications to maintain bidirectional communications with server-side processes, this specification introduces the WebSocket interface. This interface does not allow for raw access to the underlying network. For example, this interface could not be used to implement an IRC client without proxying messages through a custom server. 2. WebSocket protocol alterations This section replaces part of the WebSocket protocol opening handshake client requirement to integrate it with algorithms defined in Fetch. This way CSP, cookies, HSTS, and other Fetch-related protocols are handled in a single location. Ideally the RFC would be updated with this language, but it is never that easy. The WebSocket API, defined below, uses this language. [WSP] [FETCH] The way this works is by replacing The WebSocket Protocol’s "establish a WebSocket connection" algorithm with a new one that integrates with Fetch. "Establish a WebSocket connection" consists of three algorithms: setting up a connection, creating and transmiting a handshake request, and validating the handshake response. That layering is different from Fetch, which first creates a handshake, then sets up a connection and transmits the handshake, and finally validates the response. Keep that in mind while reading these alterations. 2.1. Connections To obtain a WebSocket connection, given a url, run these steps: Let host be url’s host. Let port be url’s port. Let resource name be U+002F (/), followed by the strings in url’s path (including empty strings), if any, separated from each other by U+002F (/). If url’s query is non-empty, append U+003F (?), followed by url’s query, to resource name. Let secure be false, if url’s scheme is "http"; otherwise true. Follow the requirements stated in step 2 to 5, inclusive, of the first set of steps in section 4.1 of The WebSocket Protocol to establish a WebSocket connection, passing host, port, resource name and secure. [WSP] If that established a connection, return it, and return failure otherwise. Although structured a little differently, carrying different properties, and therefore not shareable, a WebSocket connection is very close to identical to an "ordinary" connection. 2.2. Opening handshake To establish a WebSocket connection, given a url, protocols, and client, run these steps: Let requestURL be a copy of url, with its scheme set to "http", if url’s scheme is "ws"; otherwise to "https". This change of scheme is essential to integrate well with fetching. E.g., HSTS would not work without it. There is no real reason for WebSocket to have distinct schemes, it’s a legacy artefact. [HSTS] Let request be a new request, whose URL is requestURL, client is client, service-workers mode is "none", referrer is "no-referrer", mode is "websocket", credentials mode is "include", cache mode is "no-store" , and redirect mode is "error". Append (`Upgrade`, `websocket`) to request’s header list. Append (`Connection`, `Upgrade`) to request’s header list. Let keyValue be a nonce consisting of a randomly selected 16-byte value that has been forgiving-base64-encoded and isomorphic encoded. If the randomly selected value was the byte sequence 0x01 0x02 0x03 0x04 0x05 0x06 0x07 0x08 0x09 0x0a 0x0b 0x0c 0x0d 0x0e 0x0f 0x10, keyValue would be forgiving-base64-encoded to "AQIDBAUGBwgJCgsMDQ4PEC==" and isomorphic encoded to `AQIDBAUGBwgJCgsMDQ4PEC==`. Append (`Sec-WebSocket-Key`, keyValue) to request’s header list. Append (`Sec-WebSocket-Version`, `13`) to request’s header list. For each protocol in protocols, combine (`Sec-WebSocket-Protocol`, protocol) in request’s header list. Let permessageDeflate be a user-agent defined "permessage-deflate" extension header value. [WSP] `permessage-deflate; client_max_window_bits` Append (`Sec-WebSocket-Extensions`, permessageDeflate) to request’s header list. Fetch request with useParallelQueue set to true, and processResponse given response being these steps: If response is a network error or its status is not 101, fail the WebSocket connection. If protocols is not the empty list and extracting header list values given `Sec-WebSocket-Protocol` and response’s header list results in null, failure, or the empty byte sequence, then fail the WebSocket connection. This is different from the check on this header defined by The WebSocket Protocol. That only covers a subprotocol not requested by the client. This covers a subprotocol requested by the client, but not acknowledged by the server. Follow the requirements stated step 2 to step 6, inclusive, of the last set of steps in section 4.1 of The WebSocket Protocol to validate response. This either results in fail the WebSocket connection or the WebSocket connection is established. Fail the WebSocket connection and the WebSocket connection is established are defined by The WebSocket Protocol. [WSP] The reason redirects are not followed and this handshake is generally restricted is because it could introduce serious security problems in a web browser context. For example, consider a host with a WebSocket server at one path and an open HTTP redirector at another. Suddenly, any script that can be given a particular WebSocket URL can be tricked into communicating to (and potentially sharing secrets with) any host on the internet, even if the script checks that the URL has the right hostname. 3. The WebSocket interface 3.1. Interface definition The Web IDL definition for the WebSocket class is given as follows: enum BinaryType { "blob", "arraybuffer" }; [Exposed=(Window,Worker)] interface WebSocket : EventTarget { constructor(USVString url, optional (DOMString or sequence