ws

The readyState property of a WebSocket instance indicates the current state of the connection. Use these constants to check if a connection is ready for communication:

• CONNECTING (0): The connection is not yet open.
• OPEN (1): The connection is open and ready to communicate.
• CLOSING (2): The connection is in the process of closing.
• CLOSED (3): The connection is closed.

The permessage-deflate extension enables compression for WebSocket messages. It is enabled by default on the client and disabled by default on the server.

Warning: Compression adds significant memory and performance overhead. On Linux, high concurrency with compression can lead to memory fragmentation in Node.js/zlib. Use with caution in production.

To disable compression on the client, set perMessageDeflate: false in the constructor options.

import WebSocket, { WebSocketServer } from 'ws';

const wss = new WebSocketServer({
  port: 8080,
  perMessageDeflate: {
    zlibDeflateOptions: {
      chunkSize: 1024,
      memLevel: 7,
      level: 3
    },
    zlibInflateOptions: {
      chunkSize: 10 * 1024
    },
    clientNoContextTakeover: true,
    serverNoContextTakeover: true,
    serverMaxWindowBits: 10,
    concurrencyLimit: 10,
    threshold: 1024
  }
});

To improve the performance of masking and unmasking WebSocket frame payloads, you can install the optional bufferutil binary addon. Prebuilt binaries are available for most platforms.

To force ws to NOT use bufferutil, set the WS_NO_BUFFER_UTIL environment variable.

npm install --save-optional bufferutil

Install the ws library using npm:

npm install ws

To obtain the remote IP address of a connecting client, access the remoteAddress property from the raw socket attached to the req (request) object in the connection event.

If your server is running behind a proxy (such as NGINX), the client's IP is typically provided in the X-Forwarded-For header. You should parse this header to retrieve the original client IP.

import { WebSocketServer } from 'ws';

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

// Direct access via raw socket
wss.on('connection', function connection(ws, req) {
  const ip = req.socket.remoteAddress;
  ws.on('error', console.error);
});

// Access via proxy header (e.g., NGINX)
wss.on('connection', function connection(ws, req) {
  const ip = req.headers['x-forwarded-for'].split(',')[0].trim();
  ws.on('error', console.error);
});

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

To force ws to NOT use utf-8-validate, set the WS_NO_UTF_8_VALIDATE environment variable.

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

The ws library supports Inter-Process Communication (IPC) connections using specific URL formats.

On Unices:

ws+unix:/absolute/path/to/uds_socket:/pathname?search_params

On Windows:

ws+unix:\\.\\pipe\\pipe_name:/pathname?search_params

Note: The : character separates the IPC path from the URL path. If the URL path is omitted, it defaults to /.

You can control whether ws attempts to use certain optional performance-enhancing dependencies by setting the following environment variables to any non-empty value:

• WS_NO_BUFFER_UTIL: Prevents the bufferutil dependency from being required.
• WS_NO_UTF_8_VALIDATE: Prevents the utf-8-validate dependency from being required.

# Example: Running without bufferutil and utf-8-validate
WS_NO_BUFFER_UTIL=1 WS_NO_UTF_8_VALIDATE=1 node app.js

To enable compression, set perMessageDeflate to true or provide an object with specific parameters:

• serverNoContextTakeover {Boolean}: Whether to use context takeover.
• clientNoContextTakeover {Boolean}: Acknowledge disabling of client context takeover.
• serverMaxWindowBits {Number}: The value of windowBits.
• clientMaxWindowBits {Number}: Request a custom client window size.
• zlibDeflateOptions {Object}: Options to pass to zlib on deflate.
• zlibInflateOptions {Object}: Options to pass to zlib on inflate.
• threshold {Number}: Payloads smaller than this (default 1024) won't be compressed if context takeover is disabled.
• concurrencyLimit {Number}: Number of concurrent zlib calls (default 10).