@socket.io/sticky

A simple and performant way to use Socket.IO within a cluster.

Showing:

Popularity

Downloads/wk

818

GitHub Stars

16

Maintenance

Last Commit

3mos ago

Contributors

0

Package

Dependencies

0

License

MIT

Type Definitions

Tree-Shakeable

No?

Categories

Readme

Sticky sessions for Socket.IO

A simple and performant way to use Socket.IO within a cluster.

Unlike other packages like sticky-session, the routing is based on the session ID (the sid query parameter).

Cluster diagram

See also:

Table of contents

Installation

npm install @socket.io/sticky

Usage

const cluster = require("cluster");
const http = require("http");
const { Server } = require("socket.io");
const numCPUs = require("os").cpus().length;
const { setupMaster, setupWorker } = require("@socket.io/sticky");
const { createAdapter, setupPrimary } = require("@socket.io/cluster-adapter");

if (cluster.isMaster) {
  console.log(`Master ${process.pid} is running`);

  const httpServer = http.createServer();

  setupMaster(httpServer, {
    loadBalancingMethod: "least-connection", // either "random", "round-robin" or "least-connection"
  });

  setupPrimary();

  httpServer.listen(3000);

  for (let i = 0; i < numCPUs; i++) {
    cluster.fork();
  }

  cluster.on("exit", (worker) => {
    console.log(`Worker ${worker.process.pid} died`);
    cluster.fork();
  });
} else {
  console.log(`Worker ${process.pid} started`);

  const httpServer = http.createServer();
  const io = new Server(httpServer);
  io.adapter(createAdapter());
  setupWorker(io);

  io.on("connection", (socket) => {
    /* ... */
  });
}

How it works

The first HTTP request (without sid query parameter) is forwarded to a random worker (based on the loadBalancingMethod option).

The underlying Engine.IO server creates a new session and emits a connection event with the session ID. The worker sends this session ID to the master, which stores the relationship between the worker ID and the session ID.

For subsequent requests, the sid query parameter is extracted by the master process, which then forwards the handle to the right worker.

Notes

  • this package is not needed if you only use WebSockets (which might be a sensible choice as of 2021)
// client-side
const socket = io({
  transports: ["websocket"] // HTTP long-polling is disabled
});
  • in a multi-server setup, you will need to use another adapter, like the Redis adapter

Cluster diagram with Redis

  • this module is not compatible with an HTTPS server

For more information, please see this issue.

License

MIT

Rate & Review

Great Documentation0
Easy to Use0
Performant0
Highly Customizable0
Bleeding Edge0
Responsive Maintainers0
Poor Documentation0
Hard to Use0
Slow0
Buggy0
Abandoned0
Unwelcoming Community0
100