ws

https://github.com/websockets/ws
Admin
ws is a simple, fast, and thoroughly tested WebSocket client and server implementation for Node.js.
Tokens:63,518
Snippets:454
Trust Score:6.7
License:MIT
Update:1 day ago
Show doc for...
Tokens:
Raw
### Install ws via npm

Source: https://github.com/websockets/ws/blob/master/README.md

Use this command to install the ws module as a dependency for your Node.js project.

```bash
npm install ws
```

--------------------------------

### PerMessageDeflate compress/decompress usage example

Source: https://github.com/websockets/ws/blob/master/_autodocs/api-reference/permessage-deflate.md

Complete example showing how to instantiate PerMessageDeflate, negotiate parameters, compress and decompress a buffer, and clean up. Demonstrates the round-trip and error handling.

```javascript
const { PerMessageDeflate } = require('ws');
const pmd = new PerMessageDeflate({ isServer: true, serverNoContextTakeover: true });

const offer = pmd.offer(); // { server_no_context_takeover: true, client_max_window_bits: true }
pmd.accept([offer]);

pmd.compress(Buffer.from('hello'), true, (err, compressed) => {
  if (err) return console.error(err);
  pmd.decompress(compressed, true, (err, restored) => {
    console.log(restored.toString()); // 'hello'
    pmd.cleanup();
  });
});
```

--------------------------------

### Sender.send example with error handling

Source: https://github.com/websockets/ws/blob/master/_autodocs/api-reference/sender.md

Example of creating a Sender instance and sending a text message with fin and mask options, logging any write errors to the console.

```javascript
const sender = new Sender(socket);
sender.send('hello', { binary: false, fin: true, mask: false }, (err) => {
  if (err) console.error('write failed', err);
});
```

--------------------------------

### handleUpgrade with multiple servers sharing one HTTP server (README example)

Source: https://github.com/websockets/ws/blob/master/_autodocs/api-reference/websocket-server.md

Example from README.md, 'Multiple servers sharing a single HTTP/S server'. Shows routing upgrade requests by pathname to different WebSocketServer instances, destroying the socket for unknown paths.

```javascript
const server = http.createServer();
const wss1 = new WebSocketServer({ noServer: true });

server.on('upgrade', (request, socket, head) => {
  const { pathname } = new URL(request.url, 'wss://base.url');
  if (pathname === '/foo') {
    wss1.handleUpgrade(request, socket, head, (ws) => {
      wss1.emit('connection', ws, request);
    });
  } else {
    socket.destroy();
  }
});
server.listen(8080);
// Source: README.md, "Multiple servers sharing a single HTTP/S server"
```

--------------------------------

### Install bufferutil optional module

Source: https://github.com/websockets/ws/blob/master/README.md

Install bufferutil as an optional dependency to improve performance of masking and unmasking data payloads. Prebuilt binaries are available for most platforms, so a C++ compiler is not necessarily required.

```bash
npm install --save-optional bufferutil
```

--------------------------------

### wss.close() usage example

Source: https://github.com/websockets/ws/blob/master/_autodocs/api-reference/websocket-server.md

Example of calling close with a callback that logs 'server closed' when the server is closed.

```javascript
wss.close(() => console.log('server closed'));
```

--------------------------------

### handleUpgrade with session parsing (express-session-parse example)

Source: https://github.com/websockets/ws/blob/master/_autodocs/api-reference/websocket-server.md

Example from examples/express-session-parse/index.js showing manual handleUpgrade in noServer mode. It parses the session, checks for userId, writes a 401 response if missing, and otherwise calls handleUpgrade and emits 'connection'.

```javascript
const server = http.createServer(app);
const wss = new WebSocketServer({ clientTracking: false, noServer: true });

server.on('upgrade', (request, socket, head) => {
  socket.on('error', onSocketError);
  sessionParser(request, {}, () => {
    if (!request.session.userId) {
      socket.write('HTTP/1.1 401 Unauthorized\r\n\r\n');
      socket.destroy();
      return;
    }
    wss.handleUpgrade(request, socket, head, (ws) => {
      wss.emit('connection', ws, request);
    });
  });
});
// Source: examples/express-session-parse/index.js
```

--------------------------------

### Sender.ping example with callback

Source: https://github.com/websockets/ws/blob/master/_autodocs/api-reference/sender.md

Example of calling ping with a Buffer payload, mask set to true, and a callback that logs errors. Throws RangeError if payload exceeds 125 bytes.

```javascript
sender.ping(Buffer.from('hi'), true, (err) => {
  if (err) console.error(err);
});
```

--------------------------------

### ESM usage example with pipe

Source: https://github.com/websockets/ws/blob/master/_autodocs/api-reference/stream.md

Example using ESM import to create a duplex stream from a WebSocket, pipe stdin to the websocket, and print responses to stdout. Demonstrates the TCP-echo style usage.

```javascript
import WebSocket, { createWebSocketStream } from 'ws';

const ws = new WebSocket('wss://websocket-echo.com/');

const duplex = createWebSocketStream(ws, { encoding: 'utf8' });

duplex.on('error', console.error);

// TCP-echo style: pipe stdin to the websocket and print responses.
duplex.pipe(process.stdout);
process.stdin.pipe(duplex);
// Source: README.md, "Use the Node.js streams API"
```

--------------------------------

### Output structure of extension.parse()

Source: https://github.com/websockets/ws/blob/master/_autodocs/api-reference/extension.md

Example output structure of extension.parse(). Extensions are keyed by name, each value is an array of offer configurations, and each configuration is a map of parameter name to value (Number, String, or true for flags).

