@blamejs/core 0.6.33 → 0.6.35

package/lib/pubsub-cluster.js

@@ -0,0 +1,154 @@
+"use strict";
+/**
+ * pubsub-cluster — table-polling backend for `lib/pubsub.js`.
+ *
+ * Generalizes the polling pattern previously inlined in
+ * `lib/websocket-channels.js`. One shared table
+ * `_blamejs_pubsub_messages` carries every cross-node fan-out event;
+ * subscribers on each node poll the table at `pollIntervalMs` and
+ * dispatch new rows past their last-seen id. Independent pubsub
+ * instances on the same database isolate via `topicPrefix` (see
+ * lib/pubsub.js).
+ *
+ * Trade-offs vs. the redis backend:
+ *   - No external dependency — re-uses the cluster DB the framework
+ *     already requires for leader election, queues, sessions, etc.
+ *   - Latency floor is the polling interval (default 100ms). Operators
+ *     wanting <10ms cross-node latency switch to the redis backend.
+ *   - Survives transient network blips between app nodes; missed rows
+ *     are picked up on the next poll until retentionMs elapses.
+ *
+ * Schema: `_blamejs_pubsub_messages (id, topic, payload, publishedAt,
+ * publishedBy)`. Created by `lib/cluster-storage.js` migrations.
+ */
+var clusterStorage = require("./cluster-storage");
+var C = require("./constants");
+var lazyRequire = require("./lazy-require");
+
+var logger = lazyRequire(function () { return require("./log").boot("pubsub-cluster"); });
+
+var DEFAULT_POLL_INTERVAL_MS = 100;
+var DEFAULT_RETENTION_MS     = C.TIME.minutes(1);
+var DEFAULT_PRUNE_EVERY_MS   = C.TIME.minutes(5);
+
+function create(opts) {
+  var clusterInstance = opts.cluster;
+  var pollIntervalMs = Number(opts.pollIntervalMs) || DEFAULT_POLL_INTERVAL_MS;
+  var retentionMs    = Number(opts.retentionMs)    || DEFAULT_RETENTION_MS;
+  var pruneEveryMs   = Number(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(scopedChannel, payload) {
+    var serialized = JSON.stringify(payload);
+    await clusterStorage.execute(
+      "INSERT INTO _blamejs_pubsub_messages " +
+      "(topic, payload, publishedAt, publishedBy) VALUES (?, ?, ?, ?)",
+      [scopedChannel, serialized, Date.now(), _nodeId()]
+    );
+    return { remote: 1 };
+  }
+
+  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.
+      if (!primed) {
+        var primer = await clusterStorage.execute(
+          "SELECT COALESCE(MAX(id), 0) AS maxId FROM _blamejs_pubsub_messages",
+          []
+        );
+        if (primer.rows && primer.rows[0]) {
+          lastSeenId = Number(primer.rows[0].maxId) || 0;
+        }
+        primed = true;
+        return;
+      }
+      var result = await clusterStorage.execute(
+        "SELECT id, topic, payload, publishedAt, publishedBy " +
+        "FROM _blamejs_pubsub_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 {
+          onRemoteMessage(row.topic, row.payload, {
+            publishedBy: row.publishedBy,
+            publishedAt: Number(row.publishedAt) || null,
+          });
+        } catch (e) {
+          try { logger().warn("malformed pubsub 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_pubsub_messages WHERE publishedAt < ?",
+          [now - retentionMs]
+        );
+      }
+    } catch (e) {
+      try { logger().warn("pubsub-cluster poll failed: " +
+        ((e && e.message) || String(e))); }
+      catch (_e) { /* */ }
+    }
+  }
+
+  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();
+      });
+    };
+    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,
+    // Cluster backend doesn't need explicit subscribeRemote — every
+    // node sees every row. The pubsub.js wrapper still tracks the
+    // remoteSubCount for parity with backends that DO need it.
+    subscribeRemote:   null,
+    unsubscribeRemote: null,
+  };
+}
+
+module.exports = { create: create };

package/lib/pubsub-redis.js

