arcway 0.1.17 → 0.1.18

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "arcway",
-  "version": "0.1.17",
+  "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/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) {