```json
{
  "permessage-deflate": [
    { "client_max_window_bits": true, "server_no_context_takeover": true }
  ]
}
```

--------------------------------

### Install utf-8-validate optional module (legacy)

Source: https://github.com/websockets/ws/blob/master/README.md

For Node.js versions prior to v18.14.0, install utf-8-validate as an optional dependency to provide a binary polyfill for buffer.isUtf8().

```bash
npm install --save-optional utf-8-validate
```

--------------------------------

### Custom masking key generation with Sender.frame()

Source: https://github.com/websockets/ws/blob/master/_autodocs/api-reference/sender.md

Shows how to provide a custom generateMask function that synchronously fills the mask buffer. The example uses a fixed key 'abcd' for demonstration.

```javascript
// Custom masking key generation (requires a synchronous fill):
const generateMask = (mask) => mask.set(Buffer.from('abcd'));
const [h] = Sender.frame('x', { opcode: 0x01, mask: true, generateMask });
```

--------------------------------

### CommonJS usage example with error handling

Source: https://github.com/websockets/ws/blob/master/_autodocs/api-reference/stream.md

Example using CommonJS require to create a duplex stream, with error handling for the stream and the websocket close event. Shows writing a buffer and ending the stream.

```javascript
const { WebSocket, createWebSocketStream } = require('ws');

const ws = new WebSocket('ws://localhost:8080');
const stream = createWebSocketStream(ws);

stream.on('error', (err) => {
  // Replacement for a missing 'error' listener: re-emitted here because the
  // internal listener removes itself before destroying (lib/stream.js:34-48).
  console.error('stream error:', err);
});
stream.on('end', () => console.log('websocket closed'));

stream.write(Buffer.from('hello'), (err) => {
  if (err) console.error('write failed', err);
});
stream.end();
```

--------------------------------

### Send a ping on 'open' event

Source: https://github.com/websockets/ws/blob/master/_autodocs/api-reference/websocket.md

Example of sending a ping with the payload 'heartbeat' when the WebSocket connection opens.

```javascript
ws.on('open', () => ws.ping('heartbeat'));
```

--------------------------------

### GET Catch-all 426 Upgrade Required (server side)

Source: https://github.com/websockets/ws/blob/master/_autodocs/endpoints.md

Returns a 426 Upgrade Required response for every non-upgrade request when the server was created with an internal HTTP server (port option).

```APIDOC
## [GET] Catch-all 426 Upgrade Required

### Description
Returns a 426 Upgrade Required response for every non-upgrade request when the server was created with an internal HTTP server (port option).

### Method
GET

### Endpoint
Any path (catch-all)

### Parameters
#### Path Parameters
- None

#### Query Parameters
- None

#### Request Headers
- None

### Request Example
(No request body)

### Response
#### Success Response (426)
- **Status** (number) - `426`
- **Body** (string) - `Upgrade Required`

#### Response Example
(No explicit example provided)

#### Error Responses
- None
```

--------------------------------

### Using subprotocol.parse to parse a header

Source: https://github.com/websockets/ws/blob/master/_autodocs/api-reference/subprotocol.md

Parses a comma-separated list of protocol names into a Set. The example shows that 'chat, superchat , chat.proto' results in a Set with 'chat', 'superchat', and 'chat.proto', and that the first value is 'chat'.

```javascript
const { subprotocol } = require('ws');

const protocols = subprotocol.parse('chat, superchat , chat.proto');
// Set { 'chat', 'superchat', 'chat.proto' }
const first = protocols.values().next().value; // 'chat'
```

--------------------------------

### new WebSocketServer(options[, callback])

Source: https://github.com/websockets/ws/blob/master/_autodocs/api-reference/websocket-server.md

Creates a new WebSocketServer instance. The options object must specify exactly one of port, server, or noServer. An optional callback is added as a listener for the 'listening' event when the port option is set.

```APIDOC
## new WebSocketServer(options[, callback])

### Description
Creates a new WebSocketServer instance. The options object must specify exactly one of `port`, `server`, or `noServer`. An optional callback is added as a listener for the `'listening'` event when the `port` option is set.

### Constructor
`new WebSocketServer(options[, callback])`

### Parameters
#### options (Object) - Required
Configuration options. See the full table in configuration.md. Exactly one of `options.port`, `options.server`, `options.noServer` must be provided.

#### callback (Function) - Optional
A listener for the `'listening'` event when the `port` option is set.

### Behavior
- When `port` is set, an internal HTTP server is created that responds `426 Upgrade Required` to every non-upgrade request, then bound with `listen(port, host, backlog, callback)`.
- When `server` is set, listeners for `'listening'`, `'error'`, and `'upgrade'` are attached to that pre-created server.
- When `clientTracking` is truthy (default), a `clients` property (a `Set` of connected `WebSocket` objects) is added.

### Throws
| Error | Condition |
|-------|-----------|
| `TypeError` | Not exactly one of `port`, `server`, `noServer` specified |
```

--------------------------------

### new WebSocketServer(options[, callback])

Source: https://github.com/websockets/ws/blob/master/_autodocs/configuration.md

Creates a new WebSocket server with the specified options. The options control server binding, connection validation, and WebSocket protocol behavior. Exactly one of port, server, or noServer must be set.