@@ -0,0 +1,160 @@
+"use strict";
+/**
+ * pubsub-redis — Redis PUB/SUB backend for `lib/pubsub.js`.
+ *
+ * Two connections per pubsub instance:
+ *
+ *   subscriberConn — placed in subscribe mode via SUBSCRIBE /
+ *                    PSUBSCRIBE. The `lib/redis-client.js` push hook
+ *                    (`setOnPushMessage`) demultiplexes server-pushed
+ *                    "message" / "pmessage" frames from
+ *                    SUBSCRIBE/UNSUBSCRIBE acks. Subscribe-mode
+ *                    connections can't issue arbitrary commands;
+ *                    splitting publisher off is mandatory.
+ *   publisherConn  — issues PUBLISH commands against the same Redis
+ *                    instance. Uses normal command pipelining.
+ *
+ * The framework's `lib/redis-client.js` is single-connection-per-create
+ * — both connections use the same options (URL / password / TLS / CA).
+ *
+ * Channels are passed through to Redis with the topicPrefix already
+ * applied by `lib/pubsub.js`; this backend doesn't add any naming
+ * conventions of its own.
+ */
+var crypto = require("node:crypto");
+var redisClient = require("./redis-client");
+var lazyRequire = require("./lazy-require");
+
+var logger = lazyRequire(function () { return require("./log").boot("pubsub-redis"); });
+
+function create(opts) {
+  if (typeof opts.redisUrl !== "string" || opts.redisUrl.length === 0) {
+    throw new Error("pubsub-redis: redisUrl is required");
+  }
+  // Per-instance nonce stamped on every outgoing payload so the
+  // SUBSCRIBE socket can recognize its own publishes and skip
+  // dispatching them (the framework's pubsub.publish() already did
+  // the local dispatch synchronously before awaiting the remote
+  // write — without this filter every same-instance publish would
+  // double-fire local handlers).
+  var instanceNonce = crypto.randomBytes(8).toString("hex");
+
+  var clientOpts = {
+    url:                  opts.redisUrl,
+    password:             opts.redisPassword,
+    username:             opts.redisUsername,
+    tls:                  opts.redisTls,
+    ca:                   opts.redisCa,
+    servername:           opts.redisServername,
+    connectTimeoutMs:     opts.redisConnectTimeoutMs,
+    commandTimeoutMs:     opts.redisCommandTimeoutMs,
+    maxReconnectAttempts: opts.redisMaxReconnectAttempts,
+  };
+
+  var subscriberConn = null;
+  var publisherConn  = null;
+  var connectPromise = null;
+  var stopped = false;
+  var savedOnRemoteMessage = null;
+
+  // Inbound demultiplex — the redis-client routes "message" /
+  // "pmessage" frames here. Strip the {_psnode, p} envelope; if the
+  // nonce matches this instance, the message is our own publish
+  // looping back through Redis — skip dispatch (pubsub.js already
+  // dispatched locally in publish()). Otherwise forward to the
+  // dispatcher with the unwrapped payload string.
+  function _onPush(ev) {
+    if (!savedOnRemoteMessage) return;
+    var rawPayload = ev.payload;
+    var payloadStr = Buffer.isBuffer(rawPayload)
+      ? rawPayload.toString("utf8") : String(rawPayload);
+    var inner = payloadStr;
+    try {
+      var envelope = JSON.parse(payloadStr);
+      if (envelope && typeof envelope === "object" &&
+          typeof envelope._psnode === "string") {
+        if (envelope._psnode === instanceNonce) return;  // own publish
+        inner = JSON.stringify(envelope.p);
+      }
+    } catch (_e) {
+      // Not an envelope — forward as-is for operators publishing raw
+      // strings via redis CLI etc.
+    }
+    try {
+      savedOnRemoteMessage(ev.channel, inner, {
+        pattern: ev.pattern || null,
+      });
+    } catch (e) {
+      try { logger().warn("pubsub-redis push dispatch failed: " +
+        ((e && e.message) || String(e))); }
+      catch (_e) { /* */ }
+    }
+  }
+
+  async function _ensureConnected() {
+    if (stopped) throw new Error("pubsub-redis: backend stopped");
+    if (subscriberConn && publisherConn) return;
+    if (connectPromise) return connectPromise;
+    connectPromise = (async function () {
+      subscriberConn = redisClient.create(Object.assign({}, clientOpts, {
+        onPushMessage: _onPush,
+      }));
+      publisherConn = redisClient.create(clientOpts);
+      await Promise.all([subscriberConn.connect(), publisherConn.connect()]);
+    })();
+    try { await connectPromise; }
+    finally { connectPromise = null; }
+  }
+
+  async function publishRemote(scopedChannel, payload) {
+    await _ensureConnected();
+    var serialized = JSON.stringify({ _psnode: instanceNonce, p: payload });
+    var n = await publisherConn.command("PUBLISH", scopedChannel, serialized);
+    return { remote: Number(n) || 0 };
+  }
+
+  async function subscribeRemote(scopedChannel, isPattern) {
+    await _ensureConnected();
+    var cmd = isPattern ? "PSUBSCRIBE" : "SUBSCRIBE";
+    await subscriberConn.command(cmd, scopedChannel);
+  }
+
+  async function unsubscribeRemote(scopedChannel, isPattern) {
+    if (!subscriberConn || !subscriberConn.isOpen()) return;
+    var cmd = isPattern ? "PUNSUBSCRIBE" : "UNSUBSCRIBE";
+    try { await subscriberConn.command(cmd, scopedChannel); }
+    catch (_e) { /* unsubscribe failure is informational */ }
+  }
+
+  function start(onRemoteMessage) {
+    savedOnRemoteMessage = onRemoteMessage;
+    // Lazy connect — first subscribe / publish opens the sockets. This
+    // keeps `b.pubsub.create()` synchronous-safe on a misconfigured
+    // redis URL: the validation throw lands on the first publish/subscribe
+    // call, where the operator can catch it.
+  }
+
+  async function stop() {
+    stopped = true;
+    savedOnRemoteMessage = null;
+    if (subscriberConn) {
+      try { await subscriberConn.close(); } catch (_e) {}
+      subscriberConn = null;
+    }
+    if (publisherConn) {
+      try { await publisherConn.close(); } catch (_e) {}
+      publisherConn = null;
+    }
+  }
+
+  return {
+    name:              "redis",
+    publishRemote:     publishRemote,
+    subscribeRemote:   subscribeRemote,
+    unsubscribeRemote: unsubscribeRemote,
+    start:             start,
+    stop:              stop,
+  };
+}
+
+module.exports = { create: create };

