WebSocket Transport (via ws)

The WebSocketTransport with its default options is going to be used automatically if no transport is provided. You may customize its options by providing a custom WebSocketTransport instance.

Example

import { defineServer } from "colyseus";
import { WebSocketTransport } from "@colyseus/ws-transport"
 
const server = defineServer({
  // ...
 
  transport: new WebSocketTransport({
    pingInterval: 6000,
    pingMaxRetries: 4,
    maxPayload: 1024 * 1024 * 1, // 1MB Max Payload
  }),
 
  // ...
});

Available options

options.server

A Node.js http server instance to re-use for the WebSocket server. Useful when you’d like to use Express along with Colyseus.

import { createServer } from "http";
import { defineServer } from "@colyseus/core";
import { WebSocketTransport } from "@colyseus/ws-transport"
 
const httpServer = createServer(); // create the http server manually
 
const server = defineServer({
  transport: new WebSocketTransport({
    server: httpServer // provide the custom server for `WebSocketTransport`
  })
});

import express from "express";
import { createServer } from "http";
import { defineServer } from "@colyseus/core";
import { WebSocketTransport } from "@colyseus/ws-transport"
 
const app = express();
const httpServer = createServer(app); // create the http server manually
 
const server = defineServer({
  transport: new WebSocketTransport({
    server: httpServer // provide the custom server for `WebSocketTransport`
  })
});

By not providing this option, an http server is going to be created automatically for you.

options.pingInterval

Number of milliseconds for the server to “ping” the clients.

The clients are going to be forcibly disconnected if they can’t respond after pingMaxRetries retries.

Default: 3000

options.pingMaxRetries

Maximum allowed number of pings without a response.

Default: 2

options.maxPayload

Maximum payload clients can send per message to the server.

Default: 4096 (4kb)

options.perMessageDeflate

Enable/disable per-message deflate compression. Disabling this can reduce CPU usage and latency at the cost of increased bandwidth.

Default: false

options.beforeUpgrade

Runs before the WebSocket handshake, while the connection is still a plain HTTP request.

beforeUpgrade?: (request: Request, context: AuthContext) => Response | void | Promise<Response | void>;

The callback receives the upgrade request as a standard Request, and the same context object onAuth receives: token, headers, and ip. The context is read-only here, and changes to it do not carry over to onAuth.

Return a Response to answer the request without upgrading, or nothing to accept the handshake. The callback may be async, and the handshake waits for it to resolve.

A callback that throws answers 500 Internal Server Error, and the connection is not upgraded.

verifyClient covers the accept-or-reject case on this transport. beforeUpgrade answers with a full Response, and behaves the same way on every WebSocket transport.

options.verifyClient

This method happens before WebSocket handshake. If verifyClient is not set then the handshake is automatically accepted.

• info (Object)

  • origin (String) The value in the Origin header indicated by the client.
  • req (http.IncomingMessage) The client HTTP GET request.
  • secure (Boolean) true if req.connection.authorized or req.connection.encrypted is set.

• next (Function) A callback that must be called by the user upon inspection of the info fields. Arguments in this callback are:

  • result (Boolean) Whether or not to accept the handshake.
  • code (Number) When result is false this field determines the HTTP error status code to be sent to the client.
  • name (String) When result is false this field determines the HTTP reason phrase.

Troubleshooting

431 Request Header Fields Too Large

The maximum header size is 16 KiB by default. If you need to increase the maximum header size, you can use the NODE_OPTIONS environment variable:

NODE_OPTIONS="--max-http-header-size=32768"