```APIDOC
## new WebSocketServer(options[, callback])

### Description
Creates a new WebSocket server. The options configure server binding, connection handling, and protocol features. Exactly one of `port`, `server`, or `noServer` must be set, otherwise a `TypeError` is thrown.

### Constructor
`new WebSocketServer(options[, callback])`

### Parameters
#### Options
- **allowSynchronousEvents** (Boolean) - Optional - Default: `true` - As client option.
- **autoPong** (Boolean) - Optional - Default: `true` - As client option.
- **backlog** (Number) - Optional - Default: `null` (net default 511) - Queue length of pending connections, passed to `listen()`.
- **clientTracking** (Boolean) - Optional - Default: `true` - Add a `clients` `Set` property; `false` skips tracking (see `noServer` examples).
- **closeTimeout** (Number) - Optional - Default: `30000` - As client option.
- **handleProtocols** (Function) - Optional - Default: `null` - `(protocols: Set, request) => protocolName|false`; returned value sets the `Sec-WebSocket-Protocol` response header; `false` omits it; default selects the first client offer.
- **host** (String) - Optional - Default: `null` - Hostname to bind the internally created server to.
- **maxBufferedChunks** (Number) - Optional - Default: `262144` - As client option.
- **maxFragments** (Number) - Optional - Default: `16384` - As client option.
- **maxPayload** (Number) - Optional - Default: `104857600` - As client option.
- **noServer** (Boolean) - Optional - Default: `false` - Detach the WebSocket server from any HTTP server; the caller must call `handleUpgrade()` manually.
- **path** (String) - Optional - Default: `null` - Accept only connections whose request pathname matches exactly.
- **perMessageDeflate** (Boolean|Object) - Optional - Default: `false` - Enable/disable permessage-deflate (disabled by default on the server).
- **port** (Number) - Optional - Default: `null` - Port to bind an internal HTTP server on (responds `426` to non-upgrade requests).
- **server** (http.Server|https.Server) - Optional - Default: `null` - A pre-created HTTP/S server to attach upgrade handling to.
- **skipUTF8Validation** (Boolean) - Optional - Default: `false` - As client option.
- **verifyClient** (Function) - Optional - Default: `null` - Validate incoming connections; 1-arg `(info) => Boolean` or 2-arg `(info, cb)` form. Usage discouraged.
- **WebSocket** (Function) - Optional - Default: `WebSocket` - The `WebSocket` class (or subclass) used for accepted connections; must extend the original.

### Constraints
Exactly one of `port`, `server`, `noServer` must be set, otherwise a `TypeError` is thrown.

### Callback
Optional callback invoked when the server is listening or an error occurs.

```

--------------------------------

### Event: 'open'

Source: https://github.com/websockets/ws/blob/master/doc/ws.md

Emitted when the connection is established.

```APIDOC
## Event: 'open'

### Description
Emitted when the connection is established.

### Event Name
`open`

### Listener Signature
No arguments.
```

--------------------------------

### pmd.accept(configurations) signature

Source: https://github.com/websockets/ws/blob/master/_autodocs/api-reference/permessage-deflate.md

Accepts an array of parsed extension offers or response parameters. Normalizes parameters and selects a configuration via acceptAsServer() or acceptAsClient(). Throws various errors for invalid parameters or unmatched offers.

```javascript
accept(configurations)
```

--------------------------------

### pmd.accept(configurations)

Source: https://github.com/websockets/ws/blob/master/_autodocs/api-reference/permessage-deflate.md

Normalizes and selects the permessage-deflate configuration based on the client/server offers and local options. Throws errors for invalid or unacceptable parameters.

```APIDOC
## pmd.accept(configurations)

### Description
Normalizes parameters (validating window bits are integers 8-15 and context-takeover flags are exactly `true`) and selects the configuration according to the local options via `acceptAsServer()` / `acceptAsClient()`. Returns the accepted params object, also stored in `pmd.params`.

### Method
accept

### Parameters
- **configurations** (Array) - Required - The offers (server side) or the response parameters (client side) parsed by `extension.parse()`.

### Returns
- **Object** - The accepted parameters object, also stored in `pmd.params`.

### Throws
| Error | Condition |
|-------|-----------|
| `Error` | `'None of the extension offers can be accepted'` (server could not match a client offer) |
| `Error` | `'Unexpected parameter "client_no_context_takeover"'` (client received the flag while disabled locally) |
| `Error` | `'Unexpected or invalid parameter "client_max_window_bits"'` |
| `Error` | `'Parameter "<key>" must have only a single value'` (repeated parameter in one config) |
| `TypeError` | `'Invalid value for parameter "<key>": <value>'` (window bits out of 8-15, non-boolean takeover flags, or `client_max_window_bits` not `true` on the client) |
| `Error` | `'Unknown parameter "<key>"'` |
```

--------------------------------

### PerMessageDeflate class declaration

Source: https://github.com/websockets/ws/blob/master/_autodocs/api-reference/permessage-deflate.md

Declares the PerMessageDeflate class. This is the starting point for the class implementation.

```javascript
class PerMessageDeflate {
```

--------------------------------

### websocket.binaryType

Source: https://github.com/websockets/ws/blob/master/doc/ws.md

Gets or sets the binary data type for received messages. Can be 'nodebuffer' or 'arraybuffer'.

```APIDOC
## websocket.binaryType

### Description
Gets or sets the binary data type for received messages. Can be 'nodebuffer' or 'arraybuffer'.

### Method
Property

### Endpoint
websocket.binaryType

### Parameters
None

### Response
#### Success Response
- **binaryType** (String) - The current binary type.

#### Response Example
```javascript
ws.binaryType = 'arraybuffer';
```
```

--------------------------------

### new Receiver([options])

Source: https://github.com/websockets/ws/blob/master/_autodocs/api-reference/receiver.md

Creates a new Receiver instance. Options control event timing, binary data type, extensions, server mode, and various limits.

