Scaling Socket.IO Horizontally: Why Your Real-Time Architecture Breaks Beyond a Single Process
DEV Community

Scaling Socket.IO Horizontally: Why Your Real-Time Architecture Breaks Beyond a Single Process

The Illusion of Single-Server Simplicity

WebSockets are the foundation of modern interactive web apps. Whether you are synchronizing live cursor movements in a collaborative canvas, streaming inference progress from a background AI job, pushing real-time order tracking updates, or delivering financial ticks, persistent full-duplex TCP connections make instant client updates trivial.

During early development, building these features with Socket.IO in Node.js feels seamless. You initialize an HTTP server, attach a Socket.IO instance, listen for incoming connections, and push updates using io.emit() or room-based targeting:

// A typical single-server broadcast
io
  .to("project:402")
  .emit("task_updated", { status: "completed" });

On a single development server, this works flawlessly. The server receives the update, locates all connected clients listening on project:402, and pushes the payload down their active TCP connections. However, this architecture relies on a silent, fragile assumption: every connected client lives in the same process memory.

The Bottleneck: Horizontal Scaling and Isolated Memory

A single Node.js process runs on a single thread and is bounded by operating system memory limits (typically 1.4 GB to 2 GB of V8 heap by default). As active concurrent connections grow from hundreds to tens of thousands, a single CPU core becomes a hard throughput bottleneck.

To scale, you do what every production engineer does: scale horizontally. You spin up multiple Node.js worker processes across multiple CPU cores using PM2 or Docker containers, placing them behind a reverse proxy like Nginx or an AWS Application Load Balancer. The moment you introduce that second server instance, your real-time communication silently breaks.

Node.js processes adhere strictly to a shared-nothing architecture. Process A and Process B inhabit isolated virtual memory spaces. They cannot inspect, access, or manipulate each other's data structures.

When Client A and Client B land on different instances:

  • Client A establishes a WebSocket connection routed by the load balancer to Node Instance 1. Instance 1 allocates a socket reference in its local heap memory.
  • Client B connects and is routed to Node Instance 2. Instance 2 records Client B in its own separate heap.

When Client A performs an action that triggers io.emit('event', payload) inside Instance 1, Instance 1 can only iterate over its own local registry. Instance 1 has no visibility into Instance 2. As a result, the event is dispatched to Client A (and anyone else attached to Instance 1), while Client B never receives the payload.

The exact same breakdown occurs with Socket.IO rooms (socket.join('room-name')). If two users join the same logical room on different physical servers, the room exists only as a local key in each server's memory map. Room broadcasts become completely siloed.

To scale real-time applications horizontally, servers cannot rely on local process memory as the source of truth for client communication. They require a centralized, high-throughput message bus that sits outside the application layer.

Reproducing the Breakdown Locally

To see why in-memory WebSocket architectures fail under horizontal scaling, you don't need a complex cloud cluster. You can reproduce the exact failure on localhost by running two instances of a basic Node.js server on different ports.

1. Project Setup

Initialize an isolated Node.js environment and configure it to use ES Modules:

mkdir socket-scaling-demo
cd socket-scaling-demo
npm init -y
npm pkg set type = "module"
npm install express socket.io socket.io-client

2. The Minimal Server (server.js)

Create a server.js file that reads a PORT environment variable, binds Socket.IO, and listens for a generic broadcast_event:

import http from " node:http " ;
import express from " express " ;
import { Server } from " socket.io " ;

const app = express ();
const server = http . createServer ( app );
const io = new Server ( server , {
  cors : { origin : " * " },
});

const PORT = process . env . PORT || 3001 ;
const INSTANCE_NAME = process . env . INSTANCE_NAME || `Instance- ${ PORT } ` ;

io . on ( " connection " , ( socket ) => {
  console . log ( `[ ${ INSTANCE_NAME } ] Client connected: ${ socket . id } ` );

  // When a client sends a message, attempt to broadcast it to all connected sockets
  socket . on ( " broadcast_event " , ( data ) => {
    console . log ( `[ ${ INSTANCE_NAME } ] Received broadcast request from ${ socket . id } :` , data , );
    // io.emit() should theoretically reach everyone
    io . emit ( " notification " , { origin : INSTANCE_NAME , sender : socket . id , payload : data , });
  });

  socket . on ( " disconnect " , () => {
    console . log ( `[ ${ INSTANCE_NAME } ] Client disconnected: ${ socket . id } ` );
  });
});

