arcway 0.1.16 → 0.1.18

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "arcway",
-  "version": "0.1.16",
+  "version": "0.1.18",
   "description": "A convention-based framework for building modular monoliths with strict domain boundaries.",
   "license": "MIT",
   "type": "module",

package/server/boot/cluster-detect.js

@@ -0,0 +1,10 @@
+import cluster from 'node:cluster';
+
+function isLikelyClustered() {
+  if (process.env.pm_id) return true;
+  if (process.env.NODE_APP_INSTANCE) return true;
+  if (cluster.isWorker) return true;
+  return false;
+}
+
+export { isLikelyClustered };

package/server/boot/index.js

@@ -12,6 +12,7 @@ import { PagesRouter } from '../pages/pages-router.js';
 import { SystemRouter } from '../system-routes/index.js';
 import { StaticRouter } from '../static/index.js';
 import { WsRouter } from '../ws/ws-router.js';
+import { createWsBackplane } from '../ws/backplane.js';
 import path from 'node:path';
 
 async function boot(options) {
@@ -89,10 +90,12 @@ async function boot(options) {
     publicDir: path.join(rootDir, 'public'),
   });
 
+  const wsBackplane = createWsBackplane(config, { redis, log });
   const wsRouter = new WsRouter(config.websocket, {
     apiRouter,
     log,
     sessionConfig: config.session,
+    backplane: wsBackplane,
   });
 
   const webServer = new WebServer(config, { log });
@@ -108,7 +111,7 @@ async function boot(options) {
 
   await webServer.listen();
 
-  wsRouter.attachToServer(webServer.server);
+  await wsRouter.attachToServer(webServer.server);
 
   jobRunner.start();
 

package/server/config/modules/websocket.js

@@ -1,10 +1,18 @@
 const DEFAULTS = {
   path: '/ws',
   pingIntervalMs: 30000,
+  driver: 'memory',
 };
 
+const VALID_DRIVERS = new Set(['memory', 'redis']);
+
 function resolve(config) {
   const websocket = { ...DEFAULTS, ...config.websocket };
+  if (!VALID_DRIVERS.has(websocket.driver)) {
+    throw new Error(
+      `Invalid config: websocket.driver="${websocket.driver}" must be one of: ${[...VALID_DRIVERS].join(', ')}`,
+    );
+  }
   return { ...config, websocket };
 }
 

package/server/pages/build-cache.js

@@ -91,6 +91,18 @@ async function cpAtomic(src, dst) {
   }
 }
 
+// Best-effort LRU timestamp bump. File mtime is what enforceCacheBudget orders
+// by, so this is how we record "recently used" for cache hits. Swallow errors —
+// a concurrent evictor may have removed the file already; that's fine.
+async function touchMeta(metaPath) {
+  const now = new Date();
+  try {
+    await fs.utimes(metaPath, now, now);
+  } catch {
+    // Ignore: entry may have been evicted concurrently.
+  }
+}
+
 async function lookupBundle({ rootDir, entryPath, configHash, kind }) {
   const bucket = bucketDir(rootDir, kind);
   const key = entryKey(entryPath);
@@ -113,6 +125,7 @@ async function lookupBundle({ rootDir, entryPath, configHash, kind }) {
   } catch {
     return { hit: false, key, bucket, metaPath, jsPath, mapPath };
   }
+  await touchMeta(metaPath);
   return { hit: true, key, bucket, metaPath, jsPath, mapPath };
 }
 