```APIDOC
## new Receiver([options])

### Description
Creates a new Receiver instance. Options control event timing, binary data type, extensions, server mode, and various limits.

### Constructor
`new Receiver([options])`

### Parameters
#### Options
- **options.allowSynchronousEvents** (Boolean) - Optional - default `true` - Whether `'message'`, `'ping'`, `'pong'` events may be emitted synchronously during `write()`.
- **options.binaryType** (String) - Optional - default `'nodebuffer'` - One of `BINARY_TYPES`: `'nodebuffer'`, `'arraybuffer'`, `'fragments'` (plus `'blob'` if `Blob` exists).
- **options.extensions** (Object) - Optional - Negotiated extensions (used to look up `permessage-deflate` for RSV1 handling).
- **options.isServer** (Boolean) - Optional - default `false` - Server mode requires masked frames.
- **options.maxBufferedChunks** (Number) - Optional - default `0` (disabled) - Coerced with `| 0` to a 32-bit signed integer. Cap on buffered data chunks; `0` disables.
- **options.maxFragments** (Number) - Optional - default `0` - Cap on message fragments; `0` disables.
- **options.maxPayload** (Number) - Optional - default `0` - Cap on total message bytes (across fragments / after inflation); `0` disables.
- **options.skipUTF8Validation** (Boolean) - Optional - default `false`.

### Example
```js
const { Receiver } = require('ws');
const receiver = new Receiver({ isServer: true, maxPayload: 1024 });

receiver.on('message', (data, isBinary) => {
  console.log(isBinary ? 'binary: ' : 'text: ', data.toString());
});
receiver.on('error', (err) => console.error(err.code, err.message));

receiver.write(frameFromPeer);
```

```js
const receiver = new Receiver({ maxFragments: 16 });
receiver.on('error', (err) => {
  // err.code === 'WS_ERR_TOO_MANY_BUFFERED_PARTS', close code 1008
  closeWithCode(err[kStatusCode]); // (kStatusCode is a private symbol)
});
```
```

--------------------------------

### PerMessageDeflate.offer() method

Source: https://github.com/websockets/ws/blob/master/_autodocs/api-reference/permessage-deflate.md

Builds the extension parameters object offered in the Sec-WebSocket-Extensions request header. Maps camel-case options to wire names, e.g., serverNoContextTakeover to server_no_context_takeover.

```javascript
offer()
```

--------------------------------

### Pausing on message event

Source: https://github.com/websockets/ws/blob/master/_autodocs/api-reference/websocket.md

Example of pausing the WebSocket when a 'slow down' message is received, demonstrating the pause() method in a real event handler.

```javascript
ws.on('message', (data) => {
  if (data.toString() === 'slow down') ws.pause();
});
```

--------------------------------

### Handling SyntaxError from subprotocol.parse

Source: https://github.com/websockets/ws/blob/master/_autodocs/api-reference/subprotocol.md

Shows that a duplicate or invalid header throws a SyntaxError. The example catches the error and logs that it is a SyntaxError with message 'Unexpected end of input'.

```javascript
try {
  subprotocol.parse('chat,,');
} catch (err) {
  console.log(err instanceof SyntaxError); // true — 'Unexpected end of input'
}
```

--------------------------------

### Client authentication with ws and HTTP server upgrade

Source: https://github.com/websockets/ws/blob/master/README.md

Creates an HTTP server with a WebSocket server in noServer mode. The server's 'upgrade' event authenticates the request; on failure it responds with 401 and destroys the socket, on success it upgrades the connection and emits 'connection' with the client.

```JavaScript
import { createServer } from 'http';
import { WebSocketServer } from 'ws';

function onSocketError(err) {
  console.error(err);
}

const server = createServer();
const wss = new WebSocketServer({ noServer: true });

wss.on('connection', function connection(ws, request, client) {
  ws.on('error', console.error);

  ws.on('message', function message(data) {
    console.log(`Received message ${data} from user ${client}`);
  });
});

server.on('upgrade', function upgrade(request, socket, head) {
  socket.on('error', onSocketError);

  // This function is not defined on purpose. Implement it with your own logic.
  authenticate(request, function next(err, client) {
    if (err || !client) {
      socket.write('HTTP/1.1 401 Unauthorized\r\n\r\n');
      socket.destroy();
      return;
    }

    socket.removeListener('error', onSocketError);

    wss.handleUpgrade(request, socket, head, function done(ws) {
      wss.emit('connection', ws, request, client);
    });
  });
});

server.listen(8080);
```

--------------------------------

### websocket.readyState

Source: https://github.com/websockets/ws/blob/master/doc/ws.md

The current state of the connection. Use ready state constants for comparison.

```APIDOC
## websocket.readyState

### Description
The current state of the connection. Use ready state constants for comparison.

### Method
Property

### Endpoint
websocket.readyState

### Parameters
None

### Response
#### Success Response
- **readyState** (Number) - The current ready state.

#### Response Example
```javascript
console.log(ws.readyState);
```
```

--------------------------------

### Client WebSocket opening handshake (client side)

Source: https://github.com/websockets/ws/blob/master/_autodocs/endpoints.md

Issues the WebSocket opening handshake as an HTTP GET request, including required headers and validation of the server's response.

