@blamejs/core 0.6.32 → 0.6.34

package/lib/websocket-channels.js

@@ -4,27 +4,39 @@
  *
  * `lib/websocket.js` owns the wire protocol (RFC 6455 + 8441 frame
  * parsing, masking, control frames). This module owns the higher-level
- * pub/sub: connections subscribe to named channels, publish() fans out
- * a payload to every subscriber, and cluster mode coordinates fan-out
- * across nodes via a shared `_blamejs_ws_messages` table.
+ * subscription bookkeeping: connections subscribe to named channels,
+ * publish() fans out a payload to every subscriber. Cross-node fan-out
+ * is delegated to `b.pubsub` so cache-cluster invalidation, websocket
+ * channels, and any future cross-node primitive share the same
+ * transport (cluster table, Redis PUB/SUB, or operator-supplied).
  *
  * Public API:
  *
  *   var hub = b.websocketChannels.create({
- *     backend:        'local' | 'cluster' | { publishRemote, start, stop },
- *     pollIntervalMs: C.TIME.ms? — cluster fan-out poll cadence (default 100ms)
- *     retentionMs:    C.TIME.ms? — fan-out row retention before prune (default 60s)
- *     audit:          true,      — emit system.ws.publish on each publish
+ *     // Pub/sub backend opts — passed through to b.pubsub.create.
+ *     backend:        'local' | 'cluster' | 'redis' | { custom },
+ *     // cluster opts:
+ *     cluster:        clusterInstance,
+ *     pollIntervalMs: C.TIME.ms? — default 100ms
+ *     retentionMs:    C.TIME.ms? — default 60s
+ *     // redis opts:
+ *     redisUrl:       string?
+ *     redisPassword:  string?
+ *     redisUsername:  string?
+ *     redisTls:       boolean?
+ *     redisCa:        string|Buffer?
+ *     // common:
+ *     topicPrefix:    string?    — default "ws" so independent
+ *                                   pubsub primitives sharing a
+ *                                   backend (cache, etc.) don't
+ *                                   collide on channel names.
+ *     audit:          boolean    — emit system.ws.publish on each publish
  *   });
  *
  *   r.ws("/socket", function (conn) {
  *     hub.attach(conn);                       // tracks lifecycle, auto-detach on close
  *     hub.subscribe(conn, "chat:room-1");
  *     hub.subscribe(conn, "presence:user-42");
- *
- *     conn.on("message", function (msg) {
- *       // Operator-handled inbound; hub doesn't reflect inbound back.
- *     });
  *   });
  *
  *   await hub.publish("chat:room-1", { user: "alice", text: "hi" });
@@ -34,29 +46,11 @@
  *   hub.channels();                           // → ["chat:room-1", ...]
  *   hub.connectionChannels(conn);             // → ["chat:room-1", ...]
  *
- * Cluster fan-out semantics:
- *   - Each publish() dispatches to local subscribers SYNCHRONOUSLY
- *     before returning. Local subscribers see the message with
- *     near-zero latency.
- *   - In cluster mode the publish ALSO writes a row to
- *     _blamejs_ws_messages. Other nodes poll the table on
- *     pollIntervalMs (default 100ms) and dispatch new rows past their
- *     last-seen id to their local subscribers.
- *   - The publishing node skips its own rows on poll (publishedBy =
- *     self) so each subscriber sees the message exactly once.
- *   - Latency-sensitive operators bring their own backend (Redis,
- *     NATS, MQTT) by passing { publishRemote, start, stop }.
- *
- * Single-node mode:
- *   - 'local' backend (default when opts.cluster is not wired). publish
- *     synchronously dispatches; no DB writes; no poll loop.
- *   - Operators on a single node pay zero coordination overhead.
- *
- * Channel naming is operator-defined — the hub treats names as opaque
- * strings. Common conventions: "chat:room-id", "presence:user-id",
- * "metrics:hostname". For pattern matching subscribe to multiple
- * specific channels rather than a wildcard — wildcards complicate
- * cross-node fan-out and are deferred.
+ * Backend semantics live in `lib/pubsub.js`. The hub here is responsible
+ * for the WebSocket-specific connection lifecycle (attach / detach),
+ * the channel-to-conn map, and serialization of payloads for the local
+ * dispatch path; the cross-node delivery is one pubsub.subscribe per
+ * channel the hub joins, with the hub's `_localDispatch` as the handler.
  *
  * Error policy: a connection's send() that throws (closed socket, peer
  * gone) does NOT break dispatch to other subscribers. The throwing