@@ -194,10 +207,26 @@ async function buildWithCache({
   return { cacheHit: false, metafile: result.metafile };
 }
 
+// Canonical, order-independent hash of a virtualInputs list so stored/current
+// sets can be compared without worrying about caller ordering.
+function hashVirtualInputs(virtualInputs) {
+  if (!virtualInputs || virtualInputs.length === 0) return '';
+  const sorted = [...virtualInputs]
+    .map((v) => ({ name: v.name, digest: v.digest }))
+    .sort((a, b) => a.name.localeCompare(b.name));
+  return sha256(JSON.stringify(sorted));
+}
+
 // Multi-file cache for bundles with several output files (client build with
 // code-splitting). Each cache entry lives under <bucket>/<coarseKey>/ and the
 // index is a sidecar <bucket>/<coarseKey>.meta.json.
-async function lookupMultiFileCache({ rootDir, kind, coarseKey }) {
+//
+// `virtualInputs` (optional) are caller-computed digests that can't be
+// represented as a file path — e.g. the set of class-name tokens extracted
+// from a source tree. Each entry is `{ name, digest }`. The caller must
+// re-compute and pass current values on every lookup; the stored and current
+// digest sets must match exactly for a hit.
+async function lookupMultiFileCache({ rootDir, kind, coarseKey, virtualInputs }) {
   const bucket = bucketDir(rootDir, kind);
   const metaPath = path.join(bucket, `${coarseKey}.meta.json`);
   const cacheDir = path.join(bucket, coarseKey);
@@ -207,6 +236,14 @@ async function lookupMultiFileCache({ rootDir, kind, coarseKey }) {
   if (currentHash === null || currentHash !== meta.inputsHash) {
     return { hit: false, bucket, cacheDir, metaPath };
   }
+  // Compare virtual-input digest sets. If the stored entry has virtualInputs
+  // but the caller omitted them, treat as a miss — a silent hit would serve
+  // stale output for whatever derived state the virtual digest tracks.
+  const storedVirtualHash = meta.virtualInputsHash ?? '';
+  const currentVirtualHash = hashVirtualInputs(virtualInputs);
+  if (storedVirtualHash !== currentVirtualHash) {
+    return { hit: false, bucket, cacheDir, metaPath };
+  }
   // Sanity-check every recorded output file still exists in the cache dir.
   for (const rel of meta.outputs) {
     try {
@@ -215,6 +252,7 @@ async function lookupMultiFileCache({ rootDir, kind, coarseKey }) {
       return { hit: false, bucket, cacheDir, metaPath };
     }
   }
+  await touchMeta(metaPath);
   return { hit: true, bucket, cacheDir, metaPath, meta };
 }
 
@@ -236,6 +274,7 @@ async function storeMultiFileCache({
   destDir,
   outputs,
   inputs,
+  virtualInputs,
   metadata,
 }) {
   const cacheDir = path.join(bucket, coarseKey);
@@ -250,16 +289,166 @@ async function storeMultiFileCache({
     }),
   );
   const inputsHash = await hashInputs(inputs);
+  const virtualInputsHash = hashVirtualInputs(virtualInputs);
   const metaPath = path.join(bucket, `${coarseKey}.meta.json`);
   await writeJsonAtomic(metaPath, {
     inputs,
     inputsHash,
+    virtualInputs: virtualInputs ?? [],
+    virtualInputsHash,
     outputs,
     metadata,
     mtime: Date.now(),
   });
 }
 
+// Default cap for the on-disk cache. Override with ARCWAY_PAGES_CACHE_MAX_BYTES
+// (bytes as an integer). Anything over the cap is LRU-evicted after each store.
+const DEFAULT_CACHE_MAX_BYTES = 500 * 1024 * 1024;
+
+// Newly-written entries are protected from eviction for this many milliseconds
+// to avoid racing with in-flight stores from sibling forks. 5s comfortably
+// exceeds a typical per-entry store (cpAtomic + writeJsonAtomic).
+const DEFAULT_CACHE_GRACE_PERIOD_MS = 5000;
+
+function cacheMaxBytes() {
+  const raw = Number(process.env.ARCWAY_PAGES_CACHE_MAX_BYTES);
+  return Number.isFinite(raw) && raw > 0 ? raw : DEFAULT_CACHE_MAX_BYTES;
+}
+
+async function statOrNull(filePath) {
+  try {
+    return await fs.stat(filePath);
+  } catch {
+    return null;
+  }
+}
+
+// Recursively measure a directory's total size and the most-recent mtime of any
+// file/subdir inside it. Used for multi-file cache entries whose body lives in a
+// sibling dir. Returns {size: 0, mtime: 0} when the dir is missing.
+async function measureDir(dir) {
+  let size = 0;
+  let mtime = 0;
+  let items;
+  try {
+    items = await fs.readdir(dir, { withFileTypes: true });
+  } catch {
+    return { size, mtime };
+  }
+  for (const item of items) {
+    const abs = path.join(dir, item.name);
+    if (item.isDirectory()) {
+      const sub = await measureDir(abs);
+      size += sub.size;
+      if (sub.mtime > mtime) mtime = sub.mtime;
+    } else {
+      const s = await statOrNull(abs);
+      if (s) {
+        size += s.size;
+        if (s.mtimeMs > mtime) mtime = s.mtimeMs;
+      }
+    }
+  }
+  return { size, mtime };
+}
+
+// Enumerate every cache entry across all kinds. Each entry is identified by its
+// sidecar `<key>.meta.json` file. Single-file entries have an accompanying
+// `<key>.js` (+ optional `.js.map`); multi-file entries have a `<coarseKey>/`
+// dir. We collect paths for both shapes so removal is unconditional.
+async function collectCacheEntries(rootDir) {
+  const root = cacheRoot(rootDir);
+  let kindDirs;
+  try {
+    kindDirs = await fs.readdir(root, { withFileTypes: true });
+  } catch {
+    return [];
+  }
+  const entries = [];
+  for (const kindEnt of kindDirs) {
+    if (!kindEnt.isDirectory()) continue;
+    const bucket = path.join(root, kindEnt.name);
+    let files;
+    try {
+      files = await fs.readdir(bucket);
+    } catch {
+      continue;
+    }
+    for (const file of files) {
+      if (!file.endsWith('.meta.json')) continue;
+      const baseKey = file.slice(0, -'.meta.json'.length);
+      const metaPath = path.join(bucket, file);
+      const jsPath = path.join(bucket, `${baseKey}.js`);
+      const mapPath = path.join(bucket, `${baseKey}.js.map`);
+      const dirPath = path.join(bucket, baseKey);
+
+      const metaStat = await statOrNull(metaPath);
+      if (!metaStat) continue;
+      const jsStat = await statOrNull(jsPath);
+      const mapStat = await statOrNull(mapPath);
+      const dirInfo = await measureDir(dirPath);
+
+      const size = metaStat.size + (jsStat?.size ?? 0) + (mapStat?.size ?? 0) + dirInfo.size;
+      // Use the most recent mtime across meta + dir contents. A concurrent
+      // multi-file store rewrites `.meta.json` last but populates the dir
+      // first, so dir mtime can be newer than meta mtime during a store.
+      const mtime = Math.max(metaStat.mtimeMs, dirInfo.mtime);
+      entries.push({ metaPath, jsPath, mapPath, dirPath, size, mtime });
+    }
+  }
+  return entries;
+}
+
+async function removeCacheEntry(entry) {
+  await Promise.allSettled([
+    fs.rm(entry.metaPath, { force: true }),
+    fs.rm(entry.jsPath, { force: true }),
+    fs.rm(entry.mapPath, { force: true }),
+    fs.rm(entry.dirPath, { recursive: true, force: true }),
+  ]);
+}
+
+// Enforce a byte-budget over the on-disk cache. Oldest (by filesystem mtime)
+// entries are evicted first; entries whose mtime is within `gracePeriodMs` of
+// `now` are protected so an in-flight concurrent store isn't yanked out from
+// under a sibling fork. Lock-free and idempotent: multiple forks may run this
+// concurrently and at worst slightly over-evict, which self-corrects on the
+// next cold build.
+async function enforceCacheBudget({
+  rootDir,
+  maxBytes = cacheMaxBytes(),
+  gracePeriodMs = DEFAULT_CACHE_GRACE_PERIOD_MS,
+  now = Date.now(),
+} = {}) {
+  const entries = await collectCacheEntries(rootDir);
+  const totalSize = entries.reduce((s, e) => s + e.size, 0);
+  if (totalSize <= maxBytes) {
+    return { evicted: 0, kept: entries.length, bytesFreed: 0, bytesRemaining: totalSize };
+  }
+
+  const candidates = entries
+    .filter((e) => now - e.mtime >= gracePeriodMs)
+    .sort((a, b) => a.mtime - b.mtime);
+
+  let remaining = totalSize;
+  let freed = 0;
+  let evicted = 0;
+  for (const cand of candidates) {
+    if (remaining <= maxBytes) break;
+    await removeCacheEntry(cand);
+    remaining -= cand.size;
+    freed += cand.size;
+    evicted += 1;
+  }
+  return {
+    evicted,
+    kept: entries.length - evicted,
+    bytesFreed: freed,
+    bytesRemaining: remaining,
+  };
+}
+
 // Walk every cache entry in <rootDir>/node_modules/.cache/arcway-pages/<kind>
 // and drop any whose recorded inputs no longer hash to the stored value (or
 // whose inputs are gone). Used by tests that intentionally mutate fixture
@@ -310,6 +499,8 @@ export {
   buildWithCache,
   computeConfigHash,
   cacheRoot,
+  DEFAULT_CACHE_MAX_BYTES,
+  enforceCacheBudget,
   entryKey,
   ESBUILD_VERSION,
   sha256,

package/server/pages/build-css.js

@@ -11,10 +11,16 @@ import {
   restoreMultiFileCache,
   storeMultiFileCache,
 } from './build-cache.js';
+import { hashClassTokens } from './class-token-scan.js';
 
-// Shallow-walk the pages dir and return every source-shaped file. Used as the
-// cache-invalidation input set when tailwind will scan it via @source.
-async function collectTailwindSources(pagesDir) {
+// Shallow-walk pagesDir for the CSS files tailwind will scan; these are
+// tracked as real file inputs so any byte-level edit invalidates the cache.
+// JSX/TS/etc. are not included here — they go through hashClassTokens(), which
+// produces a virtual-input digest that only busts the cache when the set of
+// string-literal tokens changes. That's a superset of every class name
+// tailwind could emit, and ignores unrelated edits (logic, whitespace,
+// comments) that can't affect the generated CSS.
+async function collectCssFiles(pagesDir) {
   const out = [];
   async function walk(dir) {
     let entries;
@@ -28,10 +34,8 @@ async function collectTailwindSources(pagesDir) {
       if (e.isDirectory()) {
         if (e.name === 'node_modules' || e.name.startsWith('.')) continue;
         await walk(full);
-      } else if (e.isFile()) {
-        if (/\.(jsx?|tsx?|mjs|cjs|css)$/i.test(e.name)) {
-          out.push(full);
-        }
+      } else if (e.isFile() && /\.css$/i.test(e.name)) {
+        out.push(full);
       }
     }
   }
@@ -60,16 +64,26 @@ async function buildCssBundle(pagesDir, outDir, minify, stylesPath, fontFaceCss,
   rootDir = rootDir ?? path.dirname(outDir);
   const coarseKey = computeCssCoarseKey({ minify, fontFaceCss, stylesPath });
 
-  // Inputs that should invalidate the cache on content change.
+  // File inputs: stylesPath + every CSS file under pagesDir. These are hashed
+  // by full content — any byte change should invalidate the cache because raw
+  // CSS ends up in the output verbatim.
   const inputs = [];
-  if (stylesPath) {
-    inputs.push(path.resolve(stylesPath));
-  } else {
-    const scanned = await collectTailwindSources(pagesDir);
-    for (const f of scanned) inputs.push(f);
-  }
+  if (stylesPath) inputs.push(path.resolve(stylesPath));
+  const cssFiles = await collectCssFiles(pagesDir);
+  for (const f of cssFiles) inputs.push(f);
+
+  // Virtual input: a digest over every string-literal token found in the
+  // JSX/TS source tree under pagesDir. Tailwind's class-name emission depends
+  // only on which tokens appear in scanned files — not on surrounding code
+  // structure — so the digest captures the only source signal that actually
+  // matters for CSS output. Editing handler logic, comments, or whitespace
+  // leaves this digest unchanged and the CSS cache is reused.
+  const classTokensDigest = await hashClassTokens(pagesDir);
+  const virtualInputs = [
+    { name: `${path.resolve(pagesDir)}::class-tokens`, digest: classTokensDigest },
+  ];
 
-  const lookup = await lookupMultiFileCache({ rootDir, kind: 'css', coarseKey });
+  const lookup = await lookupMultiFileCache({ rootDir, kind: 'css', coarseKey, virtualInputs });
   if (lookup.hit) {
     await restoreMultiFileCache({
       cacheDir: lookup.cacheDir,
@@ -114,6 +128,7 @@ async function buildCssBundle(pagesDir, outDir, minify, stylesPath, fontFaceCss,
     destDir: clientDir,
     outputs: [cssFileName],
     inputs,
+    virtualInputs,
     metadata: { cssBundleRel },
   });
 

package/server/pages/build.js

@@ -20,6 +20,7 @@ import { buildCssBundle } from './build-css.js';
 import { generateManifest } from './build-manifest.js';
 import { resolveFonts } from './fonts.js';
 import { buildHmrRuntimeBundle } from './hmr.js';
+import { enforceCacheBudget } from './build-cache.js';
 async function buildPages(options) {
   const { rootDir } = options;
   const pagesDir = options.pagesDir ?? path.join(rootDir, 'pages');
@@ -107,6 +108,13 @@ async function buildPages(options) {
       JSON.stringify(manifest, null, 2),
     );
     await atomicSwap(outDir, buildDir);
+    // Keep the on-disk cache bounded. Fire-and-forget so the build returns
+    // immediately; eviction is idempotent across concurrent builds and any
+    // failure is non-fatal (worst case the cache grows past the cap until the
+    // next build). Tracked via `cacheEvictions` for test quiescence.
+    const eviction = enforceCacheBudget({ rootDir }).catch(() => {});
+    cacheEvictions.add(eviction);
+    eviction.finally(() => cacheEvictions.delete(eviction));
     const clientMetafile =
       devMode && clientResult.metafile
         ? rewriteMetafilePaths(clientResult.metafile, buildDir, outDir)
@@ -136,9 +144,12 @@ async function buildPages(options) {
 // Tracks fire-and-forget cleanup promises from failed builds so tests can
 // await `buildPagesIdle()` and see a clean `.build` dir.
 const pendingCleanups = new Set();
+// Tracks fire-and-forget cache-eviction promises from successful builds so
+// tests can await full quiescence and assert on post-eviction cache state.
+const cacheEvictions = new Set();
 async function buildPagesIdle() {
-  while (pendingCleanups.size > 0) {
-    await Promise.allSettled([...pendingCleanups]);
+  while (pendingCleanups.size > 0 || cacheEvictions.size > 0) {
+    await Promise.allSettled([...pendingCleanups, ...cacheEvictions]);
   }
 }
 // Serialize concurrent swaps targeting the same outDir. Without this, two

package/server/pages/class-token-scan.js

@@ -0,0 +1,71 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import crypto from 'node:crypto';
+
+const SOURCE_FILE_PATTERN = /\.(jsx?|tsx?|mjs|cjs)$/i;
+
+// Match the *content* of any string literal — double-quoted, single-quoted, or
+// backtick template. Escape-aware so `\"` doesn't end a double-quoted string
+// prematurely. Template interpolation `${...}` is captured verbatim inside the
+// backtick group; we don't try to parse it out, so interpolation syntax leaks
+// into tokens. That's a benign false-positive signal — if the expression's
+// source changes, the digest changes; tailwind's own oxide scanner has the
+// same boundary limitation.
+const STRING_LITERAL_RE =
+  /"((?:[^"\\]|\\.)*)"|'((?:[^'\\]|\\.)*)'|`((?:[^`\\]|\\.)*)`/g;
+
+// Extract every whitespace-separated token found inside any string literal in
+// `content`. Returns a Set so callers can take a union across files. We don't
+// try to filter to "looks-like-a-tailwind-class" shapes because tailwind v4
+// accepts arbitrary-value classes like `hover:bg-[#fff]` whose superset of
+// allowed characters is broad. Over-inclusion is safe — an extra token only
+// causes unnecessary cache busts on unrelated edits, not stale output.
+function extractClassTokens(content) {
+  const tokens = new Set();
+  let match;
+  while ((match = STRING_LITERAL_RE.exec(content)) !== null) {
+    const body = match[1] ?? match[2] ?? match[3] ?? '';
+    for (const part of body.split(/\s+/)) {
+      if (part.length > 0) tokens.add(part);
+    }
+  }
+  return tokens;
+}
+
+async function walkSources(dir, onFile) {
+  let entries;
+  try {
+    entries = await fs.readdir(dir, { withFileTypes: true });
+  } catch (err) {
+    if (err.code === 'ENOENT') return;
+    throw err;
+  }
+  for (const entry of entries) {
+    const full = path.join(dir, entry.name);
+    if (entry.isDirectory()) {
+      if (entry.name === 'node_modules' || entry.name.startsWith('.')) continue;
+      await walkSources(full, onFile);
+    } else if (entry.isFile() && SOURCE_FILE_PATTERN.test(entry.name)) {
+      await onFile(full);
+    }
+  }
+}
+
+// Union every class-name-shaped token across every JSX/TS source under
+// `pagesDir`, sort, and hash. Sort so the digest is order-independent —
+// adding/removing files only affects the digest via the *set* of tokens, not
+// filesystem enumeration order, which prevents false busts from filesystem
+// reordering across platforms.
+async function hashClassTokens(pagesDir) {
+  const tokens = new Set();
+  await walkSources(pagesDir, async (filePath) => {
+    const content = await fs.readFile(filePath, 'utf-8');
+    for (const token of extractClassTokens(content)) {
+      tokens.add(token);
+    }
+  });
+  const sorted = [...tokens].sort();
+  return crypto.createHash('sha256').update(sorted.join('\n')).digest('hex');
+}
+
+export { extractClassTokens, hashClassTokens };

package/server/web-server.js

@@ -166,7 +166,7 @@ class WebServer {
     // Close WS handlers before shutting down the HTTP server
     for (const { handler } of this.handlers) {
       if (typeof handler.handleUpgrade === 'function' && typeof handler.close === 'function') {
-        try { handler.close(); } catch {}
+        try { await handler.close(); } catch {}
       }
     }
     if (this.server) {

package/server/ws/backplane.js

@@ -0,0 +1,131 @@
+import { randomUUID } from 'node:crypto';
+import { isLikelyClustered } from '../boot/cluster-detect.js';
+
+class WsBackplane {
+  constructor({ redis, log, channel = null }) {
+    this.workerId = randomUUID();
+    this.pub = redis.createClient();
+    this.sub = redis.createClient();
+    this.channel = channel ?? `${redis.keyPrefix}ws:broadcast`;
+    this._log = log?.extend ? log.extend({ logger: 'ws:backplane' }) : log;
+    this._onMessage = null;
+    this._started = false;
+    this._stopped = false;
+    this._subMessageHandler = null;
+    this._subReadyHandler = null;
+  }
+
+  async start({ onMessage }) {
+    if (this._started) return;
+    this._started = true;
+    this._onMessage = onMessage;
+
+    this._subMessageHandler = (channel, raw) => {
+      if (channel !== this.channel) return;
+      let msg;
+      try {
+        msg = JSON.parse(raw);
+      } catch {
+        this._log?.warn?.('WsBackplane: malformed message, skipping');
+        return;
+      }
+      if (msg.workerId === this.workerId) return;
+      try {
+        this._onMessage?.(msg);
+      } catch (err) {
+        this._log?.error?.(`WsBackplane: onMessage handler threw: ${err}`);
+      }
+    };
+    this.sub.on('message', this._subMessageHandler);
+
+    this._subReadyHandler = () => {
+      this.sub.subscribe(this.channel).catch((err) => {
+        this._log?.error?.(`WsBackplane: resubscribe failed: ${err}`);
+      });
+    };
+    this.sub.on('ready', this._subReadyHandler);
+
+    try {
+      await this.sub.subscribe(this.channel);
+    } catch (err) {
+      this._log?.error?.(`WsBackplane: subscribe failed: ${err}`);
+    }
+  }
+
+  publishBroadcast(path, response) {
+    this._publish({
+      workerId: this.workerId,
+      kind: 'broadcast',
+      path,
+      response,
+    });
+  }
+
+  publishSend(socketId, path, response) {
+    this._publish({
+      workerId: this.workerId,
+      kind: 'send',
+      socketId,
+      path,
+      response,
+    });
+  }
+
+  _publish(payload) {
+    if (this._stopped) return;
+    const raw = JSON.stringify(payload);
+    Promise.resolve()
+      .then(() => this.pub.publish(this.channel, raw))
+      .catch((err) => {
+        this._log?.warn?.(`WsBackplane: publish failed: ${err}`);
+      });
+  }
+
+  async stop() {
+    if (this._stopped) return;
+    this._stopped = true;
+    if (this._subMessageHandler) {
+      this.sub.off('message', this._subMessageHandler);
+      this._subMessageHandler = null;
+    }
+    if (this._subReadyHandler) {
+      this.sub.off('ready', this._subReadyHandler);
+      this._subReadyHandler = null;
+    }
+    try {
+      if (this._started) await this.sub.unsubscribe(this.channel);
+    } catch {}
+    try {
+      this.sub.disconnect();
+    } catch {}
+    try {
+      this.pub.disconnect();
+    } catch {}
+    this._onMessage = null;
+  }
+}
+
+function createWsBackplane(config, { redis, log }) {
+  const driver = config?.websocket?.driver ?? 'memory';
+  if (driver === 'memory') {
+    if (isLikelyClustered()) {
+      log?.warn?.(
+        'websocket.driver=memory in a detected cluster environment — cross-worker broadcasts will be lost. Set websocket.driver=redis.',
+      );
+    }
+    return null;
+  }
+  if (driver === 'redis') {
+    if (!redis || redis.inMemory || !redis.connected) {
+      log?.warn?.(
+        'websocket.driver=redis but no real redis connection is available — falling back to in-process broadcasts. Configure redis.url for cluster-safe broadcasts.',
+      );
+      return null;
+    }
+    return new WsBackplane({ redis, log });
+  }
+  return null;
+}
+
+export default WsBackplane;
+export { WsBackplane, createWsBackplane };

package/server/ws/ws-router.js

@@ -14,13 +14,15 @@ class WsRouter {
   _path;
   _enabled;
   _sessionConfig;
+  _backplane;
 
-  constructor(config, { apiRouter, log, sessionConfig }) {
+  constructor(config, { apiRouter, log, sessionConfig, backplane = null }) {
     this._apiRouter = apiRouter;
     this._log = log.extend({ logger: 'ws' });
     this._pingIntervalMs = config?.pingIntervalMs ?? 3e4;
     this._path = config?.path ?? '/ws';
     this._sessionConfig = sessionConfig ?? null;
+    this._backplane = backplane;
 
     const wsRoutes = apiRouter.routes.filter((r) => r.wsEnabled);
     this._enabled = wsRoutes.length > 0;
@@ -30,9 +32,15 @@ class WsRouter {
     }
   }
 
-  attachToServer(httpServer) {
+  async attachToServer(httpServer) {
     if (!this._enabled) return;
 
+    if (this._backplane) {
+      await this._backplane.start({
+        onMessage: (msg) => this._onBackplaneMessage(msg),
+      });
+    }
+
     this._io = new SocketIOServer(httpServer, {
       path: this._path,
       serveClient: false,
@@ -73,7 +81,7 @@ class WsRouter {
     return false;
   }
 
-  close() {
+  async close() {
     if (!this._enabled || !this._io) return;
 
     unregisterWsServer();
@@ -82,10 +90,17 @@ class WsRouter {
     for (const client of this._clients.values()) {
       cleanupPromises.push(this._cleanupClient(client));
     }
+    await Promise.allSettled(cleanupPromises);
 
-    Promise.allSettled(cleanupPromises).then(() => {
-      this._io.close();
-    });
+    if (this._backplane) {
+      try {
+        await this._backplane.stop();
+      } catch (err) {
+        this._log.error('WsBackplane stop error', { error: String(err) });
+      }
+    }
+
+    this._io.close();
   }
 
   // ── Connection lifecycle ──
@@ -289,6 +304,17 @@ class WsRouter {
   }
 
   _sendToSocket(socketId, path, response) {
+    const client = this._clientsBySocketId.get(socketId);
+    if (client) {
+      this._localSendToSocket(socketId, path, response);
+      return;
+    }
+    if (this._backplane) {
+      this._backplane.publishSend(socketId, path, response);
+    }
+  }
+
+  _localSendToSocket(socketId, path, response) {
     const client = this._clientsBySocketId.get(socketId);
     if (!client) return;
     this._send(client, {
@@ -300,6 +326,13 @@ class WsRouter {
   }
 
   _broadcastToPath(path, response) {
+    if (this._backplane) {
+      this._backplane.publishBroadcast(path, response);
+    }
+    this._localBroadcastToPath(path, response);
+  }
+
+  _localBroadcastToPath(path, response) {
     const msg = {
       path,
       data: response.data,
@@ -313,6 +346,15 @@ class WsRouter {
     }
   }
 
+  _onBackplaneMessage(msg) {
+    if (!msg || typeof msg !== 'object') return;
+    if (msg.kind === 'broadcast') {
+      this._localBroadcastToPath(msg.path, msg.response);
+    } else if (msg.kind === 'send') {
+      this._localSendToSocket(msg.socketId, msg.path, msg.response);
+    }
+  }
+
   async _cleanupClient(client) {
     for (const [path, sub] of client.subscriptions) {
       if (sub.cleanup) {