SocketCluster Server

Common errors

• ReferenceError: require is not defined

  cause Attempting to use CommonJS `require` syntax in an ES Module context without proper configuration.
  fix If running in an ES Module environment (e.g., `"type": "module"` in `package.json`), change import statements to `import * as socketClusterServer from 'socketcluster-server';` or configure your build tool for CommonJS compatibility.

• Client failed to connect: Invalid protocol version

  cause The client is attempting to connect using an older SocketCluster protocol version, but the server is expecting a newer one (or vice-versa).
  fix Enable compatibility mode on the server: `socketClusterServer.attach(httpServer, { protocolVersion: 1 });` or update your client to use a compatible `socketcluster-client` version and its default protocol.

• TypeError: agServer.listener is not a function

  cause This error likely indicates that `agServer` was not correctly initialized, or an incorrect method name was called, possibly due to an API change in major versions.
  fix Ensure `agServer` is correctly created using `socketClusterServer.attach(httpServer);` and that you are using the `listener()` method as shown in the v16+ documentation for async iterators.

• Error: listen EADDRINUSE: address already in use :::8000

  cause The specified port (e.g., 8000) for the HTTP server is already in use by another process or a previous instance of the server was not properly shut down.
  fix Change the `httpServer.listen()` port to an available one, or ensure no other applications are using the desired port. On Linux, `lsof -i :8000` can identify the process to terminate.

Warnings

• breaking Upgrading from SocketCluster Server v15.x or earlier to v16.x and above (including v20.0.0) involves a significant API shift from `EventEmitter` patterns to async iterators (`for-await-of` loops). Code relying on `on()`, `addListener()`, or `removeListener()` will need to be refactored.
  Fix: Migrate event handling logic to use `for await (const { socket } of agServer.listener('connection'))` and `for await (let req of socket.procedure('procName'))` patterns. Refer to the official v16.x documentation on socketcluster.io.
• gotcha To ensure compatibility with older SocketCluster clients (e.g., those using `socketcluster-client` v14.x or earlier), you must explicitly set `protocolVersion: 1` and potentially `path: '/socketcluster/'` during server attachment. Failure to do so will result in client connection errors.
  Fix: Configure `agServer` attachment with compatibility options: `let agServer = socketClusterServer.attach(httpServer, { protocolVersion: 1, path: '/socketcluster/' });`
• gotcha While `socketcluster-server` can operate independently, a complete real-time application setup typically requires `socketcluster-client` for browser or Node.js clients to connect and interact. For development and testing, both packages are generally needed to form a functional system.
  Fix: Install both packages: `npm install socketcluster-server socketcluster-client` and refer to `socketcluster-client` documentation for client-side setup.
• gotcha SocketCluster Server heavily leverages modern JavaScript features like `async/await` and `for-await-of` loops. Ensure your Node.js environment is sufficiently recent (e.g., Node.js 12+ for full compatibility) to avoid syntax errors or unexpected behavior.
  Fix: Use a recent LTS version of Node.js (e.g., Node.js 18 or 20) to ensure full compatibility with the async iterator paradigm and performance benefits.

Install

• npm install socketcluster-server npm
• yarn add socketcluster-server yarn
• pnpm add socketcluster-server pnpm

Imports

• socketClusterServer
  wrong:

  import socketClusterServer from 'socketcluster-server';

  correct:

  const socketClusterServer = require('socketcluster-server');

  Primary CommonJS import. For ESM, use `import * as socketClusterServer from 'socketcluster-server';` as the package exports an object. Direct `import socketClusterServer from 'socketcluster-server';` may not work as expected without a default export.
• AGServer
  wrong:

  import { AGServer } from 'socketcluster-server';

  correct:

  import type { AGServer } from 'socketcluster-server';

  Type import for the `agServer` instance returned by `attach()`. Used for TypeScript type-checking to ensure correct API usage.
• AGSocket
  wrong:

  import { AGSocket } from 'socketcluster-server';

  correct:

  import type { AGSocket } from 'socketcluster-server';

  Type import for individual `socket` instances obtained from `agServer.listener('connection')`. Essential for TypeScript type-checking when handling socket events.

Quickstart

Demonstrates how to attach SocketCluster server to an HTTP server and handle inbound connections, RPC procedures, and remote events using async iterators. It also shows transmitting a basic event to connected clients.

const http = require('http');
const socketClusterServer = require('socketcluster-server');

let httpServer = http.createServer();
let agServer = socketClusterServer.attach(httpServer);

(async () => {
  // Handle new inbound sockets.
  for await (let {socket} of agServer.listener('connection')) {

    (async () => {
      // Set up a loop to handle and respond to RPCs for a procedure.
      for await (let req of socket.procedure('customProc')) {
        if (!req.data) {
          let error = new Error('Server failed to execute the procedure');
          error.name = 'BadCustomError';
          req.error(error);
        } else {
          req.end('Success');
        }
      }
    })();

    (async () => {
      // Set up a loop to handle remote transmitted events.
      for await (let data of socket.receiver('customRemoteEvent')) {
        console.log(`Received customRemoteEvent: ${data}`);
      }
    })();

    socket.transmit('helloClient', { message: 'Hello from server!' });
  }
})();

httpServer.listen(8000, () => {
  console.log('SocketCluster Server listening on port 8000');
});