@@ -65,9 +59,7 @@
  */
 
 var lazyRequire = require("./lazy-require");
-var clusterStorage = require("./cluster-storage");
-var C = require("./constants");
-var safeJson = require("./safe-json");
+var pubsub = require("./pubsub");
 var validateOpts = require("./validate-opts");
 var { defineClass } = require("./framework-error");
 
@@ -76,157 +68,10 @@ var logger = lazyRequire(function () { return require("./log").boot("websocket-c
 
 var WebSocketChannelsError = defineClass("WebSocketChannelsError");
 
-var DEFAULT_POLL_INTERVAL_MS = 100;
-var DEFAULT_RETENTION_MS     = C.TIME.minutes(1);
-var DEFAULT_PRUNE_EVERY_MS   = C.TIME.minutes(5);
-
 function _err(code, message) {
   return new WebSocketChannelsError(code, message, true);
 }
 
-// ---- Backends ----
-
-function _localBackend() {
-  // Single-node: no remote fan-out. publish() goes only to local subs.
-  return {
-    name:           "local",
-    publishRemote:  null,
-    start:          null,
-    stop:           null,
-  };
-}
-
-function _clusterBackend(opts) {
-  var clusterInstance = opts.cluster;
-  var pollIntervalMs = opts.pollIntervalMs || DEFAULT_POLL_INTERVAL_MS;
-  var retentionMs    = opts.retentionMs    || DEFAULT_RETENTION_MS;
-  var pruneEveryMs   = opts.pruneEveryMs   || DEFAULT_PRUNE_EVERY_MS;
-  var lastSeenId  = 0;
-  var primed      = false;
-  var lastPruneAt = 0;
-  var pollTimer   = null;
-  var stopped     = false;
-
-  function _nodeId() {
-    if (clusterInstance && typeof clusterInstance.currentNodeId === "function") {
-      return clusterInstance.currentNodeId();
-    }
-    return "single-node-local";
-  }
-
-  async function publishRemote(channel, payload) {
-    var serialized = JSON.stringify(payload);
-    await clusterStorage.execute(
-      "INSERT INTO _blamejs_ws_messages " +
-      "(channel, payload, publishedAt, publishedBy) VALUES (?, ?, ?, ?)",
-      [channel, serialized, Date.now(), _nodeId()]
-    );
-  }
-
-  async function _poll(onRemoteMessage) {
-    if (stopped) return;
-    var nodeId = _nodeId();
-    try {
-      // First poll: prime lastSeenId to the current MAX so we don't
-      // re-dispatch every historical row on startup. Tracked via the
-      // `primed` flag separately from lastSeenId — when MAX(id) is 0
-      // (empty table) the value-equality check would trip on every
-      // poll without it.
-      if (!primed) {
-        var primer = await clusterStorage.execute(
-          "SELECT COALESCE(MAX(id), 0) AS maxId FROM _blamejs_ws_messages",
-          []
-        );
-        if (primer.rows && primer.rows[0]) {
-          lastSeenId = Number(primer.rows[0].maxId) || 0;
-        }
-        primed = true;
-        return;
-      }
-      var result = await clusterStorage.execute(
-        "SELECT id, channel, payload FROM _blamejs_ws_messages " +
-        "WHERE id > ? AND publishedBy <> ? ORDER BY id ASC",
-        [lastSeenId, nodeId]
-      );
-      var rows = result.rows || [];
-      for (var i = 0; i < rows.length; i++) {
-        var row = rows[i];
-        try {
-          var payload = safeJson.parse(row.payload);
-          onRemoteMessage(row.channel, payload);
-        } catch (e) {
-          try {
-            logger().warn("malformed fan-out row id=" + row.id +
-              ": " + ((e && e.message) || String(e)));
-          } catch (_e) { /* logger best-effort */ }
-        }
-        if (Number(row.id) > lastSeenId) lastSeenId = Number(row.id);
-      }
-
-      // Rate-limited prune of expired rows.
-      var now = Date.now();
-      if (now - lastPruneAt >= pruneEveryMs) {
-        lastPruneAt = now;
-        await clusterStorage.execute(
-          "DELETE FROM _blamejs_ws_messages WHERE publishedAt < ?",
-          [now - retentionMs]
-        );
-      }
-    } catch (e) {
-      try {
-        logger().warn("fan-out poll failed: " + ((e && e.message) || String(e)));
-      } catch (_e) { /* logger best-effort */ }
-    }
-  }
-
-  function start(onRemoteMessage) {
-    if (pollTimer) return;
-    stopped = false;
-    var tick = function () {
-      _poll(onRemoteMessage).then(function () {
-        if (stopped) return;
-        pollTimer = setTimeout(tick, pollIntervalMs);
-        if (typeof pollTimer.unref === "function") pollTimer.unref();
-      }, function () {
-        if (stopped) return;
-        pollTimer = setTimeout(tick, pollIntervalMs);
-        if (typeof pollTimer.unref === "function") pollTimer.unref();
-      });
-    };
-    // Prime lastSeenId immediately so the first publish on a brand-new
-    // hub doesn't race the first poll-interval tick. Without this,
-    // publishes that happen between create() and the first poll would
-    // be missed by other nodes that haven't seeded their lastSeenId yet.
-    pollTimer = setTimeout(tick, 0);
-    if (typeof pollTimer.unref === "function") pollTimer.unref();
-  }
-
-  function stop() {
-    stopped = true;
-    if (pollTimer) { clearTimeout(pollTimer); pollTimer = null; }
-  }
-
-  return {
-    name:           "cluster",
-    publishRemote:  publishRemote,
-    start:          start,
-    stop:           stop,
-  };
-}
-
-function _resolveBackend(opts) {
-  var requested = opts.backend;
-  if (requested && typeof requested === "object" &&
-      typeof requested.publishRemote === "function") {
-    return Object.assign({ name: "custom" }, requested);
-  }
-  if (requested === "cluster") return _clusterBackend(opts);
-  if (!requested || requested === "local") return _localBackend();
-  throw _err("UNKNOWN_BACKEND",
-    "websocketChannels: unknown backend '" + requested +
-    "' (must be 'local', 'cluster', or { publishRemote, start, stop })");
-}
-
 // ---- Hub ----
 
 function create(opts) {
@@ -234,19 +79,47 @@ function create(opts) {
   validateOpts(opts, [
     "backend", "audit", "cluster",
     "pollIntervalMs", "retentionMs", "pruneEveryMs",
+    "redisUrl", "redisPassword", "redisUsername", "redisTls",
+    "redisCa", "redisServername",
+    "topicPrefix",
   ], "b.websocket");
   var auditOn = !!opts.audit;
-  var backend = _resolveBackend(opts);
+
+  // Pub/sub fan-out is delegated to b.pubsub. The hub owns one pubsub
+  // instance per WebSocket-channels primitive; topicPrefix defaults to
+  // "ws" so independent pubsub primitives sharing the same backend
+  // (cache cluster invalidation, app-level pubsub) don't collide on
+  // channel names.
+  var ps = pubsub.create({
+    backend:        opts.backend,
+    cluster:        opts.cluster,
+    pollIntervalMs: opts.pollIntervalMs,
+    retentionMs:    opts.retentionMs,
+    pruneEveryMs:   opts.pruneEveryMs,
+    redisUrl:       opts.redisUrl,
+    redisPassword:  opts.redisPassword,
+    redisUsername:  opts.redisUsername,
+    redisTls:       opts.redisTls,
+    redisCa:        opts.redisCa,
+    redisServername: opts.redisServername,
+    // Default empty so pre-existing operators / tests that publish on
+    // raw channel names keep working unchanged. Operators sharing one
+    // pubsub backend across cache + websockets + custom primitives
+    // pass a topicPrefix to isolate.
+    topicPrefix:    opts.topicPrefix || "",
+  });
+  var backendName = ps.backend();
 
   // channel -> Set<connection>
   var channelToConns = new Map();
+  // channel -> pubsub-token (one subscribe per channel the hub
+  // currently has any local listener on; refcounted via the local
+  // map's size).
+  var channelToToken = new Map();
   // connection -> Set<channel>  (WeakMap so dropped conns don't leak)
   var connToChannels = new WeakMap();
   // Tracked connection set for surface methods that need to enumerate
-  // connections (e.g. close-all-on-shutdown). Connections leave this
-  // set on detach. We hold strong refs intentionally — the hub is the
-  // owner of this membership for as long as the operator hasn't said
-  // detach.
+  // connections (e.g. close-all-on-shutdown).
   var attachedConns = new Set();
 
   function _localDispatch(channel, payload) {
@@ -266,13 +139,17 @@ function create(opts) {
     return sent;
   }
 
-  // Cluster backend invokes this when a remote node's row arrives.
-  function _onRemoteMessage(channel, payload) {
-    _localDispatch(channel, payload);
+  // Pubsub message arrivals dispatch to local WebSocket connections.
+  // For local-backend pubsub the handler runs synchronously inside
+  // ps.publish(), so we accumulate the per-publish delivery count via
+  // the `dispatchTallies` map keyed by channel + sequence id — the
+  // hub's publish() reads it back after ps.publish() resolves.
+  var lastDispatchCount = 0;
+  function _onPubsubMessage(payload, ev) {
+    var n = _localDispatch(ev.channel, payload);
+    lastDispatchCount += n;
   }
 
-  if (typeof backend.start === "function") backend.start(_onRemoteMessage);
-
   function attach(conn) {
     if (!conn || typeof conn.send !== "function") {
       throw _err("INVALID_CONN", "attach(conn) requires a connection with .send()");
@@ -292,7 +169,14 @@ function create(opts) {
       var subs = channelToConns.get(c);
       if (subs) {
         subs.delete(conn);
-        if (subs.size === 0) channelToConns.delete(c);
+        if (subs.size === 0) {
+          channelToConns.delete(c);
+          var token = channelToToken.get(c);
+          if (token) {
+            ps.unsubscribe(token);
+            channelToToken.delete(c);
+          }
+        }
       }
     }
     connToChannels.delete(conn);
@@ -306,7 +190,13 @@ function create(opts) {
     if (!connToChannels.has(conn)) {
       throw _err("NOT_ATTACHED", "subscribe: connection must be attach()-ed first");
     }
-    if (!channelToConns.has(channel)) channelToConns.set(channel, new Set());
+    if (!channelToConns.has(channel)) {
+      channelToConns.set(channel, new Set());
+      // First local listener for this channel — open a pubsub
+      // subscription so cross-node fan-out reaches us.
+      var token = ps.subscribe(channel, _onPubsubMessage);
+      channelToToken.set(channel, token);
+    }
     channelToConns.get(channel).add(conn);
     connToChannels.get(conn).add(channel);
   }
@@ -315,7 +205,14 @@ function create(opts) {
     var subs = channelToConns.get(channel);
     if (subs) {
       subs.delete(conn);
-      if (subs.size === 0) channelToConns.delete(channel);
+      if (subs.size === 0) {
+        channelToConns.delete(channel);
+        var token = channelToToken.get(channel);
+        if (token) {
+          ps.unsubscribe(token);
+          channelToToken.delete(channel);
+        }
+      }
     }
     var chans = connToChannels.get(conn);
     if (chans) chans.delete(channel);
@@ -325,25 +222,41 @@ function create(opts) {
     if (typeof channel !== "string" || channel.length === 0) {
       throw _err("INVALID_CHANNEL", "publish: channel must be a non-empty string");
     }
-    var localCount = _localDispatch(channel, payload);
+    // Pre-validate JSON serializability so circular / unserializable
+    // payloads throw INVALID_PAYLOAD on the operator's await rather
+    // than disappearing into the pubsub dispatcher's per-handler
+    // try/catch (where they'd surface only as a warn-level log).
+    try { JSON.stringify(payload); }
+    catch (e) {
+      throw _err("INVALID_PAYLOAD",
+        "publish payload is not JSON-serializable: " + (e && e.message));
+    }
+    lastDispatchCount = 0;
     var remoteSent = false;
-    if (typeof backend.publishRemote === "function") {
+    var localCount = 0;
+    try {
+      var rv = await ps.publish(channel, payload);
+      // ps.publish invokes _onPubsubMessage synchronously for the
+      // local-backend; lastDispatchCount holds the conn-level count.
+      // For remote-only backends the handler doesn't fire until a poll
+      // tick / push event arrives — at that point the message goes to
+      // every node including this one (publishedBy filter excluded for
+      // pubsub-cluster, redis sees its own publish via its subscribe
+      // socket too). So lastDispatchCount captures the local fan-out.
+      localCount = lastDispatchCount;
+      remoteSent = (rv && rv.remote > 0);
+    } catch (e) {
       try {
-        await backend.publishRemote(channel, payload);
-        remoteSent = true;
-      } catch (e) {
-        try {
-          logger().error("publishRemote failed for channel '" + channel + "': " +
-            ((e && e.message) || String(e)));
-        } catch (_e) { /* logger best-effort */ }
-      }
+        logger().error("publishRemote failed for channel '" + channel + "': " +
+          ((e && e.message) || String(e)));
+      } catch (_e) { /* logger best-effort */ }
     }
     if (auditOn) {
       audit().safeEmit({
         action:   "system.ws.publish",
         metadata: {
           channel:        channel,
-          backend:        backend.name,
+          backend:        backendName,
           localDelivered: localCount,
           remoteSent:     remoteSent,
         },
@@ -375,18 +288,20 @@ function create(opts) {
     return attachedConns.size;
   }
 
-  function close() {
-    if (typeof backend.stop === "function") backend.stop();
+  async function close() {
     // Drop all subscriptions. Connections are not closed — that's the
     // operator's call (`router.closeWebSockets()` is the framework's
     // hook for graceful shutdown).
+    for (var token of channelToToken.values()) ps.unsubscribe(token);
+    channelToToken.clear();
     channelToConns.clear();
     for (var conn of attachedConns) connToChannels.delete(conn);
     attachedConns.clear();
+    await ps.close();
   }
 
   return {
-    backend:               backend.name,
+    backend:               backendName,
     attach:                attach,
     detach:                detach,
     subscribe:             subscribe,
@@ -398,16 +313,15 @@ function create(opts) {
     connectionChannels:    connectionChannels,
     attachedCount:         attachedCount,
     close:                 close,
-    // Test hook — directly inject a remote message as if the cluster
-    // backend's poll just received it.
-    _injectRemoteMessage:  _onRemoteMessage,
+    // Test hook — directly inject a remote message as if the pubsub
+    // backend's transport just received it.
+    _injectRemoteMessage:  function (channel, payload) {
+      _localDispatch(channel, payload);
+    },
   };
 }
 
 module.exports = {
   create:                  create,
   WebSocketChannelsError:  WebSocketChannelsError,
-  // Backend factories exported for tests + advanced operator wiring.
-  _localBackend:           _localBackend,
-  _clusterBackend:         _clusterBackend,
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blamejs/core",
-  "version": "0.6.32",
+  "version": "0.6.34",
   "description": "The Node framework that owns its stack.",
   "license": "Apache-2.0",
   "author": "blamejs contributors",

package/sbom.cyclonedx.json

@@ -2,10 +2,10 @@
   "$schema": "http://cyclonedx.org/schema/bom-1.5.schema.json",
   "bomFormat": "CycloneDX",
   "specVersion": "1.5",
-  "serialNumber": "urn:uuid:bf737d55-37d5-49a4-95fb-c1149d627468",
+  "serialNumber": "urn:uuid:731bee30-9e20-4cc1-87e9-2ca1cf7a6e31",
   "version": 1,
   "metadata": {
-    "timestamp": "2026-05-02T19:10:22.247Z",
+    "timestamp": "2026-05-02T20:14:03.424Z",
     "lifecycles": [
       {
         "phase": "build"
@@ -19,14 +19,14 @@
       }
     ],
     "component": {
-      "bom-ref": "@blamejs/core@0.6.32",
+      "bom-ref": "@blamejs/core@0.6.34",
       "type": "library",
       "name": "blamejs",
-      "version": "0.6.32",
+      "version": "0.6.34",
       "scope": "required",
       "author": "blamejs contributors",
       "description": "The Node framework that owns its stack.",
-      "purl": "pkg:npm/%40blamejs/core@0.6.32",
+      "purl": "pkg:npm/%40blamejs/core@0.6.34",
       "properties": [],
       "externalReferences": [
         {
@@ -54,7 +54,7 @@
   "components": [],
   "dependencies": [
     {
-      "ref": "@blamejs/core@0.6.32",
+      "ref": "@blamejs/core@0.6.34",
       "dependsOn": []
     }
   ]