```APIDOC
## [GET] Client WebSocket opening handshake

### Description
Issues the WebSocket opening handshake as an HTTP GET request, including required headers and validation of the server's response.

### Method
GET

### Endpoint
(URL provided to the WebSocket constructor)

### Parameters
#### Path Parameters
- None

#### Query Parameters
- None

#### Request Headers
- **Upgrade** (string) - Required - `websocket`
- **Connection** (string) - Required - `Upgrade`
- **Sec-WebSocket-Key** (string) - Required - base64 of 16 random bytes (`randomBytes(16)`)
- **Sec-WebSocket-Version** (string) - Required - `options.protocolVersion` (8 or 13)
- **Sec-WebSocket-Protocol** (string) - Optional - Comma-joined requested protocols (when given)
- **Sec-WebSocket-Extensions** (string) - Optional - The permessage-deflate offer (when enabled, default)
- **Origin** / **Sec-WebSocket-Origin** (string) - Optional - When `options.origin` is set (protocolVersion < 13 → the latter)
- **Authorization** (string) - Optional - `Basic base64(user:pass)` when URL includes credentials and `followRedirects` is enabled

### Request Example
(No explicit example provided)

### Response
#### Success Response (101)
- **Upgrade** (string) - `websocket`
- **Connection** (string) - `Upgrade`
- **Sec-WebSocket-Accept** (string) - base64 of `SHA1(Sec-WebSocket-Key + GUID)`, `GUID = '258EAFA5-E914-47DA-95CA-C5AB0DC85B11'`
- **Sec-WebSocket-Protocol** (string) - Negotiated subprotocol (optional)
- **Sec-WebSocket-Extensions** (string) - Accepted extension parameters (optional)

#### Response Example
(No explicit example provided)

#### Error Responses
- Client-side handshake validation failures emit `'error'` then `'close'` with specific messages (details not provided in source).
```

--------------------------------

### Format a Sec-WebSocket-Extensions header with extension.format()

Source: https://github.com/websockets/ws/blob/master/_autodocs/api-reference/extension.md

Formats an extension configuration into a header string. Boolean true values become bare flags, and parameters are joined with '; '. The result is the inverse of parse().

```javascript
const { extension } = require('ws');
const { PerMessageDeflate } = require('ws');

const header = extension.format({
  'permessage-deflate': { server_no_context_takeover: true, client_max_window_bits: 12 }
});
// 'permessage-deflate; server_no_context_takeover; client_max_window_bits=12'
```

--------------------------------

### GET WebSocket handshake (server side)

Source: https://github.com/websockets/ws/blob/master/_autodocs/endpoints.md

Performs the WebSocket upgrade handshake. Validates required headers and upgrades the connection to a WebSocket on success, or returns an error response on failure.

```APIDOC
## [GET] WebSocket handshake

### Description
Performs the WebSocket upgrade handshake. Validates required headers and upgrades the connection to a WebSocket on success, or returns an error response on failure.

### Method
GET

### Endpoint
Any path matching `options.path` (when set) or any path at all (when unset, filtered by `server.shouldHandle(request)`).

### Parameters
#### Path Parameters
- None

#### Query Parameters
- None

#### Request Headers
- **Upgrade** (string) - Required - Must be `websocket` (case-insensitive).
- **Sec-WebSocket-Key** (string) - Required - Must match `/^[+/0-9A-Za-z]{22}==$/` (16-byte base64).
- **Sec-WebSocket-Version** (string) - Required - Must be `13` or `8`.
- **Sec-WebSocket-Protocol** (string) - Optional - Parsed into a set of token names.
- **Sec-WebSocket-Extensions** (string) - Optional - Parsed; only `permessage-deflate` offers are considered (when `perMessageDeflate` is enabled).
- **Origin** / **Sec-WebSocket-Origin** (string) - Optional - Surfaced to `verifyClient`.

### Request Example
(No request body; headers only)

### Response
#### Success Response (101)
- **Upgrade** (string) - `websocket`
- **Connection** (string) - `Upgrade`
- **Sec-WebSocket-Accept** (string) - base64 of `SHA1(Sec-WebSocket-Key + GUID)`, `GUID = '258EAFA5-E914-47DA-95CA-C5AB0DC85B11'`
- **Sec-WebSocket-Protocol** (string) - Negotiated subprotocol (optional)
- **Sec-WebSocket-Extensions** (string) - Accepted extension parameters (optional)

#### Response Example
(No explicit example provided)

#### Error Responses
- **405** - `Invalid HTTP method` - Method is not `GET`.
- **400** - `Invalid Upgrade header` - `Upgrade` missing or not `websocket`.
- **400** - `Missing or invalid Sec-WebSocket-Key header` - Key missing or failed regex.
- **400** - `Missing or invalid Sec-WebSocket-Version header` - Version not 13/8. Includes `Sec-WebSocket-Version: 13, 8` response header.
- **400** - `Bad Request` - `shouldHandle()` returned `false`.
- **400** - `Invalid Sec-WebSocket-Protocol header` - Subprotocol header unparseable.
- **400** - `Invalid or unacceptable Sec-WebSocket-Extensions header` - Extensions unparseable or unacceptable.
- **401** (or custom `code`) - `Unauthorized` (or custom `name`) + extra `headers` - `verifyClient` rejected the handshake.
- **503** - `Service Unavailable` - Upgrade arrives while server is `CLOSING`.
```

--------------------------------

### Catch SyntaxError from extension.parse() on malformed input

Source: https://github.com/websockets/ws/blob/master/_autodocs/api-reference/extension.md

Shows that malformed input throws a SyntaxError. The example uses an invalid parameter assignment and catches the error, logging true for instanceof SyntaxError.

```javascript
try {
  extension.parse('permessage-deflate; =broken');
} catch (err) {
  console.log(err instanceof SyntaxError); // true
}
```

--------------------------------

### server.address() method

Source: https://github.com/websockets/ws/blob/master/_autodocs/api-reference/websocket-server.md

