@atolljs/node 0.1.0 → 0.1.1

package/README.md

@@ -1,17 +1,100 @@
 # @atolljs/node
 
 `node:worker_threads` runtime adapter for `@atolljs/core` — lets `WorkerPool`
-and `connectWorker` run on Node's Worker (an EventEmitter) instead of the DOM
-surface they expect.
-
-- `createNodePool({ worker, sharedMemory?, tasks?, … })` — `WorkerPool` with the
-  adapter baked in. The `worker:` factory may return a `node:worker_threads.Worker`
-  directly, so `new Worker(new URL('./x.worker.ts', import.meta.url))` stays
-  bundler-detectable.
-- `createNodeWorker(nodeWorker)` / `NodeWorkerAdapter` — wraps a Node Worker for
-  `connectWorker` or a hand-built `WorkerPool`.
-- `@atolljs/node/shim` — worker-side entry shim; imports first and binds
-  `self = parentPort` before `defineWorker`'s bootstrap evaluates.
-
-`SharedArrayBuffer` works in Node with no headers — cross-origin isolation is a
-browser-only requirement.
+and `connectWorker` run on Node's `Worker` (an `EventEmitter`) instead of the
+DOM surface they expect. No framework required.
+
+**[Atoll — package documentation](https://jwhenry3.github.io/atolljs/consumer/#/quickstart)**
+
+## Install
+
+```bash
+npm install @atolljs/core @atolljs/node
+```
+
+## Usage
+
+```ts
+// pool.ts — a WorkerPool backed by node:worker_threads
+import { Worker } from 'node:worker_threads';
+import { createNodePool } from '@atolljs/node';
+import { counterMemory } from './counter.memory';
+
+export const pool = createNodePool({
+  // The factory may return a node:worker_threads.Worker directly — the
+  // adapter wraps it, so new Worker(new URL(...)) stays bundler-detectable.
+  worker: () => new Worker(new URL('./counter.worker.js', import.meta.url)),
+  sharedMemory: counterMemory,
+  poolSize: 4,
+});
+```
+
+```ts
+// counter.worker.ts — the worker entry; the shim binds self = parentPort
+// before defineWorker's bootstrap evaluates, so import it first.
+import '@atolljs/node/shim';
+import { defineWorker } from '@atolljs/core';
+import { counterMemory } from './counter.memory';
+
+export const counterWorker = defineWorker({
+  sharedMemory: counterMemory,
+  methods: {
+    increment(delta: number) {
+      const next = counterMemory.count.read() + delta;
+      counterMemory.count.write(next);
+      return next;
+    },
+  },
+});
+```
+
+## API
+
+- `createNodePool({ worker, sharedMemory?, tasks?, … })` — a `WorkerPool` with
+  the adapter baked in. `worker` accepts a path/URL or a factory returning
+  either a Node or DOM-style `Worker`.
+- `createNodeWorker(nodeWorker)` / `NodeWorkerAdapter` — wrap a Node `Worker`
+  (or worker file path) for `connectWorker` or a hand-built `WorkerPool`.
+- `@atolljs/node/shim` — worker-side entry shim; import first so `self =
+  parentPort` is bound before `defineWorker`'s bootstrap evaluates.
+- `withSharedBuffer` + `bindSharedBuffer` — share one contract buffer across
+  pools. Wrap a worker factory with `withSharedBuffer(spawn, bufferOrThunk)`
+  so every spawn is fed `pool.sharedBuffer` (thunk evaluated per spawn —
+  respawns included); the worker entry `await`s `bindSharedBuffer()` to bind
+  all contracts. For message-only pools whose workers read another pool's
+  memory.
+- `@atolljs/node/http` — two offload topologies:
+  - `createHttpCluster` (Node ≥ 26): the main thread accepts TCP
+    connections with `pauseOnConnect` and transfers each `net.Socket` to a
+    pool worker, where `serveHttp` feeds it into an `http.Server` owned by
+    the worker — parsing, routing, and serialization all off-thread.
+  - `routeHttpGateway` (any Node): path-level ownership — the main thread
+    parses HTTP once and proxies matched prefixes to worker-owned internal
+    listeners (`serveHttp(app, { listen: 0 })`). Pin `/api/a/*` to worker A,
+    `/api/b/*` to worker B, serve the rest on main. WebSocket upgrades match
+    the same prefixes and are tunneled end-to-end; for embedding into a
+    host framework, `workerHttpPorts` + `proxyToWorker` (+`proxyUpgradeToWorker`
+    on the server's `upgrade` event) expose the same machinery as mountable
+    middleware (see `examples/nestjs` housed API).
+  See `examples/http-offload` and `docs/frameworks/node.md`.
+- `@atolljs/node/redis` — shared-memory persistence via Redis
+  (`persistSharedMemory` / `redisMemoryAdapter`): field regions mirror to a
+  Redis hash on a version-diff flush, restore into the buffer at boot, and
+  optionally replicate across processes over a pub/sub channel. Pass it as
+  `persistence` on `createNodePool` (or `AtollModule.registerPool`) — the
+  pool attaches it after bind and calls `stop()` on `terminate()`.
+
+## Notes
+
+- `SharedArrayBuffer` works in Node with no headers — cross-origin isolation
+  is a browser-only requirement.
+- Building a NestJS app? [`@atolljs/nestjs`](../nestjs) wraps this adapter in
+  DI providers and decorator-based method offload.
+
+## Documentation
+
+- [Atoll — package documentation](https://jwhenry3.github.io/atolljs/consumer/#/quickstart)
+- [Node backends — Express, Fastify, Hono, Koa](https://jwhenry3.github.io/atolljs/consumer/#/fw-node)
+- [Worker HTTP servers — clustering & gateway](https://jwhenry3.github.io/atolljs/consumer/#/fw-node/clustering)
+- [Worker pool & tasks](https://jwhenry3.github.io/atolljs/consumer/#/tasks)
+- [NestJS guide](https://jwhenry3.github.io/atolljs/consumer/#/fw-nestjs)

package/package.json

@@ -1,24 +1,31 @@
 {
   "name": "@atolljs/node",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Node runtime adapter — node:worker_threads pools, no framework",
+  "homepage": "https://jwhenry3.github.io/atolljs/consumer/#/quickstart",
   "type": "module",
   "exports": {
     ".": "./src/index.ts",
+    "./http": "./src/http.ts",
+    "./redis": "./src/redis.ts",
     "./shim": "./src/shim.ts"
   },
   "files": [
     "src"
   ],
   "publishConfig": {
-    "access": "public"
+    "access": "public",
+    "registry": "https://registry.npmjs.org"
   },
   "peerDependencies": {
-    "@atolljs/core": "0.1.0"
+    "@atolljs/core": "0.1.1"
   },
   "repository": {
     "type": "git",
     "url": "https://github.com/jwhenry3/atolljs",
     "directory": "packages/node"
+  },
+  "bugs": {
+    "url": "https://github.com/jwhenry3/atolljs/issues"
   }
 }

package/src/http.ts

@@ -0,0 +1,569 @@
+// HTTP clustering for plain-Node servers — the worker_threads answer to the
+// cluster module. The main thread accepts TCP connections with
+// pauseOnConnect (no bytes consumed) and transfers each net.Socket to a
+// pool worker via postMessage. The worker feeds it into its own
+// http.Server, so request parsing, route handling, and response
+// serialization ALL run off the API thread — the main thread only moves a
+// handle. Works alongside task dispatch: the same workers still answer
+// EXECUTE_TASK; sockets just queue behind whatever a worker is doing.
+import {
+  createServer as createHttpServer,
+  request as httpRequest,
+  Server as HttpServer,
+  type IncomingMessage,
+  type RequestListener,
+  type ServerResponse,
+} from 'node:http';
+import {
+  connect as netConnect,
+  createServer as createNetServer,
+  type Server as NetServer,
+  type Socket,
+} from 'node:net';
+import { isMainThread, parentPort } from 'node:worker_threads';
+
+/** Wire id for transferred sockets — distinct from the pool's task protocol. */
+const HTTP_CONNECTION = 'HTTP_CONNECTION';
+/** Wire id a worker uses to announce an internally-listening HTTP port. */
+export const HTTP_PORT = 'HTTP_PORT';
+/** Wire id a tracker sends to re-request an HTTP_PORT announcement. */
+const HTTP_PORT_QUERY = 'HTTP_PORT_QUERY';
+
+/**
+ * net.Socket/net.Server handles only became transferable across
+ * worker_threads in Node.js 26 — on older runtimes postMessage throws
+ * DataCloneError ("Found invalid value in transferList"). Gate at setup so
+ * the failure is loud instead of dropping connections.
+ */
+const NODE_MAJOR = Number(process.versions.node.split('.')[0]);
+export const SOCKET_TRANSFER_SUPPORTED = NODE_MAJOR >= 26;
+
+function assertSocketTransferSupported(): void {
+  if (!SOCKET_TRANSFER_SUPPORTED) {
+    throw new Error(
+      `serveHttp (without { listen }) requires Node.js >= 26 for net.Socket transfer ` +
+        `across worker_threads (found ${process.versions.node}).`,
+    );
+  }
+}
+
+/** Anything that exposes its workers — WorkerPool is the usual source. */
+export interface WorkerSource {
+  readonly workers: readonly Worker[];
+}
+
+export interface HttpClusterOptions {
+  /** The pool whose workers serve connections (respawns picked up on read). */
+  pool: WorkerSource;
+  /** Port to listen on. Ignored when `server` is provided. */
+  port?: number;
+  /** Listen host. Ignored when `server` is provided. */
+  host?: string;
+  /**
+   * Bring your own listener — MUST be created with `pauseOnConnect: true`
+   * (e.g. `net.createServer({ pauseOnConnect: true })`) or the main thread
+   * may consume request bytes before the socket is transferred.
+   */
+  server?: NetServer;
+  /**
+   * Connection → worker selection. Defaults to round-robin. Receives the
+   * fresh `pool.workers` snapshot each call, so respawns participate.
+   * Returning undefined destroys the socket. {@link stickyByAddress} is a
+   * ready-made sticky implementation for multi-connection session flows.
+   */
+  route?: (socket: Socket, workers: readonly Worker[]) => Worker | undefined;
+  /** Called once the server is listening. */
+  onListen?: (server: NetServer) => void;
+}
+
+export interface HttpCluster {
+  /** The listening TCP server (the user's `server` when provided). */
+  server: NetServer;
+  /** Stop accepting; in-flight transferred connections stay with workers. */
+  close(): Promise<void>;
+}
+
+/**
+ * Main thread: cluster a pool behind one listener — accept connections and
+ * hand each socket to a pool worker. Pairs with the worker-side
+ * {@link serveHttp}:
+ *
+ *   const pool = createNodePool({ worker: () => new Worker(new URL('./api.worker.js', import.meta.url)), sharedMemory, poolSize: 'auto' });
+ *   const cluster = createHttpCluster({ pool, port: 8080 }); // null below Node 26
+ *
+ * Sockets transfer BEFORE any bytes are read — the worker's http.Server does
+ * all parsing. HTTPS termination is not supported here (the TLS handshake
+ * would run on the accept thread); terminate TLS upstream or serve plain
+ * HTTP behind a proxy.
+ *
+ * Returns `null` on runtimes without socket transfer (Node < 26 — see
+ * {@link SOCKET_TRANSFER_SUPPORTED}) after logging a one-line notice, so
+ * callers can write the cluster unconditionally and degrade to gateway-only
+ * behavior without wrapping the call in capability checks.
+ */
+export function createHttpCluster(options: HttpClusterOptions): HttpCluster | null {
+  if (!SOCKET_TRANSFER_SUPPORTED) {
+    console.warn(
+      `[atoll] createHttpCluster skipped — net.Socket transfer requires Node.js >= 26 ` +
+        `(found ${process.versions.node})`,
+    );
+    return null;
+  }
+  let cursor = 0;
+  const route =
+    options.route ??
+    ((_: Socket, workers: readonly Worker[]) =>
+      workers.length === 0 ? undefined : workers[cursor++ % workers.length]);
+
+  const server = options.server ?? createNetServer({ pauseOnConnect: true });
+  server.on('connection', (socket: Socket) => {
+    const worker = route(socket, options.pool.workers);
+    if (!worker) {
+      socket.destroy();
+      return;
+    }
+    try {
+      worker.postMessage({ type: HTTP_CONNECTION, socket }, [
+        socket as unknown as Transferable,
+      ]);
+    } catch (err) {
+      socket.destroy();
+      server.emit('error', err);
+    }
+  });
+  if (!options.server) {
+    server.listen(options.port ?? 8080, options.host, () => options.onListen?.(server));
+  } else {
+    options.onListen?.(server);
+  }
+  return {
+    server,
+    close: () =>
+      new Promise<void>((resolve, reject) =>
+        server.close((err) => (err ? reject(err) : resolve())),
+      ),
+  };
+}
+
+/**
+ * FNV-1a — tiny string hash for rendezvous routing. Only hashes connection
+ * metadata (client IPs), never user data, so a non-crypto hash is fine.
+ */
+const fnv1a = (s: string): number => {
+  let h = 0x811c9dc5;
+  for (let i = 0; i < s.length; i++) {
+    h ^= s.charCodeAt(i);
+    h = Math.imul(h, 0x01000193);
+  }
+  return h >>> 0;
+};
+
+/**
+ * Sticky connection routing for {@link createHttpCluster}: every connection
+ * from the same client address lands on the same worker — rendezvous
+ * (highest-random-weight) hashing over `key + slot`, so removing a worker
+ * only remaps ITS clients instead of reshuffling the whole pool.
+ *
+ * A transferred socket pins its whole life to one worker, so a bare
+ * WebSocket connection never needs this — stickiness matters for
+ * multi-connection session flows: socket.io's polling→upgrade sequence,
+ * or an HTTP request that must precede/follow a WS connection on the same
+ * worker. The acceptor can't read headers or cookies, so client address
+ * (nginx ip_hash style) is the strongest key available — supply `key` to
+ * mix in more (e.g. localPort for multi-listener setups).
+ *
+ *   createHttpCluster({ pool, port: 8080, route: stickyByAddress() });
+ */
+export function stickyByAddress(
+  key: (socket: Socket) => string = (s) => s.remoteAddress ?? '',
+): (socket: Socket, workers: readonly Worker[]) => Worker | undefined {
+  return (socket, workers) => {
+    if (workers.length === 0) return undefined;
+    const k = key(socket);
+    let best: Worker | undefined;
+    let bestScore = -1;
+    workers.forEach((w, i) => {
+      const score = fnv1a(`${k}#${i}`);
+      if (score > bestScore) {
+        bestScore = score;
+        best = w;
+      }
+    });
+    return best;
+  };
+}
+
+export interface ServeHttpOptions {
+  /**
+   * Listen on an internal TCP port and announce it to the parent thread via
+   * a `{ type: HTTP_PORT, port }` message — for the gateway topology where
+   * the main thread parses HTTP and proxies to worker-owned listeners
+   * (works on any Node version, unlike socket transfer). `0` = ephemeral.
+   * The server still accepts transferred sockets either way — `listen` only
+   * adds the internal gateway port.
+   */
+  listen?: number;
+  /** Listen host; defaults to '127.0.0.1' so worker ports stay internal. */
+  host?: string;
+}
+
+/**
+ * Worker side: serve HTTP with an http.Server owned by this worker. Call it
+ * once in the worker entry, after '@atolljs/node/shim':
+ *
+ *   import '@atolljs/node/shim';
+ *   import { serveHttp } from '@atolljs/node/http';
+ *   import express from 'express';
+ *
+ *   const app = express();          // any (req, res) handler works —
+ *   app.get('/api', (_q, r) => …);  // express/koa .callback()/fastify.server
+ *   serveHttp(app);                 // sockets transferred by createHttpCluster
+ *   serveHttp(app, { listen: 0 });  // internal listener for routeHttpGateway
+ *
+ * Accepts a RequestListener (wrapped in a new http.Server), an existing
+ * http.Server (e.g. `fastify().server` after ready()), or
+ * `{ handler }` / `{ server }`. A no-op on the main thread.
+ */
+export function serveHttp(
+  target: RequestListener | HttpServer | { handler?: RequestListener; server?: HttpServer },
+  options?: ServeHttpOptions,
+): HttpServer {
+  const server =
+    target instanceof HttpServer
+      ? target
+      : typeof target === 'function'
+        ? createHttpServer(target)
+        : target.server ?? createHttpServer(target.handler);
+
+  if (isMainThread || !parentPort) return server;
+  if (options?.listen === undefined) assertSocketTransferSupported();
+
+  let announcedPort: number | undefined;
+  parentPort.on('message', (msg: { type?: string; socket?: Socket }) => {
+    if (msg?.type === HTTP_CONNECTION && msg.socket) {
+      // Feed the accepted socket to this worker's HTTP stack — its stream is
+      // still paused (pauseOnConnect), so resume after the parser attaches.
+      server.emit('connection', msg.socket);
+      msg.socket.resume();
+    } else if (msg?.type === HTTP_PORT_QUERY && announcedPort !== undefined) {
+      parentPort!.postMessage({ type: HTTP_PORT, port: announcedPort });
+    }
+  });
+
+  if (options?.listen !== undefined) {
+    server.listen(options.listen, options.host ?? '127.0.0.1', () => {
+      const addr = server.address();
+      announcedPort = typeof addr === 'object' && addr ? addr.port : 0;
+      parentPort!.postMessage({ type: HTTP_PORT, port: announcedPort });
+    });
+  }
+  return server;
+}
+
+/* ── worker port tracking — shared by gateway and proxy middleware ─────── */
+
+export interface WorkerHttpPorts {
+  /** Announced internal listener ports, keyed by worker instance (live map). */
+  readonly ports: ReadonlyMap<Worker, number>;
+  /**
+   * Attach to any new workers in `source.workers` and re-query ones that
+   * haven't announced — call it before resolving routes so respawns (and
+   * announcements that raced the initial attach) are picked up.
+   */
+  refresh(): void;
+  /** Detach all message listeners. */
+  dispose(): void;
+}
+
+/**
+ * Collect HTTP_PORT announcements from a pool's workers — for the
+ * gateway/proxy topology where workers listen on internal TCP ports.
+ * Announcements are a handshake, not a broadcast: workers that haven't
+ * announced get an HTTP_PORT_QUERY so trackers attached late still learn
+ * their ports.
+ */
+export function workerHttpPorts(source: WorkerSource): WorkerHttpPorts {
+  const ports = new Map<Worker, number>();
+  const listeners = new Map<Worker, (e: MessageEvent) => void>();
+  const refresh = () => {
+    for (const w of source.workers) {
+      if (!listeners.has(w)) {
+        const listener = (e: MessageEvent) => {
+          const d = e.data as { type?: string; port?: number } | undefined;
+          if (d?.type === HTTP_PORT && typeof d.port === 'number') ports.set(w, d.port);
+        };
+        listeners.set(w, listener);
+        w.addEventListener('message', listener);
+      }
+      if (!ports.has(w)) {
+        try {
+          w.postMessage({ type: HTTP_PORT_QUERY });
+        } catch {
+          /* worker terminated between snapshot read and post — next refresh retries */
+        }
+      }
+    }
+  };
+  refresh();
+  return {
+    ports,
+    refresh,
+    dispose: () => {
+      for (const [w, l] of listeners) w.removeEventListener('message', l);
+      listeners.clear();
+    },
+  };
+}
+
+/** Forward one request to a worker-owned listener and pipe the reply back. */
+const forwardToPort = (
+  req: IncomingMessage,
+  res: ServerResponse,
+  port: number,
+  path: string,
+): void => {
+  const upstream = httpRequest(
+    {
+      host: '127.0.0.1',
+      port,
+      method: req.method,
+      path: path.startsWith('/') ? path : `/${path}`,
+      headers: { ...req.headers, host: `127.0.0.1:${port}` },
+    },
+    (ures) => {
+      res.writeHead(ures.statusCode ?? 502, ures.headers);
+      ures.pipe(res);
+    },
+  );
+  upstream.on('error', () => {
+    if (!res.headersSent) res.writeHead(502);
+    res.end();
+  });
+  req.pipe(upstream);
+};
+
+export interface ProxyToWorkerOptions {
+  /** The pool whose workers announce internal HTTP ports. */
+  pool: WorkerSource;
+  /** Announcement tracker — from {@link workerHttpPorts} (refreshed per request). */
+  tracker: WorkerHttpPorts;
+  /** Which worker serves this route — a slot index into the live
+   *  `pool.workers` snapshot, or a selector (e.g. round-robin). */
+  worker: number | ((workers: readonly Worker[]) => Worker | undefined);
+  /**
+   * Prefix prepended to `req.url` before forwarding. When mounted via
+   * `app.use('/prefix', mw)` Express has already stripped the mount — set
+   * `to: '/prefix'` to restore it for the worker's routes.
+   */
+  to?: string;
+}
+
+/**
+ * A mountable RequestListener that proxies to one pool worker's internal
+ * listener — the piece that lets a host framework (Nest, Express, …) house
+ * part of its API inside workers without giving up its own server:
+ *
+ *   const tracker = workerHttpPorts(pool);
+ *   app.use('/api/housed', proxyToWorker({
+ *     pool, tracker, to: '/api/housed',
+ *     worker: (w) => w[i++ % w.length],   // or 0 to pin a slot
+ *   }));
+ */
+export function proxyToWorker(options: ProxyToWorkerOptions): RequestListener {
+  return (req, res) => {
+    const port = resolveWorkerPort(options);
+    if (port === undefined) {
+      res.writeHead(503, { 'content-type': 'application/json' });
+      res.end(JSON.stringify({ error: 'worker not listening yet' }));
+      return;
+    }
+    forwardToPort(req, res, port, (options.to ?? '') + (req.url ?? '/'));
+  };
+}
+
+/** Resolve the target worker's announced port for proxy/cluster options. */
+const resolveWorkerPort = (options: ProxyToWorkerOptions): number | undefined => {
+  options.tracker.refresh();
+  const workers = options.pool.workers;
+  const worker =
+    typeof options.worker === 'number' ? workers[options.worker] : options.worker(workers);
+  return worker ? options.tracker.ports.get(worker) : undefined;
+};
+
+/**
+ * Tunnel an HTTP Upgrade (WebSocket) handshake to a worker-owned listener:
+ * replay the request line + headers verbatim against the worker's internal
+ * port (rawHeaders preserves order, case, and duplicates), then splice the
+ * two sockets into a raw bidirectional pipe. `head` is the first packet of
+ * the upgraded stream the parser already consumed — it MUST be written after
+ * the headers or the peer's first frames are lost.
+ */
+const tunnelUpgradeToPort = (
+  req: IncomingMessage,
+  socket: Socket,
+  head: Buffer,
+  port: number,
+  path: string,
+): void => {
+  const upstream = netConnect({ host: '127.0.0.1', port }, () => {
+    const lines = [`${req.method} ${path} HTTP/${req.httpVersion}`];
+    for (let i = 0; i < req.rawHeaders.length; i += 2) {
+      const key = req.rawHeaders[i];
+      const value = key.toLowerCase() === 'host' ? `127.0.0.1:${port}` : req.rawHeaders[i + 1];
+      lines.push(`${key}: ${value}`);
+    }
+    upstream.write(lines.join('\r\n') + '\r\n\r\n');
+    if (head?.length) upstream.write(head);
+    socket.pipe(upstream).pipe(socket);
+  });
+  upstream.on('error', () => socket.destroy());
+  socket.on('error', () => upstream.destroy());
+};
+
+/**
+ * The upgrade-side sibling of {@link proxyToWorker}: middleware never sees
+ * WebSocket handshakes (Node emits 'upgrade' on the server, bypassing
+ * request listeners), so attach the returned listener to your server:
+ *
+ *   const tracker = workerHttpPorts(pool);
+ *   app.use('/api/housed', proxyToWorker({ pool, tracker, to: '/api/housed', worker }));
+ *   app.getHttpServer().on('upgrade',
+ *     proxyUpgradeToWorker({ pool, tracker, worker })); // full URL — `to` not needed
+ *
+ * Unlike the middleware, an 'upgrade' listener receives the ORIGINAL url
+ * (nothing stripped it), so `to` is a rewrite prefix rather than a mount
+ * restore — usually omit it.
+ */
+export function proxyUpgradeToWorker(
+  options: ProxyToWorkerOptions,
+): (req: IncomingMessage, socket: Socket, head: Buffer) => void {
+  return (req, socket, head) => {
+    const port = resolveWorkerPort(options);
+    if (port === undefined) {
+      socket.destroy();
+      return;
+    }
+    tunnelUpgradeToPort(req, socket, head, port, (options.to ?? '') + (req.url ?? '/'));
+  };
+}
+
+/* ── gateway: path-level routing on the main thread ───────────────────────
+   Clustering routes per-CONNECTION — it can't split a listener by URL
+   path (the accepting thread never reads request bytes). To pin routes to
+   worker A vs worker B vs the main thread, the main thread must parse HTTP
+   and forward — this gateway does exactly that: workers listen on internal
+   127.0.0.1 ports (serveHttp({ listen })), and matched prefixes proxy to the
+   chosen pool worker; unmatched requests run in the main-thread handler.
+   Works on any Node version.                                          */
+
+export interface GatewayRoute {
+  /** URL prefix that owns this route, e.g. '/api/a/'. */
+  prefix: string;
+  /** Which pool worker serves the prefix — a slot index into the live
+   *  `pool.workers` snapshot, or a selector. Respawns are picked up. */
+  worker: number | ((workers: readonly Worker[]) => Worker | undefined);
+  /** Rewrite target prefix — the worker sees `to + url.slice(prefix.length)`.
+   *  Defaults to '/', so `/api/a/x` arrives at the worker as `/x`. */
+  to?: string;
+}
+
+export interface RouteHttpGatewayOptions {
+  /** The pool whose workers announce internal HTTP ports. */
+  pool: WorkerSource;
+  port?: number;
+  host?: string;
+  /** BYO http.Server (the gateway attaches its request handler). */
+  server?: HttpServer;
+  routes?: GatewayRoute[];
+  /** Everything unmatched runs on the main thread; defaults to 404. */
+  handler?: RequestListener;
+  /**
+   * Fallback for unmatched Upgrade (WebSocket) handshakes — e.g. attach your
+   * own ws server's handler to keep WS routes on the main thread. When
+   * omitted the socket is destroyed, unless another 'upgrade' listener is
+   * registered on the server (then it's left to that listener).
+   */
+  onUpgrade?: (req: IncomingMessage, socket: Socket, head: Buffer) => void;
+  onListen?: (server: HttpServer) => void;
+}
+
+export interface HttpGateway {
+  server: HttpServer;
+  /** Announced internal listener ports, keyed by worker instance (live map). */
+  ports: ReadonlyMap<Worker, number>;
+  close(): Promise<void>;
+}
+
+/** Main thread: parse HTTP once and proxy matched prefixes to worker-owned
+ *  listeners — the mixed topology: some routes in worker A, some in worker
+ *  B, the rest served right here. Upgrade (WebSocket) handshakes match the
+ *  same prefix table and are TUNNELED — the handshake is replayed to the
+ *  worker's listener and the two sockets spliced, so frames flow end-to-end
+ *  without the main thread touching them again. */
+export function routeHttpGateway(options: RouteHttpGatewayOptions): HttpGateway {
+  const tracker = workerHttpPorts(options.pool);
+  const fallback: RequestListener =
+    options.handler ?? ((_req, res) => res.writeHead(404).end());
+  const server = options.server ?? createHttpServer();
+
+  const resolveRoute = (url: string) => {
+    tracker.refresh(); // respawned workers re-announce on the next request
+    const workers = options.pool.workers;
+    const route = options.routes?.find((r) => url.startsWith(r.prefix));
+    const worker = route
+      ? typeof route.worker === 'number'
+        ? workers[route.worker]
+        : route.worker(workers)
+      : undefined;
+    return { route, port: worker ? tracker.ports.get(worker) : undefined };
+  };
+
+  server.on('request', (req: IncomingMessage, res: ServerResponse) => {
+    const url = req.url ?? '/';
+    const { route, port } = resolveRoute(url);
+    if (!route) {
+      fallback(req, res);
+      return;
+    }
+    if (port === undefined) {
+      res.writeHead(503, { 'content-type': 'application/json' });
+      res.end(JSON.stringify({ error: 'worker not listening yet' }));
+      return;
+    }
+    forwardToPort(req, res, port, (route.to ?? '/') + url.slice(route.prefix.length));
+  });
+
+  // Upgrade handshakes bypass 'request' entirely — match the same prefix
+  // table and splice the client socket onto a fresh connection to the
+  // worker's listener. After the handshake the main thread is out of the
+  // data path: frames tunnel socket↔socket.
+  server.on('upgrade', (req: IncomingMessage, socket: Socket, head: Buffer) => {
+    const url = req.url ?? '/';
+    const { route, port } = resolveRoute(url);
+    if (!route || port === undefined) {
+      if (options.onUpgrade) {
+        options.onUpgrade(req, socket, head);
+      } else if (server.listenerCount('upgrade') <= 1) {
+        // No fallback and nobody else claimed it — preserve Node's
+        // no-listener behavior (destroy) instead of leaking the socket.
+        socket.destroy();
+      }
+      return;
+    }
+    tunnelUpgradeToPort(req, socket, head, port, (route.to ?? '/') + url.slice(route.prefix.length));
+  });
+
+  if (!options.server) {
+    server.listen(options.port ?? 8080, options.host, () => options.onListen?.(server));
+  } else {
+    options.onListen?.(server);
+  }
+  return {
+    server,
+    ports: tracker.ports,
+    close: () =>
+      new Promise<void>((resolve, reject) =>
+        server.close((err) => (err ? reject(err) : resolve())),
+      ),
+  };
+}

package/src/index.ts

@@ -1,6 +1,7 @@
-// Node runtime adapter for the Atoll — node:worker_threads pools without a
-// framework. Worker entries must import '@atolljs/node/shim' first.
-export { NodeWorkerAdapter, createNodeWorker } from './worker';
-export type { WorkerErrorEvent } from './worker';
-export { createNodePool } from './pool';
-export type { NodePoolConfig } from './pool';
+// Node runtime adapter for the Atoll — node:worker_threads pools without a
+// framework. Worker entries must import '@atolljs/node/shim' first.
+export { NodeWorkerAdapter, createNodeWorker } from './worker';
+export type { WorkerErrorEvent } from './worker';
+export { createNodePool } from './pool';
+export type { NodePoolConfig } from './pool';
+export { bindSharedBuffer, withSharedBuffer } from './sharedBuffer';

package/src/redis.ts

@@ -0,0 +1,252 @@
+/**
+ * Redis persistence for shared-memory contracts — the shared-memory analog
+ * of NestJS's Redis WebSocket adapter. The SharedArrayBuffer stays the
+ * synchronous source of truth on this thread (the contract's read/write
+ * surface can't be async); the adapter mirrors field regions to a Redis hash
+ * so state survives restarts, and optionally replicates writes across
+ * processes through a pub/sub channel.
+ *
+ * Layout in Redis:
+ *   {key}:{name}              hash — member = field path, value = base64 bytes
+ *   {key}:{name}:ops          channel — { src, path, b64 } per dirty field
+ *
+ * Change detection is the version-counter block every write already bumps
+ * (Atomics), polled on `syncIntervalMs` — no instrumentation of the hot
+ * write path. Remote applies bump the local version too, so `observe()`/
+ * waitAsync watchers fire exactly as they do for local writes.
+ *
+ * The client surface is intentionally minimal (base64 strings, hset/hgetall)
+ * — ioredis and node-redis both satisfy it directly; `publish` is only used
+ * when replication is enabled.
+ */
+import { scoped, type SharedMemory, type SharedSpec } from '@atolljs/core';
+
+const log = scoped('redis-mem');
+
+/** The hash commands the adapter needs — ioredis and node-redis both fit. */
+export interface RedisHashClient {
+  hset(key: string, field: string, value: string): Promise<unknown>;
+  hgetall(key: string): Promise<Record<string, string>>;
+  publish?(channel: string, message: string): Promise<unknown>;
+}
+
+/**
+ * Normalized pub/sub surface — node-redis's `client.subscribe(ch, listener)`
+ * matches directly; wrap an ioredis connection with `ioRedisSubscriber`.
+ */
+export interface RedisSubscriber {
+  subscribe(
+    channel: string,
+    onMessage: (channel: string, message: string) => void,
+  ): unknown;
+  unsubscribe?(channel: string): unknown;
+}
+
+/** Wrap an ioredis connection in the normalized subscriber surface. */
+export const ioRedisSubscriber = (client: {
+  subscribe(channel: string): unknown;
+  unsubscribe?(channel: string): unknown;
+  on(event: 'message', cb: (channel: string, message: string) => void): unknown;
+}): RedisSubscriber => ({
+  subscribe: (channel, onMessage) => {
+    client.on('message', (c, m) => {
+      if (c === channel) onMessage(c, m);
+    });
+    return client.subscribe(channel);
+  },
+  unsubscribe: (channel) => client.unsubscribe?.(channel),
+});
+
+export interface RedisMemoryAdapterOptions {
+  client: RedisHashClient;
+  /** Hash key root — the contract lives at `${key}:${name}`. Default 'atoll:mem'. */
+  key?: string;
+  /** Contract namespace under the key root. Default 'default'. */
+  name?: string;
+  /** Version-diff poll cadence — dirty fields flush at most this often. Default 100ms. */
+  syncIntervalMs?: number;
+  /** Restrict persistence to a subset of field paths. */
+  fields?: string[];
+  /**
+   * A second Redis connection subscribed to `${key}:${name}:ops` — enables
+   * cross-process replication. Each instance publishes its dirty fields;
+   * subscribers apply the bytes into their own buffer and bump the local
+   * version counter so local observers fire. Last write wins per field.
+   */
+  subscriber?: RedisSubscriber;
+  /** Echo guard — defaults to pid + random. Override for deterministic tests. */
+  instanceId?: string;
+}
+
+export interface RedisMemoryPersistence {
+  /** Resolves when initial restore + subscriber attach complete. */
+  readonly ready: Promise<void>;
+  /** Flush dirty fields now — also runs automatically on the poll interval. */
+  flush(): Promise<number>;
+  /** Final flush, unsubscribe, and stop the poll timer. */
+  stop(): Promise<void>;
+}
+
+interface FieldRegion {
+  path: string;
+  byteOffset: number;
+  byteLength: number;
+  version?: { view: Int32Array; index: number };
+}
+
+/**
+ * Attach Redis persistence to a bound (or soon-bound) shared-memory contract.
+ * `ready` resolves once state has been restored INTO the local buffer —
+ * workers that bind afterwards see the restored state, and version bumps
+ * wake observers on this thread.
+ */
+export function persistSharedMemory<S extends SharedSpec>(
+  memory: SharedMemory<S>,
+  options: RedisMemoryAdapterOptions,
+): RedisMemoryPersistence {
+  const { client, subscriber } = options;
+  const key = `${options.key ?? 'atoll:mem'}:${options.name ?? 'default'}`;
+  const channel = `${key}:ops`;
+  const intervalMs = options.syncIntervalMs ?? 100;
+  const instanceId =
+    options.instanceId ?? `${process.pid}:${Math.random().toString(36).slice(2, 8)}`;
+
+  let buffer: SharedArrayBuffer;
+  let regions: FieldRegion[] = [];
+  const lastSeen = new Map<string, number>();
+  let timer: ReturnType<typeof setInterval> | undefined;
+  let stopped = false;
+  let flushing = Promise.resolve(0);
+
+  const b64encode = (u8: Uint8Array): string =>
+    Buffer.from(u8.buffer, u8.byteOffset, u8.byteLength).toString('base64');
+  const b64decode = (s: string): Uint8Array => new Uint8Array(Buffer.from(s, 'base64'));
+
+  const fieldRegion = (path: string): FieldRegion | undefined =>
+    regions.find((r) => r.path === path);
+
+  /**
+   * Write bytes into the field's region and bump its local version counter —
+   * the same signal a connector write produces, so waitAsync observers and
+   * our own diff both see it. Marks lastSeen so the flush doesn't echo the
+   * applied value straight back to Redis (no publish ping-pong).
+   */
+  const applyRemote = (path: string, b64: string): void => {
+    const region = fieldRegion(path);
+    if (!region) return;
+    const bytes = b64decode(b64);
+    if (bytes.byteLength !== region.byteLength) {
+      log.warn(`"${path}": remote field is ${bytes.byteLength}B but the contract reserves ${region.byteLength}B — skipped`);
+      return;
+    }
+    new Uint8Array(buffer, region.byteOffset, region.byteLength).set(bytes);
+    if (region.version) {
+      Atomics.add(region.version.view, region.version.index, 1);
+      Atomics.notify(region.version.view, region.version.index);
+      lastSeen.set(path, Atomics.load(region.version.view, region.version.index));
+    }
+  };
+
+  /** Flush fields whose version counter moved since the last flush. */
+  const flush = async (): Promise<number> => {
+    if (stopped) return 0;
+    let dirty = 0;
+    for (const region of regions) {
+      const current = region.version
+        ? Atomics.load(region.version.view, region.version.index)
+        : 0;
+      if (lastSeen.get(region.path) === current) continue;
+      lastSeen.set(region.path, current);
+      dirty++;
+      const b64 = b64encode(new Uint8Array(buffer, region.byteOffset, region.byteLength));
+      await client.hset(key, region.path, b64);
+      if (subscriber) {
+        await client.publish?.(
+          channel,
+          JSON.stringify({ src: instanceId, path: region.path, b64 }),
+        );
+      }
+    }
+    return dirty;
+  };
+
+  const restore = async (): Promise<void> => {
+    const all = (await client.hgetall(key)) ?? {};
+    let restored = 0;
+    for (const [path, b64] of Object.entries(all)) {
+      applyRemote(path, b64);
+      restored++;
+    }
+    if (restored) log.info(`restored ${restored} field(s) from ${key}`);
+  };
+
+  const ready = new Promise<void>((resolve, reject) => {
+    memory.onBound(() => {
+      buffer = memory.buffer;
+      regions = memory
+        .fields()
+        .filter((f) => !options.fields || options.fields.includes(f.path))
+        .map((f) => ({ ...f, version: memory.connector(f.path)._version }));
+      for (const r of regions) {
+        if (r.version) {
+          lastSeen.set(r.path, Atomics.load(r.version.view, r.version.index));
+        }
+      }
+      (async () => {
+        await restore();
+        if (subscriber) {
+          await subscriber.subscribe(channel, (_ch, message) => {
+            try {
+              const msg = JSON.parse(message) as { src?: string; path?: string; b64?: string };
+              if (msg.src === instanceId || !msg.path || !msg.b64) return;
+              applyRemote(msg.path, msg.b64);
+            } catch (e) {
+              log.warn('malformed replication message', e);
+            }
+          });
+        }
+        timer = setInterval(() => {
+          flushing = flushing.then(flush).catch((e) => {
+            log.warn('flush failed', e);
+            return 0;
+          });
+        }, intervalMs);
+        timer.unref?.();
+      })().then(resolve, reject);
+    });
+  });
+
+  return {
+    ready,
+    // Serialize manual flushes behind the interval's — concurrent hset on
+    // the same members is pointless churn.
+    flush: () => (flushing = flushing.then(flush).catch(() => 0)),
+    stop: async () => {
+      if (stopped) return;
+      stopped = true;
+      if (timer) clearInterval(timer);
+      await subscriber?.unsubscribe?.(channel);
+      await flushing.catch(() => 0);
+      // One last flush — durability on shutdown — bypass the stopped guard.
+      stopped = false;
+      try {
+        await flush();
+      } finally {
+        stopped = true;
+      }
+    },
+  };
+}
+
+/**
+ * Pool-config form — the `persistence` option shape for `createNodePool` /
+ * `AtollModule.registerPool`. Nest's `app.useWebSocketAdapter()` analog:
+ *
+ *   persistence: redisMemoryAdapter(redis, { name: 'incidents' })
+ */
+export function redisMemoryAdapter(
+  client: RedisHashClient,
+  options: Omit<RedisMemoryAdapterOptions, 'client'> = {},
+): (memory: SharedMemory) => RedisMemoryPersistence {
+  return (memory) => persistSharedMemory(memory, { ...options, client });
+}

package/src/sharedBuffer.ts

@@ -0,0 +1,76 @@
+// Hand an existing shared buffer to workers that aren't bound through a
+// pool's INIT_MEMORY handshake — e.g. a second, message-only pool of HTTP
+// workers that should read another pool's contract buffer. A pool's
+// sharedMemory config creates a NEW WebAssembly.Memory, so sharing requires
+// passing the buffer explicitly; this module packages both halves.
+//
+//   // main — wraps a worker factory; bundler detection still sees the
+//   // literal `new Worker(new URL(...))` inside the thunk:
+//   worker: withSharedBuffer(
+//     () => new Worker(new URL('./housed.worker.ts', import.meta.url)),
+//     () => getAtollPool('incidents')?.sharedBuffer,   // per spawn — respawns included
+//   ),
+//
+//   // worker entry — resolves once the buffer lands, binds all contracts:
+//   await bindSharedBuffer();
+import { isMainThread, parentPort, workerData } from 'node:worker_threads';
+import type { Worker as NodeWorker } from 'node:worker_threads';
+import { bindSharedMemories } from '@atolljs/core';
+
+/** Wire id for the share-buffer message — distinct from pool protocol types. */
+const SHARED_BUFFER = 'SHARED_BUFFER';
+
+/**
+ * Main thread: wraps a worker factory so each spawned worker receives a
+ * shared buffer over its message channel. The buffer may be a thunk —
+ * evaluated per spawn, so respawned workers get it too. An unresolved
+ * buffer still posts (empty), so the worker fails loudly instead of hanging.
+ */
+export function withSharedBuffer<W extends Worker | NodeWorker>(
+  spawn: () => W,
+  buffer: SharedArrayBuffer | (() => SharedArrayBuffer | undefined),
+): () => W {
+  return () => {
+    const worker = spawn();
+    const shared = typeof buffer === 'function' ? buffer() : buffer;
+    // Messages posted before the worker subscribes are queued by Node —
+    // the listener in bindSharedBuffer sees it as soon as the entry runs.
+    worker.postMessage({ type: SHARED_BUFFER, buffer: shared });
+    return worker;
+  };
+}
+
+/**
+ * Worker side: resolve this worker's shared buffer and bind every defined
+ * contract to it (the same call the worker bootstrap makes on INIT_MEMORY).
+ * Checks `workerData.buffer` first — the manual channel — then waits for the
+ * message {@link withSharedBuffer} posts. Rejects on an empty buffer or after
+ * `timeoutMs` so misconfigurations surface instead of hanging.
+ */
+export function bindSharedBuffer(timeoutMs = 10_000): Promise<SharedArrayBuffer> {
+  const fromWorkerData = (workerData as { buffer?: SharedArrayBuffer } | null)?.buffer;
+  if (fromWorkerData) {
+    bindSharedMemories(fromWorkerData);
+    return Promise.resolve(fromWorkerData);
+  }
+  if (isMainThread || !parentPort) {
+    return Promise.reject(new Error('bindSharedBuffer() must be called inside a worker'));
+  }
+  const port = parentPort;
+  return new Promise((resolve, reject) => {
+    const timer = setTimeout(
+      () => reject(new Error(`bindSharedBuffer(): no shared buffer arrived within ${timeoutMs}ms`)),
+      timeoutMs,
+    );
+    port.on('message', (msg: { type?: string; buffer?: SharedArrayBuffer }) => {
+      if (msg?.type !== SHARED_BUFFER) return;
+      clearTimeout(timer);
+      if (!msg.buffer) {
+        reject(new Error('bindSharedBuffer(): the producing side sent an empty buffer'));
+        return;
+      }
+      bindSharedMemories(msg.buffer);
+      resolve(msg.buffer);
+    });
+  });
+}

package/src/worker.ts

@@ -24,8 +24,12 @@ export class NodeWorkerAdapter {
 
   constructor(private readonly worker: NodeWorker) {}
 
-  postMessage(message: unknown): void {
-    this.worker.postMessage(message);
+  postMessage(message: unknown, transferList?: unknown[]): void {
+    if (transferList === undefined) {
+      this.worker.postMessage(message);
+    } else {
+      this.worker.postMessage(message, transferList as never);
+    }
   }
 
   terminate(): void {