{"slug": "scaling-socket-io-horizontally-why-your-real-time-architecture-breaks-beyond-a", "title": "Scaling Socket.IO Horizontally: Why Your Real-Time Architecture Breaks Beyond a Single Process", "summary": "A developer demonstrates why Socket.IO real-time architectures break when scaled horizontally beyond a single Node.js process, since each instance's shared-nothing memory means broadcasts and room joins only reach clients connected to that same process. The writeup shows how to reproduce the failure locally by running two server instances on different ports, and argues that horizontally scaled real-time apps require a centralized message bus outside the application layer.", "body_md": "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.\n\nDuring 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:\n\n```\n// A typical single-server broadcast\nio.to(\"project:402\").emit(\"task_updated\", { status: \"completed\" });\n```\n\nOn 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.\n\nHowever, this architecture relies on a silent, fragile assumption: **every connected client lives in the same process memory.**\n\nA 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.\n\nTo 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.\n\nThe moment you introduce that second server instance, your real-time communication silently breaks.\n\nNode.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.\n\nWhen Client A and Client B land on different instances:\n\nClient 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.\n\nClient B connects and is routed to Node Instance 2. Instance 2 records Client B in its own separate heap.\n\nWhen Client A performs an action that triggers `io.emit('event', payload)` inside Instance 1, Instance 1 can only iterate over its own local registry.\n\nInstance 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.\n\nThe 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.\n\nTo 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.\n\nTo 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.\n\nInitialize an isolated Node.js environment and configure it to use ES Modules:\n\n```\nmkdir socket-scaling-demo\ncd socket-scaling-demo\nnpm init -y\nnpm pkg set type=\"module\"\nnpm install express socket.io socket.io-client\n```\n\n`server.js`)\nCreate a `server.js` file that reads a `PORT` environment variable, binds Socket.IO, and listens for a generic `broadcast_event`:\n\n``` python\nimport http from \"node:http\";\nimport express from \"express\";\nimport { Server } from \"socket.io\";\n\nconst app = express();\nconst server = http.createServer(app);\n\nconst io = new Server(server, {\n  cors: { origin: \"*\" },\n});\n\nconst PORT = process.env.PORT || 3001;\nconst INSTANCE_NAME = process.env.INSTANCE_NAME || `Instance-${PORT}`;\n\nio.on(\"connection\", (socket) => {\n  console.log(`[${INSTANCE_NAME}] Client connected: ${socket.id}`);\n\n  // When a client sends a message, attempt to broadcast it to all connected sockets\n  socket.on(\"broadcast_event\", (data) => {\n    console.log(\n      `[${INSTANCE_NAME}] Received broadcast request from ${socket.id}:`,\n      data,\n    );\n\n    // io.emit() should theoretically reach everyone\n    io.emit(\"notification\", {\n      origin: INSTANCE_NAME,\n      sender: socket.id,\n      payload: data,\n    });\n  });\n\n  socket.on(\"disconnect\", () => {\n    console.log(`[${INSTANCE_NAME}] Client disconnected: ${socket.id}`);\n  });\n});\n\nserver.listen(PORT, () => {\n  console.log(`>>> ${INSTANCE_NAME} listening on http://localhost:${PORT}`);\n});\n```\n\nOpen two separate terminal tabs and start two distinct instances representing two worker processes behind a load balancer:\n\n```\nPORT=3001 INSTANCE_NAME=\"Server-A\" node server.js\nPORT=3002 INSTANCE_NAME=\"Server-B\" node server.js\n```\n\nBoth instances are now live on your machine, bound to different network ports, and executing in completely segregated memory spaces.\n\n`test-clients.js`)\nNow create a test runner script (`test-clients.js`) to simulate two separate users.\n\nClient 1 connects to Server-A (`:3001`).\n\nClient 2 connects to Server-B (`:3002`).\n\n``` js\nimport { io } from \"socket.io-client\";\n\n// Client 1 lands on Server A\nconst client1 = io(\"http://localhost:3001\", { transports: [\"websocket\"] });\n\n// Client 2 lands on Server B\nconst client2 = io(\"http://localhost:3002\", { transports: [\"websocket\"] });\n\nclient1.on(\"connect\", () => {\n  console.log(`[Client 1] Connected to Server-A (ID: ${client1.id})`);\n});\n\nclient2.on(\"connect\", () => {\n  console.log(`[Client 2] Connected to Server-B (ID: ${client2.id})`);\n});\n\n// Listen for incoming notifications on both clients\nclient1.on(\"notification\", (msg) => {\n  console.log(`[Client 1] Received notification:`, msg);\n});\n\nclient2.on(\"notification\", (msg) => {\n  console.log(`[Client 2] Received notification:`, msg);\n});\n\n// Wait 1 second for handshakes to settle, then emit an event from Client 1\nsetTimeout(() => {\n  console.log(\n    '\\n>>> Client 1 emitting: \"broadcast_event\" -> \"Task #402 Finished\"\\n',\n  );\n  client1.emit(\"broadcast_event\", { task: \"Task #402 Finished\" });\n}, 1000);\nnode test-clients.js\n```\n\nLook closely at your terminal output:\n\n```\n[Client 1] Connected to Server-A (ID: Wk9vA8j_...)\n[Client 2] Connected to Server-B (ID: gU4sZ2m_...)\n\n>>> Client 1 emitting: \"broadcast_event\" -> \"Task #402 Finished\"\n\n[Client 1] Received notification: {\n  origin: 'Server-A',\n  sender: 'Wk9vA8j_...',\n  payload: { task: 'Task #402 Finished' }\n}\n```\n\nClient 1 receives its own reflected notification from Server-A, but Client 2 receives absolutely nothing.\n\n```\n[Server-A] Client connected: Wk9vA8j_...\n[Server-A] Received broadcast request from Wk9vA8j_...: { task: 'Task #402 Finished' }\n[Server-B] Client connected: gU4sZ2m_...\n```\n\n(Complete silence.)\n\n`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.\n\nIn 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.**\n\nTo 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.\n\nThis is where **Redis** comes in.\n\nWhile 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)**.\n\nRedis Pub/Sub is a pure fire-and-forget message broker. It does not store messages on disk, track delivery status, or maintain historical logs:\n\nPublishers send messages to named channels (e.g., `PUBLISH channel_orders '{\"id\": 402}'`).\n\nSubscribers listen on those channels (e.g., `SUBSCRIBE channel_orders`).\n\nWhenever a message is published, Redis broadcasts a copy of that payload across the network to **all connected subscribers in memory simultaneously**.\n\nBecause Redis runs in C and keeps all channel mappings in memory, routing a packet between clients typically takes fractions of a millisecond.\n\nUnder the hood, Socket.IO relies on an abstraction called an Adapter.\n\n```\nio.emit(\"event\", payload);\n// or\nio.to(\"room-1\").emit(\"event\", payload);\n```\n\nSocket.IO does not execute the network writes directly. It passes the event, target room, and data to its default adapter: the `socket.io-adapter`.\n\nThe 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.\n\nIf a client isn't in that local `Map`, the default adapter has no way to find or contact them.\n\n`@socket.io/redis-adapter` Works\nThe 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.\n\nHere is the exact lifecycle of an event when the Redis adapter is active:\n\nWhen you run `io.emit('notification', payload)` on Instance 1, the Redis adapter intercepts the call.\n\nInstead 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:**\n\n```\nPUBLISH \"socket.io#/#\" <serialized_packet>\n```\n\nRedis receives the command and routes the serialized packet across every connection subscribed to that channel.\n\n**Instance 2** maintains a dedicated, persistent **Redis Subscribe client**. It catches the published packet from Redis:\n\nInstance 2 decodes the payload.\n\nIt checks the target room or namespace specified in the packet.\n\nIt inspects **its own local process memory** to see if any connected sockets match the criteria (in this case, Bob).\n\nFinding Bob's active socket, Instance 2 writes the data directly down Bob's TCP connection.\n\nAt 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.\n\nWhen configuring the adapter in code, you will notice that it requires two separate Redis client connections:\n\n``` js\nconst pubClient = new Redis(REDIS_URL);\nconst subClient = pubClient.duplicate();\n```\n\nThis is an architectural requirement of the Redis protocol:\n\nOnce a Redis connection issues a `SUBSCRIBE` command, that connection enters a dedicated subscriber state.\n\nWhile 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`).\n\nTherefore, the adapter requires one dedicated connection strictly for listening (`subClient`), and a separate connection for pushing outgoing messages (` pubClient`).\n\nNow 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.\n\nNow 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.\n\nTo 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.\n\nInside your `socket-scaling-demo` directory, install the official Redis adapter and `ioredis` (the battle-tested Redis client for Node.js):\n\n```\nnpm install @socket.io/redis-adapter ioredis\n```\n\nCreate a `docker-compose.yml` file in the root of your project:\n\n```\nservices:\n  redis:\n    image: redis:7-alpine\n    container_name: socket-redis-bus\n    restart: always\n    ports:\n      - \"6379:6379\"\n    command: [\"redis-server\", \"--appendonly\", \"no\", \"--save\", \"\"]\n```\n\n`--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.\nLaunch the Redis container in detached mode:\n\n```\ndocker compose up -d\n```\n\nVerify the container is healthy:\n\n```\ndocker compose ps\n```\n\nYou should see `socket-redis-bus` running on port `6379`.\n\nOpen `server.js` and update it to mount the `@socket.io/redis-adapter` onto the Socket.IO instance before accepting connections:\n\n``` python\nimport http from \"node:http\";\nimport express from \"express\";\nimport { Server } from \"socket.io\";\nimport { createAdapter } from \"@socket.io/redis-adapter\";\nimport Redis from \"ioredis\";\n\nconst app = express();\nconst server = http.createServer(app);\n\n// 1. Establish Redis Publisher and Subscriber connections\nconst REDIS_URL = process.env.REDIS_URL || \"redis://127.0.0.1:6379\";\n\nconst pubClient = new Redis(REDIS_URL, {\n  maxRetriesPerRequest: null,\n  enableReadyCheck: false,\n});\n\n// A subscribed connection cannot execute other commands, so duplicate it\nconst subClient = pubClient.duplicate();\n\n// 2. Attach Socket.IO and bind the Redis Adapter\nconst io = new Server(server, {\n  cors: { origin: \"*\" },\n  adapter: createAdapter(pubClient, subClient),\n});\n\nconst PORT = process.env.PORT || 3001;\nconst INSTANCE_NAME = process.env.INSTANCE_NAME || `Instance-${PORT}`;\n\nio.on(\"connection\", (socket) => {\n  console.log(`[${INSTANCE_NAME}] Client connected: ${socket.id}`);\n\n  socket.on(\"broadcast_event\", (data) => {\n    console.log(\n      `[${INSTANCE_NAME}] Received broadcast request from ${socket.id}:`,\n      data,\n    );\n\n    // io.emit() is now intercepted by the Redis adapter and published to the Redis bus\n    io.emit(\"notification\", {\n      origin: INSTANCE_NAME,\n      sender: socket.id,\n      payload: data,\n    });\n  });\n\n  socket.on(\"disconnect\", () => {\n    console.log(`[${INSTANCE_NAME}] Client disconnected: ${socket.id}`);\n  });\n});\n\nserver.listen(PORT, () => {\n  console.log(`>>> ${INSTANCE_NAME} listening on http://localhost:${PORT}`);\n});\n```\n\nKill any previous running server processes (Ctrl + C) and start both instances again in their respective terminal tabs:\n\n```\nPORT=3001 INSTANCE_NAME=\"Server-A\" node server.js\nPORT=3002 INSTANCE_NAME=\"Server-B\" node server.js\n```\n\nBoth instances are now connected to the local Redis instance on port `6379` and actively subscribed to the default channel prefix (`socket.io#/#`).\n\nNow execute the exact same client test script we wrote in Part 2 (`test-clients.js`):\n\n```\nnode test-clients.js\n```\n\nRecall that:\n\n**Client 1** emits the broadcast_event with payload { task: 'Task #402 Finished' }.\n\n```\n[Client 1] Connected to Server-A (ID: Xk7_q9Lm...)\n[Client 2] Connected to Server-B (ID: 9Rt2_vKp...)\n\n>>> Client 1 emitting: \"broadcast_event\" -> \"Task #402 Finished\"\n\n[Client 1] Received notification: {\n  origin: 'Server-A',\n  sender: 'Xk7_q9Lm...',\n  payload: { task: 'Task #402 Finished' }\n}\n\n[Client 2] Received notification: {\n  origin: 'Server-A',\n  sender: 'Xk7_q9Lm...',\n  payload: { task: 'Task #402 Finished' }\n}\n```\n\n**Client 2** now receives the notification immediately.\n\nLet's inspect what happened across all processes:\n\n**Client 1** sent the event packet over TCP to **Server-A**.\n\nServer-A’s adapter intercepted the `io.emit()` call and published the payload to Redis.\n\nRedis broadcast the message to all subscribed clients on that channel in less than 1 millisecond.\n\n**Server-B** received the payload via its `subClient`, inspected its local socket table, found **Client 2**, and pushed the event down Client 2's TCP connection.\n\nWithout changing a single line of client-side code, your real-time infrastructure is now capable of scaling horizontally across any number of container instances.\n\nSetting up `@socket.io/redis-adapter` on a local environment solves cross-process event synchronization, but deploying this architecture into production (behind reverse proxies, load balancers, or Kubernetes clusters) introduces three distinct operational challenges.\n\nIf you don't account for these edge cases, your cluster will suffer from handshake drops, random HTTP 400 errors, and memory leaks.\n\nBy default, Socket.IO does not establish a raw WebSocket connection immediately. It initiates an HTTP long-polling handshake first (`GET /socket.io/?EIO=4&transport=polling`) before attempting to upgrade the protocol to WebSockets.\n\nThis introduces a race condition when sitting behind a standard round-robin load balancer (like AWS ALB, Nginx, or Cloudflare):\n\nIf you want to keep HTTP long-polling enabled for fallback compatibility with legacy corporate networks, your load balancer must use sticky cookies (cookie-based session affinity) so that requests with the same session cookie consistently hit the same backend container during the handshake.\n\nIn an Nginx reverse proxy, you configure this using the `ip_hash` directive or cookie-based routing:\n\n```\nupstream socket_cluster {\n    ip_hash; # Routes the same client IP to the same upstream container\n    server 127.0.0.1:3001;\n    server 127.0.0.1:3002;\n}\n\nserver {\n    listen 80;\n\n    location /socket.io/ {\n        proxy_pass http://socket_cluster;\n        proxy_http_version 1.1;\n        proxy_set_header Upgrade $http_upgrade;\n        proxy_set_header Connection \"upgrade\";\n        proxy_set_header Host $host;\n    }\n}\n```\n\nIf you control both the frontend and backend clients (modern web apps, mobile applications, or internal microservices), you can skip the HTTP long-polling handshake entirely.\n\nBy forcing Socket.IO to initiate directly via WebSockets, the TCP handshake occurs in a single network round-trip. Because persistent TCP connections remain pinned to the specific server instance that accepted the connection, you no longer need sticky sessions on your load balancer.\n\n``` js\n// Force immediate WebSocket connection (No HTTP polling)\nconst socket = io(\"https://api.yourdomain.com\", {\n  transports: [\"websocket\"],\n  upgrade: false,\n});\njs\nconst io = new Server(server, {\n  cors: { origin: \"*\" },\n  transports: [\"websocket\"], // Disable polling on the server\n  adapter: createAdapter(pubClient, subClient),\n});\n```\n\nBecause Node.js is single-threaded, an unhandled error on an event emitter can crash the entire process. If your Redis cluster restarts or drops connection momentarily during a deployment, unhandled errors on the `ioredis` instances will bring down your Node.js workers.\n\nAlways attach error listeners to both Redis clients and configure backoff retries:\n\n``` python\nimport Redis from \"ioredis\";\n\nconst redisConfig = {\n  maxRetriesPerRequest: null,\n  enableReadyCheck: false,\n  retryStrategy(times) {\n    // Exponential backoff with a cap of 3 seconds\n    const delay = Math.min(times * 100, 3000);\n    return delay;\n  },\n};\n\nconst pubClient = new Redis(REDIS_URL, redisConfig);\nconst subClient = pubClient.duplicate();\n\npubClient.on(\"error\", (err) => {\n  console.error(\"[Redis Pub Error]:\", err.message);\n});\n\nsubClient.on(\"error\", (err) => {\n  console.error(\"[Redis Sub Error]:\", err.message);\n});\n```\n\nWhen Redis recovers, `ioredis` will automatically re-establish the connection and the adapter will resume channel listening without dropping existing client TCP connections.\n\nIn standard configurations, all namespace events pass through a single Redis channel (e.g., `socket.io#/#`). If your application broadcasts thousands of events per second across hundreds of rooms, a single Redis Pub/Sub channel can saturate network throughput on that channel.\n\nTo scale beyond this limit, `@socket.io/redis-adapter` supports Redis Streams or Redis Sharded Pub/Sub (available in Redis 7.0+):\n\n``` js\nimport { createShardedAdapter } from \"@socket.io/redis-adapter\";\n\n// Uses Redis 7+ SPUBLISH / SSUBSCRIBE for linear cluster scaling\nconst io = new Server(server, {\n  adapter: createShardedAdapter(pubClient, subClient),\n});\n```\n\nSharded Pub/Sub hashes room names and distributes messages across distinct cluster slots, ensuring that individual Redis cluster nodes only process events intended for their specific shards.\n\nWhile chat applications are the standard hello-world tutorial for WebSockets, production-grade distributed push backbones power the core experiences of the largest platforms on the internet.\n\nAny platform where state must update on a user's screen in sub-second intervals—without millions of clients bombarding the database with continuous HTTP polling—uses this exact pattern: stateless edge WebSocket nodes connected via a shared pub/sub event highway.\n\n`/deal-status` every second, database connection pools would saturate and crash. Instead, when an inventory threshold updates or a deal reaches 100% reserved, the checkout backend fires a single Redis/Kafka event. The clustered edge servers push that state change to all product pages watching that SKU within milliseconds, toggling the \"Claim Deal\" button instantly.\n**Google Docs / Sheets Multi-User Presence:** When 20 team members work on a document, their cursor coordinates, selection ranges, and OT (Operational Transformation) / CRDT character diffs stream across processes. Because collaborators inevitably land on different application servers across Google's edge data centers, local server memory cannot coordinate them. An event bus aggregates document mutations and fans them out to all connected collaborators in that document's virtual room.\n\n**Google Cloud Console & Cloud Shell:** When running asynchronous deployment pipelines (like Cloud Build or deploying a container to Cloud Run), log streams and build progress percentages are emitted through distributed pub/sub queues and pushed to your browser’s live terminal console.\n\n**\"Teleparty\" / Co-Watching & Playback Sync:** Coordinating playback states (play, pause, seek to `01:14:22`) between friends across different continents requires near-zero latency. Playback actions trigger pub/sub broadcast events that instantly align playback timers across all connected sessions.\n\n**Cross-Device Session Handover:** If you are watching a movie on your living room Smart TV and open Netflix on your phone, the phone UI immediately reflects what is currently playing. When you pause on the TV, the state sync event notifies your phone’s active socket to update the media controls and current watch time.\n\nScaling real-time systems horizontally requires treating individual application servers as stateless connection terminators. By offloading event routing to a shared, high-throughput message bus like Redis, your backend instances can scale up or down dynamically behind any standard load balancer without dropping critical broadcasts.\n\nYou can inspect, fork, and run the complete reproducible source code—including the Docker Compose cluster, multi-instance server configurations, and simulated test runner—from the companion repository:\n\n👉 GitHub Repository: [GitHub Repo](https://github.com/kishanchauhan01/Articles/tree/main/Scaling%20Socket.IO%20Horizontally)", "url": "https://wpnews.pro/news/scaling-socket-io-horizontally-why-your-real-time-architecture-breaks-beyond-a", "canonical_source": "https://dev.to/kishanchauhan01/scaling-socketio-horizontally-why-your-real-time-architecture-breaks-beyond-a-single-process-1bm9", "published_at": "2026-09-22 17:05:55+00:00", "updated_at": "2026-09-22 17:22:49.454330+00:00", "lang": "en", "topics": ["developer-tools", "ai-infrastructure"], "entities": ["Socket.IO", "Node.js", "Express", "PM2", "Docker", "Nginx", "AWS Application Load Balancer"], "alternates": {"html": "https://wpnews.pro/news/scaling-socket-io-horizontally-why-your-real-time-architecture-breaks-beyond-a", "markdown": "https://wpnews.pro/news/scaling-socket-io-horizontally-why-your-real-time-architecture-breaks-beyond-a.md", "text": "https://wpnews.pro/news/scaling-socket-io-horizontally-why-your-real-time-architecture-breaks-beyond-a.txt", "jsonld": "https://wpnews.pro/news/scaling-socket-io-horizontally-why-your-real-time-architecture-breaks-beyond-a.jsonld"}}