Returns an object with `port`, `family`, and `address` properties as reported by the OS for IP sockets; the name as a string for pipes / UNIX domain sockets; `null` when there is no internal server. Throws `Error('The server is operating in "noServer" mode')` when constructed with `noServer: true`.

```js
address()
```

--------------------------------

### pause() and resume() methods

Source: https://github.com/websockets/ws/blob/master/_autodocs/api-reference/websocket.md

pause() stops event emission until buffered data is drained; resume() restarts it. Both are no-ops when the ready state is CONNECTING or CLOSED.

```javascript
pause()
resume()
```

--------------------------------

### Get client IP address from raw socket

Source: https://github.com/websockets/ws/blob/master/README.md

Shows how to obtain the remote IP address of a WebSocket client using req.socket.remoteAddress in a WebSocketServer connection handler. Includes error handling for the WebSocket.

```JavaScript
import { WebSocketServer } from 'ws';

const wss = new WebSocketServer({ port: 8080 });

wss.on('connection', function connection(ws, req) {
  const ip = req.socket.remoteAddress;

  ws.on('error', console.error);
});
```

--------------------------------

### new WebSocket(address[, protocols][, options])

Source: https://github.com/websockets/ws/blob/master/_autodocs/api-reference/websocket.md

Creates a new WebSocket client connection to the given address. Accepts optional subprotocols and connection options, and throws errors for invalid addresses or protocols.