server . listen ( PORT , () => {
  console . log ( `>>> ${ INSTANCE_NAME } listening on http://localhost: ${ PORT } ` );
});

3. Spawning Two Isolated Server Instances

Open two separate terminal tabs and start two distinct instances representing two worker processes behind a load balancer:

Terminal 1 (Server Instance A): 

PORT = 3001
INSTANCE_NAME = "Server-A"
node server.js

Terminal 2 (Server Instance B): 

PORT = 3002
INSTANCE_NAME = "Server-B"
node server.js

Both instances are now live on your machine, bound to different network ports, and executing in completely segregated memory spaces.

4. Simulating Distributed Clients (test-clients.js)

Now create a test runner script (test-clients.js) to simulate two separate users. Client 1 connects to Server-A (:3001). Client 2 connects to Server-B (:3002).

import { io } from " socket.io-client " ;

// Client 1 lands on Server A
const client1 = io ( " http://localhost:3001 " , { transports : [ " websocket " ] });
// Client 2 lands on Server B
const client2 = io ( " http://localhost:3002 " , { transports : [ " websocket " ] });

client1 . on ( " connect " , () => {
  console . log ( `[Client 1] Connected to Server-A (ID: ${ client1 . id } )` );
});

client2 . on ( " connect " , () => {
  console . log ( `[Client 2] Connected to Server-B (ID: ${ client2 . id } )` );
});

// Listen for incoming notifications on both clients
client1 . on ( " notification " , ( msg ) => {
  console . log ( `[Client 1] Received notification:` , msg );
});

client2 . on ( " notification " , ( msg ) => {
  console . log ( `[Client 2] Received notification:` , msg );
});

// Wait 1 second for handshakes to settle, then emit an event from Client 1
setTimeout (() => {
  console . log ( ' \n >>> Client 1 emitting: "broadcast_event" -> "Task #402 Finished" \n ' , );
  client1 . emit ( " broadcast_event " , { task : " Task #402 Finished " });
}, 1000 );

Run the test runner in a third terminal:

node test-clients.js

5. The Result: Silent Event Dropping

Look closely at your terminal output:

[Client 1] Connected to Server-A (ID: Wk9vA8j_...)
[Client 2] Connected to Server-B (ID: gU4sZ2m_...)
>>> Client 1 emitting: "broadcast_event" -> "Task #402 Finished"

[Client 1] Received notification: { origin: 'Server-A', sender: 'Wk9vA8j_...', payload: { task: 'Task #402 Finished' } }

Client 1 receives its own reflected notification from Server-A, but Client 2 receives absolutely nothing.

Inspect Terminal 1 (Server-A):

[Server-A] Client connected: Wk9vA8j_...
[Server-A] Received broadcast request from Wk9vA8j_...: { task: 'Task #402 Finished' }

Inspect Terminal 2 (Server-B):

[Server-B] Client connected: gU4sZ2m_...
(Complete silence.)

Server-A did exactly what its code instructed: it queried its internal heap, found all sockets in its local memory pool (Wk9vA8j_...), and dispatched the TCP packet. It had no mechanism to notify Server-B that a global event occurred.

In a production environment where tens of thousands of users are randomly distributed across 10 container replicas, over 90% of your users will miss every broadcast event.

Redis as the Distributed Pub/Sub Backbone

To bridge the gap between isolated Node.js processes, we need a communication channel that operates outside application memory. The channel must be extremely fast-introducing less than a millisecond of overhead-so real-time events don't lag behind. This is where Redis comes in.

While developers commonly think of Redis as a key-value cache or a session store, Redis includes a native, lightweight messaging pattern: Publish/Subscribe (Pub/Sub).

Understanding Redis Pub/Sub in 60 Seconds

Redis Pub/Sub is a pure fire-and-forget message broker. It does not store messages on disk, track delivery status, or maintain historical logs:

  • Publishers send messages to named channels (e.g., PUBLISH channel_orders '{"id": 402}').
  • Subscribers listen on those channels (e.g., SUBSCRIBE channel_orders).
  • Whenever a message is published, Redis broadcasts a copy of that payload across the network to all connected subscribers in memory simultaneously.

Because Redis runs in C and keeps all channel mappings in memory, routing a packet between clients typically takes fractions of a millisecond.

The Default: Socket.IO's In-Memory Adapter

