Skip to content
Tutorials Center
My learning

Topics

Lesson 20 of 36 ยท Scaling and Adapters

Sticky Sessions and Load Balancing

Configure sticky sessions for Socket.IO with nginx, HAProxy, cookies and IP hashing, and learn why long-polling breaks behind a round-robin balancer.

When you run several Socket.IO servers behind a load balancer, the balancer must send all requests of one client to the same server. If it spreads them round-robin, the handshake fails with Session ID unknown. This lesson shows exactly why, then walks through the usual ways to keep clients pinned: a cookie, a hash of the client IP, and the Node.js cluster helper.

The failure, step by step

A Socket.IO client that starts with long-polling makes these requests:

  1. GET /socket.io/?EIO=4&transport=polling returns the handshake, including a session id (sid).
  2. POST /socket.io/?EIO=4&transport=polling&sid=... sends data.
  3. GET /socket.io/?EIO=4&transport=polling&sid=... waits for data (long poll).
  4. An upgrade request to WebSocket, also carrying the sid.

Only the server that did step 1 knows the sid. Step 2 on another server fails.

Node.js Round-robin vs sticky routing (stand-in)

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Round-robin sends the handshake to A and the follow-up to B, which rejects it. The hash always chooses the same server for the same address.

Sticky strategies

Strategy How it works Good for Watch out for
Cookie Balancer sets a cookie naming the server Browsers, most setups Non-browser clients must keep cookies
IP hash Hash of the client address picks the server Simple, no cookies Many users behind one NAT land on one server
Header or sid Route on a request header or query value Custom gateways Needs balancer support

Cookie affinity spreads load better than IP hashing, because corporate networks and mobile carriers put thousands of users behind a single address. If you must use IP hashing, the shared address is where all of them go.

nginx

NGINX
upstream socket_nodes {
    ip_hash;                       # sticky by client IP
    server 10.0.0.11:3000;
    server 10.0.0.12:3000;
    server 10.0.0.13:3000;
}

server {
    listen 80;

    location /socket.io/ {
        proxy_pass http://socket_nodes;

        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_set_header Host $host;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    }
}

The Upgrade and Connection headers are required, or WebSocket upgrades fail and clients stay on polling. Open-source nginx has ip_hash and hash $cookie_name consistent; cookie-insert stickiness (sticky cookie) is a commercial feature.

HAProxy

TEXT
backend socket_nodes
    balance leastconn
    cookie SERVERID insert indirect nocache
    server s1 10.0.0.11:3000 check cookie s1
    server s2 10.0.0.12:3000 check cookie s2
    server s3 10.0.0.13:3000 check cookie s3

HAProxy inserts a SERVERID cookie on the first response. Later requests carry it, so the balancer always knows the target.

Cloud load balancers

Managed balancers have their own switch, usually called session affinity or stickiness: enable duration-based or application-cookie stickiness, and make sure the balancer supports WebSocket upgrades and uses an idle timeout longer than Socket.IO's heartbeat (default ping every 25 seconds). Otherwise the balancer closes idle connections that Socket.IO thinks are healthy.

One machine, many processes: @socket.io/sticky

When you use Node's cluster module, the workers share one listening port and the operating system hands connections to them, with no stickiness. The @socket.io/sticky package solves this inside your own application by routing each connection in the primary process:

JavaScript
import cluster from "node:cluster";
import { createServer } from "node:http";
import { availableParallelism } from "node:os";
import { Server } from "socket.io";
import { setupMaster, setupWorker } from "@socket.io/sticky";
import { createAdapter, setupPrimary } from "@socket.io/cluster-adapter";

if (cluster.isPrimary) {
  const httpServer = createServer();
  setupMaster(httpServer, { loadBalancingMethod: "least-connection" });
  setupPrimary();                       // lets workers talk through the primary
  httpServer.listen(3000);

  for (let i = 0; i < availableParallelism(); i++) cluster.fork();
} else {
  const httpServer = createServer();
  const io = new Server(httpServer);
  io.adapter(createAdapter());          // broadcasts cross worker boundaries
  setupWorker(io);                      // handshake and sticky routing
  io.on("connection", (socket) => { /* your handlers */ });
}

Three jobs, three calls: setupMaster routes connections, setupWorker accepts them, and the cluster adapter relays broadcasts between workers. The cluster adapter is described in cluster and alternative adapters.

WebSocket only: no stickiness needed

If you configure only the WebSocket transport on the client, the whole session is one TCP connection and the balancer never has a chance to split it:

JavaScript
const socket = io("https://chat.example.com", { transports: ["websocket"] });

The trade-off is that browsers behind proxies that block upgrades cannot connect at all, because there is no polling fallback. Many production apps accept this. If you do, remember that the load balancer still decides which server receives each new connection, and reconnection after a failure can land elsewhere. That is fine, as long as your design does not depend on the same node.

Node.js Which node gets a client? Hash distribution

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

The second line shows the weak point of IP hashing: one address means one node, no matter how many people sit behind it. Prefer cookies where you can.

Checklist for sticky deployments

  • Forward Upgrade and Connection headers.
  • Set the balancer idle/read timeout above pingInterval + pingTimeout (45 s by default); 60 seconds or more is typical.
  • Use an adapter, because stickiness alone does not make broadcasts cross servers.
  • Decide what happens when a server dies: clients reconnect, land on another node, and start a fresh session. See reliability and recovery.
  • Test with two instances locally before production.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What error does a server return when a polling request carries a sid it never issued?

    The session exists only in the process that did the handshake, so another process reports that the session id is unknown.
  2. 2. Why is cookie-based stickiness usually better than IP hashing?

    Hashing the address maps every user behind a shared address to the same node, which can overload it.
  3. 3. Which nginx headers must be forwarded for WebSocket upgrades?

    The proxy must pass the Upgrade header and set Connection to upgrade with HTTP/1.1, otherwise clients stay on polling.
  4. 4. What does @socket.io/sticky do?

    The primary process routes each connection to a worker, so polling requests of one client always reach the same worker.

Summary

  • Long-polling handshakes need every request of a session to hit the same server.
  • Use cookie affinity when possible, IP hash as a simpler fallback.
  • nginx needs HTTP/1.1 plus the Upgrade and Connection headers; keep timeouts above the heartbeat.
  • @socket.io/sticky provides stickiness for Node.js cluster.
  • WebSocket-only clients skip stickiness but lose the polling fallback.

Next: Redis Adapter and Pub/Sub