```APIDOC
## new WebSocket(address[, protocols][, options])

### Description
Creates a new WebSocket client instance that connects to the specified address. Optional subprotocols and connection options may be provided.

### Constructor Signature
`new WebSocket(address, protocols, options)`

### Parameters
- **address** (String|URL) - Required - The URL to connect to. Allowed protocols: `ws:`, `wss:`, `http:` (normalized to `ws:`), `https:` (normalized to `wss:`), `ws+unix:` (IPC). A fragment identifier in the URL is rejected.
- **protocols** (String|Array) - Optional - Subprotocol names; validated against the token regex `/^[!#$%&'*+\-.0-9A-Z^_`|a-z~]+$/`. Passing an object as the second argument is treated as the options object.
- **options** (Object) - Optional - Connection options. Any option accepted by `http.request()` / `https.request()` is passed through, except those parsed from the URL (which take precedence).

### Throws
| Error | Condition |
|-------|-----------|
| `RangeError` | `options.protocolVersion` is not `8` or `13` |
| `SyntaxError` | Address cannot be parsed as a URL |
| `SyntaxError` | URL protocol is not `ws:`, `wss:`, `http:`, `https:`, or `ws+unix:` |
| `SyntaxError` | IPC URL with empty pathname, or URL containing a fragment identifier |
| `SyntaxError` | An invalid or duplicated subprotocol was specified |

### Usage Notes
- Creating an instance with `address === null` initializes a server-side connection (used internally by `WebSocketServer`).
- When `readyState` is `CONNECTING`: `send()`, `ping()`, `pong()` throw `Error('WebSocket is not open: readyState 0 (CONNECTING)')`; `close()` and `terminate()` abort the handshake with `'WebSocket was closed before the connection was established'`.

### Ready State Constants
The following constants are defined as enumerable class- and prototype-level constants:
- `WebSocket.CONNECTING` (0) - The connection is not yet open.
- `WebSocket.OPEN` (1) - The connection is open and ready to communicate.
- `WebSocket.CLOSING` (2) - The connection is in the process of closing.
- `WebSocket.CLOSED` (3) - The connection is closed.

```

--------------------------------

### new PerMessageDeflate([options])

Source: https://github.com/websockets/ws/blob/master/_autodocs/api-reference/permessage-deflate.md

Creates a new PerMessageDeflate instance with optional configuration options for compression behavior, such as window bits, context takeover, concurrency limit, and payload threshold.

```APIDOC
## new PerMessageDeflate([options])

### Description
Creates a new PerMessageDeflate instance with the given options.

### Constructor
`new PerMessageDeflate([options])`

### Parameters
#### Options
- **options** (Object) - Optional - Configuration options. See [configuration.md](../configuration.md#permessage-deflate-options) for the full table.
  - `clientMaxWindowBits` (number) - Optional - Client maximum window bits.
  - `clientNoContextTakeover` (boolean) - Optional - Whether to disable client context takeover.
  - `concurrencyLimit` (number) - Optional - Default: 10 - Global concurrency limit for compression operations.
  - `isServer` (boolean) - Optional - Whether this instance is used on the server side.
  - `maxPayload` (number) - Optional - Maximum payload size.
  - `serverMaxWindowBits` (number) - Optional - Server maximum window bits.
  - `serverNoContextTakeover` (boolean) - Optional - Whether to disable server context takeover.
  - `threshold` (number) - Optional - Default: 1024 - Payload size threshold for compression.
  - `zlibDeflateOptions` (Object) - Optional - Options for zlib deflate.
  - `zlibInflateOptions` (Object) - Optional - Options for zlib inflate.

### Notes
- The `concurrencyLimit` is global (a module-level `Limiter` shared by all instances) because the underlying issue is global thread-pool memory fragmentation on Node.js.
```

--------------------------------

### Get client IP behind a proxy using X-Forwarded-For

Source: https://github.com/websockets/ws/blob/master/README.md

When running behind a proxy like NGINX, extracts the client IP from the X-Forwarded-For header. Assumes the header is present and takes the first IP in the comma-separated list.

```JavaScript
wss.on('connection', function connection(ws, req) {
  const ip = req.headers['x-forwarded-for'].split(',')[0].trim();

  ws.on('error', console.error);
});
```

--------------------------------

### pmd.offer()

Source: https://github.com/websockets/ws/blob/master/_autodocs/api-reference/permessage-deflate.md

Builds the extension parameters object offered in the Sec-WebSocket-Extensions request header, mapping camel-case options to wire names.

```APIDOC
## pmd.offer()

### Description
Builds the extension parameters object offered in the `Sec-WebSocket-Extensions` request header.

### Method
`offer()`

### Returns
- **Object** - A plain object containing the offered extension parameters, e.g., `{ server_max_window_bits: 12 }`.

### Notes
- Maps camel-case options to wire names:
  - `serverNoContextTakeover` → `server_no_context_takeover`
  - `clientNoContextTakeover` → `client_no_context_takeover`
  - `serverMaxWindowBits` → `server_max_window_bits`
  - `clientMaxWindowBits` → `client_max_window_bits` (defaults to `true` when unset).
```

--------------------------------

### websocket.onopen

Source: https://github.com/websockets/ws/blob/master/doc/ws.md

Event handler for the 'open' event. Assign a function to handle connection open.

```APIDOC
## websocket.onopen

### Description
Event handler for the 'open' event. Assign a function to handle connection open.

### Method
Property

### Endpoint
websocket.onopen

### Parameters
None

### Response
#### Success Response
- **onopen** (Function) - The assigned event handler.

#### Response Example
```javascript
ws.onopen = () => {
  console.log('Connected');
};
```
```

--------------------------------

### extension.format(extensions)

Source: https://github.com/websockets/ws/blob/master/_autodocs/api-reference/extension.md

Builds a valid Sec-WebSocket-Extensions header field value from a map of extension configurations. This is the inverse of parse().

```APIDOC
## extension.format(extensions)

### Description
Builds a valid `Sec-WebSocket-Extensions` header field value from a map of extension name to configuration(s). This is the inverse of `parse()`.

### Method
format

### Parameters
- **extensions** (Object) - Required - A map of extension name → configuration(s). Each configuration is an object of parameter name → value (or array of values); boolean `true` values are serialized as bare flags.

### Returns
A string representing the formatted header field value.

### Example
```js
const { extension } = require('ws');

const header = extension.format({
  'permessage-deflate': { server_no_context_takeover: true, client_max_window_bits: 12 }
});
// 'permessage-deflate; server_no_context_takeover; client_max_window_bits=12'
```
```

--------------------------------

### Simple WebSocket server with ws WebSocketServer

Source: https://github.com/websockets/ws/blob/master/README.md

Creates a WebSocket server listening on port 8080. On connection, it logs incoming messages and sends a text response. Use for a minimal WebSocket server.

```JavaScript
import { WebSocketServer } from 'ws';

const wss = new WebSocketServer({ port: 8080 });

wss.on('connection', function connection(ws) {
  ws.on('error', console.error);

  ws.on('message', function message(data) {
    console.log('received: %s', data);
  });

  ws.send('something');
});
```

--------------------------------

### server.shouldHandle(request)

Source: https://github.com/websockets/ws/blob/master/doc/ws.md

Determines whether the server should handle the given upgrade request. Override this method to customize which requests are accepted.

```APIDOC
## server.shouldHandle(request)

### Description
Determines whether the server should handle the given upgrade request. Override this method to customize which requests are accepted.

### Method
Method

### Endpoint
server.shouldHandle(request)

### Parameters
#### Request
- **request** (http.IncomingMessage) - Required - The HTTP upgrade request.

### Response
#### Success Response
- **boolean** (Boolean) - `true` if the request should be handled, `false` otherwise.

#### Response Example
```javascript
wss.shouldHandle = (request) => {
  return request.url === '/ws';
};
```
```

--------------------------------

### Constructor signature: new Receiver([options])

Source: https://github.com/websockets/ws/blob/master/_autodocs/api-reference/receiver.md

Constructor for the Receiver class. Accepts an options object with properties like allowSynchronousEvents, binaryType, extensions, isServer, maxBufferedChunks, maxFragments, maxPayload, and skipUTF8Validation.

```javascript
constructor(options = {})
```

--------------------------------

### websocket.onopen

Source: https://github.com/websockets/ws/blob/master/doc/ws.md

An event listener to be called when the connection is established.

```APIDOC
## websocket.onopen

### Description
An event listener to be called when the connection is established. The listener receives an `OpenEvent` named "open".

### Type
{Function}
```

--------------------------------

### server.handleUpgrade(request, socket, head, callback)

Source: https://github.com/websockets/ws/blob/master/_autodocs/api-reference/websocket-server.md

Handles a WebSocket upgrade. Called automatically when the HTTP server is created internally or passed via `server`; must be called manually in `noServer` mode. Performs validation and invokes the callback on success.

```APIDOC
## server.handleUpgrade(request, socket, head, callback)

### Description
Handles a WebSocket upgrade. Called automatically when the HTTP server is created internally or passed via `server`; must be called manually in `noServer` mode. Performs validation checks and invokes the callback with the WebSocket and request on success. On failure, emits `'wsClientError'` if any listener is registered, otherwise writes an HTTP response directly to the socket.

### Method
N/A (method call)

### Endpoint
N/A

### Parameters
- **req** (http.IncomingMessage) - Required - The HTTP GET request.
- **socket** (stream.Duplex) - Required - The network socket.
- **head** (Buffer) - Required - The first packet of the upgraded stream.
- **cb** (Function) - Required - Called as `cb(websocket, request)` on success.

### Validation Checks
| # | Check | Failure response |
|---|-------|------------------|
| 1 | `req.method === 'GET'` | 405 `Invalid HTTP method` |
| 2 | `Upgrade: websocket` header | 400 `Invalid Upgrade header` |
| 3 | `Sec-WebSocket-Key` matches `/^[+/0-9A-Za-z]{22}==$/` | 400 `Missing or invalid Sec-WebSocket-Key header` |
| 4 | `Sec-WebSocket-Version` is `13` or `8` | 400 `Missing or invalid Sec-WebSocket-Version header` + `Sec-WebSocket-Version: 13, 8` |
| 5 | `shouldHandle(req)` | 400 |
| 6 | `Sec-WebSocket-Protocol` parses | 400 `Invalid Sec-WebSocket-Protocol header` |
| 7 | `Sec-WebSocket-Extensions` parses/acceptable | 400 `Invalid or unacceptable Sec-WebSocket-Extensions header` |
| 8 | optional `verifyClient` | 401 (or the `code` returned through the callback) |

### Request Example
```js
const server = http.createServer(app);
const wss = new WebSocketServer({ clientTracking: false, noServer: true });

server.on('upgrade', (request, socket, head) => {
  socket.on('error', onSocketError);
  sessionParser(request, {}, () => {
    if (!request.session.userId) {
      socket.write('HTTP/1.1 401 Unauthorized\r\n\r\n');
      socket.destroy();
      return;
    }
    wss.handleUpgrade(request, socket, head, (ws) => {
      wss.emit('connection', ws, request);
    });
  });
});
```

### Response
On success, the callback is invoked with the WebSocket and request. On failure, an HTTP error response is written to the socket or `'wsClientError'` is emitted.
```

--------------------------------

### Send data on open

Source: https://github.com/websockets/ws/blob/master/_autodocs/api-reference/websocket.md

Creates a WebSocket connection and sends data once the connection is open. Demonstrates sending a string and a binary TypedArray with the binary option. The error event is logged to the console.

```javascript
const ws = new WebSocket('ws://www.host.com/path');

ws.on('error', console.error);
ws.on('open', () => {
  ws.send('something');
  ws.send(new Float32Array(5), { binary: true });
});
```

--------------------------------

### websocket.readyState

Source: https://github.com/websockets/ws/blob/master/doc/ws.md

The current state of the connection. This is one of the ready state constants.

```APIDOC
## websocket.readyState

### Description
The current state of the connection. This is one of the ready state constants.

### Type
Number
```

--------------------------------

### server.address()

Source: https://github.com/websockets/ws/blob/master/doc/ws.md

Returns the bound address and port of the server. Useful for determining the actual port when using port 0.

```APIDOC
## server.address()

### Description
Returns the bound address and port of the server. Useful for determining the actual port when using port 0.

### Method
Method

### Endpoint
server.address()

### Parameters
None

### Response
#### Success Response
- **address** (Object) - An object with properties `address`, `family`, and `port`.

#### Response Example
```javascript
const wss = new WebSocketServer({ port: 0 });
console.log(wss.address()); // { address: '::', family: 'IPv6', port: 12345 }
```
```

--------------------------------

### websocket.send(data[, options][, callback])

Source: https://github.com/websockets/ws/blob/master/doc/ws.md

Sends data through the connection. This method throws an error if the ready state is CONNECTING.

```APIDOC
## websocket.send(data[, options][, callback])

### Description
Send `data` through the connection. This method throws an error if the ready state is `CONNECTING`.

### Method
send

### Parameters
- `data` (Array|Number|Object|String|ArrayBuffer|Buffer|DataView|TypedArray|Blob) - Required - The data to send. `Object` values are only supported if they conform to the requirements of [`Buffer.from()`][]. If those constraints are not met, a `TypeError` is thrown.
- `options` (Object) - Optional
  - `binary` (Boolean) - Optional - Specifies whether `data` should be sent as a binary or not. Default is autodetected.
  - `compress` (Boolean) - Optional - Specifies whether `data` should be compressed or not. Defaults to `true` when permessage-deflate is enabled.
  - `fin` (Boolean) - Optional - Specifies whether `data` is the last fragment of a message or not. Defaults to `true`.
  - `mask` (Boolean) - Optional - Specifies whether `data` should be masked or not. Defaults to `true` when `websocket` is not a server client.
- `callback` (Function) - Optional - An optional callback which is invoked when `data` is written out. If an error occurs, the callback is called with the error as its first argument.

### Response
No response body. The callback is invoked when `data` is written out.
```

--------------------------------

### server.address()

Source: https://github.com/websockets/ws/blob/master/doc/ws.md

Returns an object with port, family, and address properties specifying the bound address, the address family name, and port of the server as reported by the operating system if listening on an IP socket. If the server is listening on a pipe or UNIX domain socket, the name is returned as a string.

```APIDOC
## server.address()

### Description
Returns an object with `port`, `family`, and `address` properties specifying the bound address, the address family name, and port of the server as reported by the operating system if listening on an IP socket. If the server is listening on a pipe or UNIX domain socket, the name is returned as a string.

### Method
GET

### Endpoint
server.address()

### Response
#### Success Response
- **port** (Number) - The port number.
- **family** (String) - The address family name.
- **address** (String) - The bound address.

#### Response Example
{
  "port": 8080,
  "family": "IPv4",
  "address": "127.0.0.1"
}
```

--------------------------------

### handleUpgrade(req, socket, head, cb) signature

Source: https://github.com/websockets/ws/blob/master/_autodocs/api-reference/websocket-server.md

Signature for the handleUpgrade method. All parameters are required: req (http.IncomingMessage), socket (stream.Duplex), head (Buffer), and cb (Function).

```javascript
handleUpgrade(req, socket, head, cb)
```
Tokens:
Raw