Under the hood, Socket.IO relies on an abstraction called an Adapter. Whenever you invoke a broadcast method:

io . emit ( " event " , payload );
// or
io . to ( " room-1 " ). emit ( " event " , payload );

Socket.IO does not execute the network writes directly. It passes the event, target room, and data to its default adapter: the socket.io-adapter.

The default adapter's implementation is straightforward: it maintains local JavaScript Map and Set instances containing all connected socket IDs and their associated rooms. It loops through those memory structures, finds the matching TCP sockets attached to that specific Node.js process, and writes the bytes out. If a client isn't in that local Map, the default adapter has no way to find or contact them.

The Fix: How @socket.io/redis-adapter Works

The official @socket.io/redis-adapter replaces the default in-memory adapter. Instead of confining event delivery to local memory, it turns every Node.js instance into both a Publisher and a Subscriber on Redis.

Here is the exact lifecycle of an event when the Redis adapter is active:

  1. The Interception - When you run io.emit('notification', payload) on Instance 1, the Redis adapter intercepts the call.
  2. The Redis Publish - Instead of only iterating over its local sockets, the adapter serializes the event name, packet arguments, and target room/namespace into a binary buffer or JSON payload. It pushes this packet to Redis using an active Redis Publish client: PUBLISH "socket.io#/#" <serialized_packet>.
  3. Channel Distribution - Redis receives the command and routes the serialized packet across every connection subscribed to that channel.
  4. The Ingestion & Local Dispatch - Instance 2 maintains a dedicated, persistent Redis Subscribe client. It catches the published packet from Redis, decodes the payload, checks the target room or namespace specified in the packet, inspects its own local process memory to see if any connected sockets match the criteria (in this case, Bob), and writes the data directly down Bob's TCP connection.

At the same time, Instance 1 processes the message for Alice through its own local socket map. Both clients receive the event in near-lockstep-regardless of which physical server, core, or container they originally connected to.

Why Two Redis Clients Are Required

When configuring the adapter in code, you will notice that it requires two separate Redis client connections:

const pubClient = new Redis ( REDIS_URL );
const subClient = pubClient . duplicate ();

This is an architectural requirement of the Redis protocol: Once a Redis connection issues a SUBSCRIBE command, that connection enters a dedicated subscriber state. While in subscriber mode, the connection cannot execute any other commands (such as PUBLISH, GET, or SET). It can only listen for incoming channel events or adjust subscriptions (UNSUBSCRIBE, PING).

Therefore, the adapter requires one dedicated connection strictly for listening (subClient), and a separate connection for pushing outgoing messages (pubClient).

Now that the distributed pub/sub mechanics are clear, we can implement the solution using Docker Compose and verify that our two isolated server instances communicate without dropping events.

Step-by-Step Implementation with Redis and Docker Compose

Now that the architecture is clear, we will wire up the Redis Pub/Sub adapter to fix the silent event-dropping issue demonstrated in Part 2. To keep the development environment clean and reproducible, we will spin up an isolated Redis container using Docker Compose, update our Node.js server to use @socket.io/redis-adapter, and rerun our multi-client test script.

Step 1: Install Required Dependencies

Inside your socket-scaling-demo directory, install the official Redis adapter and ioredis (the battle-tested Redis client for Node.js):

npm install @socket.io/redis-adapter ioredis

Step 2: Spin Up Redis with Docker Compose

Create a docker-compose.yml file in the root of your project:

services :
  redis :
    image : redis:7-alpine
    container_name : socket-redis-bus
    restart : always
    ports :
      - " 6379:6379"
    command : [ " redis-server" , " --appendonly" , " no" , " --save" , " " ]

Note on Flags: --appendonly no and --save "" disable disk persistence. Because Redis acts strictly as an in-memory Pub/Sub message bus here, turning off disk snapshots reduces CPU overhead and avoids unnecessary disk I/O.

Launch the Redis container in detached mode:

docker compose up -d

Verify the container is healthy:

docker compose ps

You should see socket-redis-bus running on port 6379.

Step 3: Upgrade server.js with the Redis Adapter

Open server.js and update it to mount the @socket.io/redis-adapter onto the Socket.IO instance before accepting connections:

import http from " node:http " ;
import express from " express " ;
import { Server } from " socket.io " ;
import { createAdapter } from
Read on DEV Community ↗ ← Back to News

Comments

No comments yet. Start the discussion.