Clustering and Persistence

Problem. Offloading compute still leaves connections accepted on one main thread — and a process restart wipes shared state entirely, cold-starting the read model on the first request.

Fix. createHttpCluster transfers raw sockets straight to workers (Node ≥ 26) with stickyByAddress pinning, proxyUpgradeToWorker does the same for WebSockets, and persistSharedMemory mirrors fields into Redis and replays them on boot.

Gateway routing moves compute off the main thread — but every connection still lands there first. For most apps that's fine. For workloads where the per-request cost is the product — hashing, compression, aggregation over shared state — Node 26 added the missing primitive: transferring the accepted socket itself to a worker.

Socket-transfer clustering

import { createHttpCluster, stickyByAddress } from '@atolljs/node';

const cluster = createHttpCluster({
  workers: () => new Worker(new URL('./server.worker.ts', import.meta.url)),
  route: stickyByAddress(),     // same client → same worker
});

The main thread accepts and hands off; request handling never touches its event loop. stickyByAddress pins clients to workers — essential the moment a worker holds per-connection or in-memory session state. proxyUpgradeToWorker does the equivalent for WebSockets: upgrades tunnel through the gateway, or transfer with the socket on Node ≥ 26. And SOCKET_TRANSFER_SUPPORTED is exported and checked — older Node is told the truth, not crashed.

Making shared state durable

The honest limit of shared memory: it's process-local. Restart the process and a million-record read model is gone — cold start on the first request, right when your load balancer is watching.

persistSharedMemory mirrors each versioned field into Redis hashes and replays ops across processes:

import { persistSharedMemory, ioRedisSubscriber } from '@atolljs/node';

const handle = persistSharedMemory(incidentsMemory, {
  transport: ioRedisSubscriber(redis),  // any ioredis-shaped client
});
// on boot, workers rehydrate the buffer from Redis
// handle.stop() flushes and detaches cleanly

Stop is clean — a failing final flush warns instead of rejecting, and the flush timer never leaks. On boot, workers rehydrate from Redis: the read model survives a deploy.

That's the full arc this series builds toward: compute in workers, connections on workers, state in shared memory, memory in Redis. Each piece removes one reason production traffic has to care that multithreading happened.

Source: the Node.js runtime guide — clustering, WebSocket tunneling, and persistence; implementation in packages/node/src/{http,redis}.ts.