package/lib/pubsub.js

@@ -0,0 +1,357 @@
+"use strict";
+/**
+ * pubsub — distributed pub/sub primitive.
+ *
+ * Generalizes the cluster-table fan-out pattern that previously lived
+ * inline in `lib/websocket-channels.js` and the `NOT_SUPPORTED` cache
+ * cluster `invalidateTag` path. Three backends:
+ *
+ *   local    — in-process Map<channel, Set<handler>>; publish dispatches
+ *              SYNCHRONOUSLY before returning. Single-node deploys pay
+ *              zero coordination overhead.
+ *   cluster  — shared `_blamejs_pubsub_messages` table polled at
+ *              pollIntervalMs; publish writes a row + dispatches locally;
+ *              other nodes pick up rows via `id > lastSeenId AND
+ *              publishedBy <> selfNodeId`. Default cluster mode for any
+ *              `b.cluster`-aware deploy.
+ *   redis    — Redis PUB/SUB on the bespoke `lib/redis-client.js`. One
+ *              connection per pubsub instance enters subscribe mode
+ *              (demultiplexed via `setOnPushMessage`); publish goes
+ *              through a separate command-mode connection.
+ *
+ * Operator API:
+ *
+ *   var ps = b.pubsub.create({
+ *     backend:        'local' | 'cluster' | 'redis' | { custom },
+ *     // cluster opts
+ *     cluster:        clusterInstance,
+ *     pollIntervalMs: C.TIME.ms?    — default 100ms
+ *     retentionMs:    C.TIME.ms?    — default 60s
+ *     pruneEveryMs:   C.TIME.ms?    — default 5min
+ *     // redis opts
+ *     redisUrl:       string        — required for redis backend
+ *     redisPassword:  string?
+ *     redisUsername:  string?
+ *     redisTls:       boolean?
+ *     redisCa:        string|Buffer?
+ *     redisServername: string?
+ *     // common
+ *     topicPrefix:    string?       — every publish/subscribe channel
+ *                                     scoped to `<topicPrefix>:<channel>`
+ *                                     so independent pubsub instances
+ *                                     sharing a backend don't collide.
+ *     audit:          boolean?      — default false. When true emits
+ *                                     `system.pubsub.publish` per call.
+ *   });
+ *
+ *   var token = ps.subscribe(channel, function (payload, ev) {
+ *     // payload is whatever publish() received (objects survive JSON
+ *     // round-trip on remote backends; on the local backend the
+ *     // reference is passed through). ev = { channel, source: 'local'
+ *     // | 'remote', publishedBy?, publishedAt? }.
+ *   });
+ *   ps.unsubscribe(token);
+ *
+ *   await ps.publish(channel, payload);          // returns { local, remote? }
+ *
+ *   await ps.close();                            // tears down backend
+ *
+ * Local dispatch always happens BEFORE the publish() promise resolves,
+ * regardless of backend — same-node subscribers see the payload with
+ * near-zero latency. The remote write is awaited so the caller knows
+ * the cross-node fan-out completed.
+ *
+ * Subscription handler errors are caught and logged via the framework's
+ * boot logger; they never abort dispatch to other handlers on the same
+ * channel.
+ *
+ * Channel naming is operator-defined — pubsub treats names as opaque
+ * strings (with the optional topicPrefix prepended). Pattern subscribe
+ * (Redis-style `news.*`) is exposed via `subscribePattern(pattern,
+ * handler)`; not every backend supports it (cluster-table backend
+ * matches client-side, redis backend uses PSUBSCRIBE, local backend
+ * matches client-side too).
+ */
+var lazyRequire = require("./lazy-require");
+var safeJson = require("./safe-json");
+var validateOpts = require("./validate-opts");
+var { defineClass } = require("./framework-error");
+
+var audit  = lazyRequire(function () { return require("./audit"); });
+var logger = lazyRequire(function () { return require("./log").boot("pubsub"); });
+
+var PubsubError = defineClass("PubsubError");
+
+function _err(code, message) { return new PubsubError(code, message, true); }
+
+function _resolveBackend(opts) {
+  var requested = opts.backend;
+  if (requested && typeof requested === "object") {
+    if (typeof requested.publishRemote !== "function" ||
+        typeof requested.start !== "function" ||
+        typeof requested.stop !== "function") {
+      throw _err("BAD_BACKEND",
+        "pubsub: custom backend must implement { publishRemote, start, stop }");
+    }
+    return Object.assign({ name: "custom" }, requested);
+  }
+  if (!requested || requested === "local") {
+    return { name: "local", publishRemote: null, start: null, stop: null };
+  }
+  if (requested === "cluster") {
+    return require("./pubsub-cluster").create(opts);
+  }
+  if (requested === "redis") {
+    return require("./pubsub-redis").create(opts);
+  }
+  throw _err("UNKNOWN_BACKEND",
+    "pubsub: unknown backend '" + requested +
+    "' (must be 'local', 'cluster', 'redis', or { publishRemote, start, stop })");
+}
+
+function _matchPattern(pattern, channel) {
+  // Glob-style: '*' matches any single segment; '**' matches any
+  // suffix. Operators wanting full Redis-pattern semantics use the
+  // redis backend's PSUBSCRIBE which the redis client routes natively.
+  if (pattern === channel) return true;
+  if (pattern.indexOf("*") === -1) return false;
+  var rx = "^" + pattern
+    .split("**").map(function (p) {
+      return p.split("*").map(function (s) {
+        return s.replace(/[.+?^${}()|[\]\\]/g, "\\$&");
+      }).join("[^.]*");
+    }).join(".*") + "$";
+  return new RegExp(rx).test(channel);
+}
+
+function create(opts) {
+  opts = opts || {};
+  validateOpts(opts, [
+    "backend", "cluster", "audit", "topicPrefix",
+    "pollIntervalMs", "retentionMs", "pruneEveryMs",
+    "redisUrl", "redisPassword", "redisUsername", "redisTls",
+    "redisCa", "redisServername",
+  ], "b.pubsub");
+
+  var topicPrefix = opts.topicPrefix || "";
+  var auditOn = !!opts.audit;
+  var backend = _resolveBackend(opts);
+
+  // channel -> Set<token-record>; token-record is { channel, handler, isPattern }.
+  // Tokens are objects so unsubscribe is O(1) without hashing.
+  var exactSubs   = new Map();
+  var patternSubs = new Set();
+  var closed      = false;
+
+  function _scoped(channel) {
+    return topicPrefix ? topicPrefix + ":" + channel : channel;
+  }
+  function _unscope(scopedChannel) {
+    if (!topicPrefix) return scopedChannel;
+    if (scopedChannel.indexOf(topicPrefix + ":") === 0) {
+      return scopedChannel.slice(topicPrefix.length + 1);
+    }
+    return scopedChannel;
+  }
+
+  function _localDispatch(channel, payload, source, meta) {
+    var ev = Object.assign({ channel: channel, source: source || "local" },
+                            meta || {});
+    var dispatched = 0;
+    var exact = exactSubs.get(channel);
+    if (exact) {
+      for (var rec of exact) {
+        try { rec.handler(payload, ev); dispatched++; }
+        catch (e) {
+          try { logger().warn("pubsub handler threw on '" + channel +
+            "': " + ((e && e.message) || String(e))); }
+          catch (_e) { /* logger best-effort */ }
+        }
+      }
+    }
+    for (var prec of patternSubs) {
+      if (_matchPattern(prec.channel, channel)) {
+        try { prec.handler(payload, ev); dispatched++; }
+        catch (e) {
+          try { logger().warn("pubsub pattern handler threw on '" +
+            channel + "' (pattern '" + prec.channel + "'): " +
+            ((e && e.message) || String(e))); }
+          catch (_e) { /* logger best-effort */ }
+        }
+      }
+    }
+    return dispatched;
+  }
+
+  // Backend invokes this when a remote node's record arrives.
+  function _onRemoteMessage(scopedChannel, rawPayload, meta) {
+    var channel = _unscope(scopedChannel);
+    var payload;
+    try {
+      payload = (typeof rawPayload === "string" ||
+                 (rawPayload && Buffer.isBuffer(rawPayload)))
+        ? safeJson.parse(Buffer.isBuffer(rawPayload)
+                          ? rawPayload.toString("utf8")
+                          : rawPayload)
+        : rawPayload;
+    } catch (e) {
+      try { logger().warn("pubsub remote payload parse failed on '" +
+        channel + "': " + ((e && e.message) || String(e))); }
+      catch (_e) { /* */ }
+      return;
+    }
+    _localDispatch(channel, payload, "remote", meta || {});
+  }
+
+  if (typeof backend.start === "function") {
+    backend.start(_onRemoteMessage);
+  }
+
+  // Track which scoped channels we've subscribed remotely so we can
+  // ref-count and unsubscribe when the last local handler goes away.
+  var remoteSubCount = new Map();
+
+  async function _maybeRemoteSubscribe(scopedChannel, isPattern) {
+    var n = (remoteSubCount.get(scopedChannel) || 0) + 1;
+    remoteSubCount.set(scopedChannel, n);
+    if (n === 1 && typeof backend.subscribeRemote === "function") {
+      try { await backend.subscribeRemote(scopedChannel, isPattern); }
+      catch (e) {
+        // Roll back the count so a retry isn't blocked by stale bookkeeping.
+        remoteSubCount.set(scopedChannel, n - 1);
+        throw e;
+      }
+    }
+  }
+  async function _maybeRemoteUnsubscribe(scopedChannel, isPattern) {
+    var n = (remoteSubCount.get(scopedChannel) || 1) - 1;
+    if (n <= 0) {
+      remoteSubCount.delete(scopedChannel);
+      if (typeof backend.unsubscribeRemote === "function") {
+        try { await backend.unsubscribeRemote(scopedChannel, isPattern); }
+        catch (_e) { /* unsubscribe failure is informational */ }
+      }
+    } else {
+      remoteSubCount.set(scopedChannel, n);
+    }
+  }
+
+  function subscribe(channel, handler) {
+    if (closed) throw _err("CLOSED", "pubsub.subscribe: instance closed");
+    if (typeof channel !== "string" || channel.length === 0) {
+      throw _err("BAD_OPT", "pubsub.subscribe: channel must be a non-empty string");
+    }
+    if (typeof handler !== "function") {
+      throw _err("BAD_OPT", "pubsub.subscribe: handler must be a function");
+    }
+    var rec = { channel: channel, handler: handler, isPattern: false };
+    var set = exactSubs.get(channel);
+    if (!set) { set = new Set(); exactSubs.set(channel, set); }
+    set.add(rec);
+    // Remote subscribe is fire-and-forget from the caller's perspective;
+    // the redis backend awaits the SUBSCRIBE ack internally before its
+    // promise resolves, so a sync subscribe() that returns the token
+    // doesn't strand the operator if they immediately publish().
+    _maybeRemoteSubscribe(_scoped(channel), false).catch(function (e) {
+      try { logger().warn("pubsub subscribeRemote('" + channel + "') failed: " +
+        ((e && e.message) || String(e))); }
+      catch (_e) { /* */ }
+    });
+    return rec;
+  }
+
+  function subscribePattern(pattern, handler) {
+    if (closed) throw _err("CLOSED", "pubsub.subscribePattern: instance closed");
+    if (typeof pattern !== "string" || pattern.length === 0) {
+      throw _err("BAD_OPT", "pubsub.subscribePattern: pattern must be a non-empty string");
+    }
+    if (typeof handler !== "function") {
+      throw _err("BAD_OPT", "pubsub.subscribePattern: handler must be a function");
+    }
+    var rec = { channel: pattern, handler: handler, isPattern: true };
+    patternSubs.add(rec);
+    _maybeRemoteSubscribe(_scoped(pattern), true).catch(function (e) {
+      try { logger().warn("pubsub subscribePatternRemote('" + pattern + "') failed: " +
+        ((e && e.message) || String(e))); }
+      catch (_e) { /* */ }
+    });
+    return rec;
+  }
+
+  function unsubscribe(token) {
+    if (!token || typeof token !== "object") return;
+    if (token.isPattern) {
+      if (patternSubs.delete(token)) {
+        _maybeRemoteUnsubscribe(_scoped(token.channel), true);
+      }
+      return;
+    }
+    var set = exactSubs.get(token.channel);
+    if (set && set.delete(token)) {
+      if (set.size === 0) exactSubs.delete(token.channel);
+      _maybeRemoteUnsubscribe(_scoped(token.channel), false);
+    }
+  }
+
+  async function publish(channel, payload) {
+    if (closed) throw _err("CLOSED", "pubsub.publish: instance closed");
+    if (typeof channel !== "string" || channel.length === 0) {
+      throw _err("BAD_OPT", "pubsub.publish: channel must be a non-empty string");
+    }
+    var local = _localDispatch(channel, payload, "local");
+    var remote = 0;
+    if (typeof backend.publishRemote === "function") {
+      try {
+        var rv = await backend.publishRemote(_scoped(channel), payload);
+        remote = (rv && typeof rv === "object" && Number.isFinite(rv.remote))
+          ? rv.remote : 1;
+      } catch (e) {
+        if (auditOn) {
+          try { audit().safeEmit("system.pubsub.publish-failed", {
+            channel: channel, error: (e && e.message) || String(e),
+          }); } catch (_e) { /* */ }
+        }
+        throw e;
+      }
+    }
+    if (auditOn) {
+      try { audit().safeEmit("system.pubsub.publish", {
+        channel: channel, localDispatched: local, remoteWritten: remote,
+      }); } catch (_e) { /* */ }
+    }
+    return { local: local, remote: remote };
+  }
+
+  async function close() {
+    if (closed) return;
+    closed = true;
+    if (typeof backend.stop === "function") {
+      try { await backend.stop(); } catch (_e) { /* close failure is informational */ }
+    }
+    exactSubs.clear();
+    patternSubs.clear();
+    remoteSubCount.clear();
+  }
+
+  return {
+    backend:          function () { return backend.name; },
+    subscribe:        subscribe,
+    subscribePattern: subscribePattern,
+    unsubscribe:      unsubscribe,
+    publish:          publish,
+    close:            close,
+    // Diagnostic — exposed for tests + observability.
+    _state: function () {
+      return {
+        backend:        backend.name,
+        exactChannels:  exactSubs.size,
+        patternCount:   patternSubs.size,
+        remoteSubCount: remoteSubCount.size,
+        closed:         closed,
+      };
+    },
+    _matchPatternForTest: _matchPattern,
+  };
+}
+
+module.exports = { create: create, PubsubError: PubsubError };