@blamejs/core 0.6.33 → 0.6.34

package/CHANGELOG.md

@@ -8,6 +8,7 @@ upgrading across more than a few patches at a time.
 
 ## v0.6.x
 
+- **0.6.34** (2026-05-02) — distributed pub/sub primitive. **`b.pubsub`** — single API for cross-node fan-out across the framework, with three backends. `local` dispatches in-process to registered handlers (zero coordination overhead for single-node deploys); `cluster` polls a shared `_blamejs_pubsub_messages` table at `pollIntervalMs` (default 100ms) and dispatches new rows past `lastSeenId` from other nodes (publishedBy=self filter prevents loopback); `redis` opens a SUBSCRIBE-mode connection on `lib/redis-client.js` (now with new push-message demultiplexing — server-pushed `["message", channel, payload]` and `["pmessage", pattern, channel, payload]` arrays route through `setOnPushMessage` instead of consuming a pending request slot, while SUBSCRIBE / UNSUBSCRIBE acks still flow through the normal command pipeline). Per-instance nonce stamped on outgoing redis payloads so the SUBSCRIBE socket recognizes its own publishes and skips the loopback (without it every same-instance publish would fire local handlers twice). Operator API: `ps.subscribe(channel, handler) → token`, `ps.subscribePattern(pattern, handler) → token` (glob-style on local + cluster, native PSUBSCRIBE on redis), `ps.unsubscribe(token)`, `await ps.publish(channel, payload) → { local, remote }`, `await ps.close()`. `topicPrefix` opt scopes channel names so independent pubsub instances sharing a backend (cache invalidation + websocket channels + custom) don't collide. Handler errors are caught + logged via the framework's boot logger; they never abort dispatch to other handlers on the same channel. **`lib/websocket-channels.js`** — replaces the inline cluster-poll-and-fan-out logic with `b.pubsub` consumption. The hub now owns one pubsub instance per primitive; cross-node delivery is `pubsub.subscribe` per channel the hub joins, with the hub's `_localDispatch` as the handler. Per-channel pubsub subscription is refcounted by local conn count (subscribe on first conn, unsubscribe on last). The `_blamejs_ws_messages` table is renamed to `_blamejs_pubsub_messages` (column `channel` → `topic`) reflecting the generalization; pre-v1, no compat shim — operators upgrading wipe the previous table (which carried only ephemeral fan-out rows with default 60s retention). **`b.cache.create({ invalidationPubsub })`** — passing a `b.pubsub.create()` instance auto-publishes on every successful `del` / `clear` / `invalidateTag`, and subscribes for the same events so other cache instances on other nodes (or processes sharing the pubsub backend) react locally — primarily useful for the memory backend so stale per-node entries don't survive a global tag wipe. Re-entrancy guard prevents inbound invalidation events from re-publishing (no fan-out loops). Tests: 29 layer-0 assertions covering local + cluster behavior, topicPrefix isolation, pattern subscribe, handler error isolation, post-close error path, end-to-end cache invalidationPubsub fan-out via local pubsub. 10 live integration assertions against the docker redis container covering single-instance round-trip, PSUBSCRIBE pattern, cross-instance fan-out, and cache invalidation through redis PUB/SUB. Smoke 6817 / wiki e2e 178 / per-primitive integration 15 files / wiki integration 32 / shellcheck clean / eslint clean.
 - **0.6.33** (2026-05-02) — log-stream sinks parity sweep. **`b.logStream` syslog sink (RFC 5424)** — first-class `protocol: "syslog"` for `b.logStream.init({ sinks: { ... } })`; new module `lib/log-stream-syslog.js`. URL-driven transport selection: `udp://host:514` / `tcp://host:514` / `tls://host:6514`. UDP is best-effort one-datagram-per-record; TCP / TLS use RFC 6587 octet-counting framing (`<length> <message>`) so collectors that prefer it over the older non-transparent newline framing parse cleanly. TLS is TLS 1.3 minimum; operators with private CAs pass `ca` (PEM string or array) for trust pinning, `servername` for SNI override (auto-suppressed on IP literals per the v0.6.28 redis-client convention). Outgoing records are formatted with PRI = `(facility << 3) | severity`, default facility `local0` (16), severity mapped from the framework's level field (debug=7 / info=6 / warn=4 / error=3); operators override via `facility`, `appName` (default `blamejs`), `procId` (default `process.pid`), `hostname` (default `os.hostname()`), `structuredData` (default `-`). Meta is JSON-encoded into the MSG body so the structured payload survives the wire as a single token. TCP / TLS reconnect with exponential backoff (default 250ms→30s); records buffer during the down window with `bufferLimit`-bounded oldest-drop semantics, replay on reconnect. `close()` waits up to 3s for an in-flight (re)connect to drain the buffer before tearing down — without this the slower TLS handshake raced fire-and-forget shutdown emits and silently dropped records. Operator-supplied `onDrop({reason, batch, error})` surfaces every drop class (`overflow` / `udp-send-error` / `write-error` / `sink-closed`). Removed `syslog` from `DEFERRED_PROTOCOLS`. **`b.logStream` cloudwatch sink: `autoCreate`** — pass `{ autoCreate: true }` to have the framework issue `CreateLogGroup` + `CreateLogStream` on first emit so operators provisioning collectors via env vars / runbooks don't need a separate aws-cli step. Idempotent: AWS's `ResourceAlreadyExistsException` is treated as success on both calls. Hard failures (5xx, AccessDenied, etc.) drop the batch with `onDrop` reason `autocreate-failed`. Default remains `autoCreate: false` so the AWS posture (operator pre-creates via aws / CDK / Terraform) stays the recommended path; `autoCreate` exists for ephemeral / dynamic-stream deployments where pre-provisioning is impractical. **Test suite**: 19 new framework-level cloudwatch assertions cover autoCreate fires both Create calls in order before PutLogEvents, ResourceAlreadyExists doesn't abort the post-create PutLogEvents, hard 5xx during CreateLogGroup drops the batch via `onDrop`, autoCreate=false skips Create calls entirely. Live syslog integration covers UDP / TCP wire delivery against the docker syslog-ng container (`/var/log/blamejs-test.log`) plus an in-process `tls.createServer` receiver that asserts the on-the-wire RFC 6587 octet-counting framing + RFC 5424 PRI / timestamp / structured-data slot the framework emits over TLS. **Test infrastructure fix**: `docker/init/generate-certs.sh` was overwriting an existing CA when re-run with `.complete` removed, invalidating every previously-issued leaf cert; now reuses an existing `(ca.crt, ca.key)` pair across `.complete`-only resets and only generates a fresh CA when neither file is present. Smoke 6790 / wiki e2e 178 / per-primitive integration 14 files (log-stream up from 16→18 checks, cloudwatch suite up from 39→58 assertions) / wiki integration 32 / shellcheck clean / eslint clean.
 - **0.6.32** (2026-05-02) — E1 from the v0.6.x scope plan. **`b.cache` Redis backend** — first-class `backend: "redis"` for `b.cache.create({...})`, no operator-supplied glue needed. New module `lib/cache-redis.js` consumes `lib/redis-client.js` directly; storage layout: `<namespace>:e:<key>` (STRING, JSON-encoded value, PEXPIREAT-bounded), `<namespace>:t:<tag>` (SET, cacheKeys carrying that tag — powers `invalidateTag` fan-out), `<namespace>:k:<key>:tags` (SET, tags this key carries — powers per-key tag cleanup on `del`/`set`-overwrite, expires alongside the entry). TTL is enforced by Redis itself (PEXPIREAT) so the framework's sweeper is a no-op for this backend; sliding TTL bumps the entry's expiry on every read when `slidingTtl: true` AND `ttlMs` is finite. New opts on `cache.create`: `redisUrl` (required when `backend: "redis"`), `redisPassword`, `redisUsername`, `redisTls`, `redisCa` (private-CA trust pinning per v0.6.28), `redisServername`, `redisConnectTimeoutMs`, `redisCommandTimeoutMs`, `redisMaxReconnectAttempts`. Concurrency: invalidateTag filters out ghost entries (key already PEXPIRE'd from the keyspace but lingering in a tag SET) by EXISTS-checking before del. Lazy connect — `cache.create({backend:"redis"})` stays sync-safe; first op opens the socket. Tests: 10 new live integration assertions on top of the existing memory + custom-backend coverage (set+get round-trip, has, del, complex JSON value round-trip, short-TTL Redis-side expiry, multi-tag invalidateTag fan-out + preservation of untagged entries, wrap() single-flight memoization through Redis). Smoke 6780 / wiki e2e 178 / per-primitive integration 14 files (cache up from 15→25 checks) / wiki integration green.
 - **0.6.31** (2026-05-02) — lazy-deferral cleanup wave from v0.6.27. **A1: queue-redis priority ordering** — `b.queue.enqueue({ priority })` on the Redis backend now matches queue-local's `ORDER BY priority DESC, availableAt ASC, enqueuedAt ASC` semantics. The Redis ZSET stays scored by availableAt only (so ZRANGEBYSCORE 0..nowMs cleanly filters ready vs not-yet-ready jobs), but `LEASE_LUA` now over-fetches `maxRows*5` candidates by score, HMGETs priority + availableAt + enqueuedAt for each, sorts server-side in Lua by the same triple queue-local sorts on, and leases the top `maxRows`. Closes the v0.6.27 deferral that punted priority ordering as "ZSET-incompatible". **A2: queue-redis flow `dependsOn` cascade** — `b.queue.enqueue({ flowId, flowChildName, dependsOn })` on the Redis backend now releases dependent jobs when their parents complete, mirroring queue-local's `_maybeReleaseFlowChildren`. A per-flow `<prefix>:flow:<flowId>` Redis SET tracks every job in the flow; `complete()` walks the set, looks up siblings whose `dependsOn` includes the just-completed job (by id OR `flowChildName`) AND every other dep is also satisfied, and HSET-bumps their `availableAt` to now + ZADDs them into the ready zset. The flow set persists across `complete()` calls so a later sibling's deps check can still find earlier-done parents by name; `purge()` cleans the set on queue teardown. Closes the v0.6.27 deferral. **A4: WebSocket per-message-deflate (RFC 7692)** — `b.websocket.handleUpgrade` negotiates the `permessage-deflate` extension when the client offers it, accepting `client_max_window_bits` / `server_max_window_bits` constraints (8-15 range, default 15) and always asserting `client_no_context_takeover` + `server_no_context_takeover` so every message uses a fresh zlib state. The connection's send path compresses TEXT/BINARY frames via `zlib.deflateRawSync`, strips the 4-byte `0x00 0x00 0xff 0xff` trailer per RFC 7692 §7.2.1, and sets RSV1 on the first frame of each compressed message. The receive path appends the trailer back and inflates via `zlib.inflateRawSync`. RSV1 on a continuation frame, RSV1 without negotiated extension, RSV2/RSV3 set, and decompressed payload exceeding `maxMessageBytes` all close with the appropriate RFC 6455 status (`PROTOCOL_ERROR`, `INVALID_PAYLOAD`, `MESSAGE_TOO_BIG`). Operator opt-out: pass `permessageDeflate: false` to `handleUpgrade` to refuse the extension even when offered. Tests cover the 101-handshake echo of negotiated params, real compression on a redundant payload (4000 bytes → ~30 bytes on the wire), uncompressed-frame round-trip on the same connection (mixed-mode per RFC 7692 §6), and unknown-extension graceful ignore. v0.6.27's third lazy deferral A3 (TLS-redis live test) was already covered by `test/integration/redis-client-tls.test.js` shipped in v0.6.28. Smoke 6780 / wiki e2e 178 / per-primitive integration 14 files green / wiki integration green.

package/README.md

@@ -46,7 +46,7 @@ The framework bundles the surface a typical Node app reaches for. Every primitiv
 - **Crypto** — envelope-versioned PQC at rest (ML-KEM-1024 + P-384 hybrid, XChaCha20-Poly1305, SHAKE256), vault sealing, field-level crypto + cryptographic erasure (`b.cryptoField.eraseRow`), signed webhooks (SLH-DSA-SHAKE-256f), ECIES API encryption (`b.crypto`, `b.vault`, `b.webhook`); pure-JS mTLS CA that issues clientAuth / serverAuth / dual-EKU certs with SAN entries and auto-detects the highest-PQC signature algorithm the vendored x509 library accepts (today: ECDSA-P384-SHA384 bridge; self-upgrades to SLH-DSA / ML-DSA when the X.509 ecosystem catches up), PQC TLS gates inbound + outbound (`b.mtlsCa`, `b.pqcGate`, `b.pqcAgent`).
 - **HTTP** — router with schema-validated routes + OpenAPI publication; full middleware stack (CSRF, CORS, rate-limit, security headers, CSP nonce, body parser, compression, SSE, request log, request-time DB role binding via `b.middleware.dbRoleFor`, in-process CIDR fence via `b.middleware.networkAllowlist`) wired by `createApp`; HTTP/1.1 + HTTP/2 outbound client with SSRF gate (cloud-metadata IPs hard-denied unconditionally; private / loopback / link-local overridable per call), scheme + userinfo + per-host (wildcard / per-method) destination allowlist, redirects, multipart, interceptors, progress, encrypted cookie jar (`b.httpClient`, `b.ssrfGuard`, `b.safeUrl`); operator-tunable network configurability — env-driven NTP / NTS (RFC 8915 authenticated time), IPv4-or-IPv6 NTP servers, DNS with IPv6 / DoH / DoT (private-CA trust pinning via `opts.ca`) / cache / lookup timeout, outbound HTTP proxy (`HTTP_PROXY` / `HTTPS_PROXY` / `NO_PROXY`), runtime DPI trust-store CA additions, application-level heartbeats, TCP socket defaults (`b.network`).
 - **Defensive parsers** — `b.safeJson`, `b.safeBuffer`, `b.safeSql`, `b.safeSchema`, `b.parsers` (XML / TOML / YAML / .env), `b.config` (schema-validated env), `b.fileType` magic-byte content classification with deny-on-upload categories (image / document / archive / executable / etc.).
-- **Communication** — WebSockets with channel/room fan-out across cluster replicas (`b.websocket`, `b.websocketChannels`); mail with multipart + attachments + DKIM + calendar invites + bounce intake (`b.mail`, `b.mailBounce`); generic notification dispatcher with operator-supplied transports (`b.notify`).
+- **Communication** — WebSockets with channel/room fan-out across cluster replicas (`b.websocket`, `b.websocketChannels`); generic distributed pub/sub with cluster-table / Redis PUB/SUB / custom backends (`b.pubsub`); mail with multipart + attachments + DKIM + calendar invites + bounce intake (`b.mail`, `b.mailBounce`); generic notification dispatcher with operator-supplied transports (`b.notify`).
 - **Observability** — tamper-evident audit chain with SLH-DSA-signed checkpoints, metrics, tracing (OTel pass-through when wired), PII redaction, log-stream sinks (local file rotation, generic webhook, OTLP/HTTP-JSON to an OTel collector, AWS CloudWatch Logs via SigV4 with optional autoCreate, RFC 5424 syslog over UDP/TCP/TLS), OTLP/HTTP-JSON exporter for traces + metrics (`b.audit`, `b.metrics`, `b.tracing`, `b.redact`, `b.logStream`, `b.otelExport`); operator-callable boot-time security policy assertions (`b.security.assertProduction`) and tamper-evident config-baseline drift detection signed with the audit-signing key (`b.configDrift`).
 - **i18n** — CLDR plural rules, Accept-Language negotiation, Intl formatters, RTL (`b.i18n`).
 - **Format helpers** — RFC 4180 CSV with Excel formula-injection prevention (`b.csv`), RFC 9562 UUID v4 + v7 (`b.uuid`), URL-safe slugs (`b.slug`), TZ-aware datetime (`b.time`), ZIP creation (`b.archive`), HMAC-signed cursor pagination (`b.pagination`), HTML form rendering + validation + CSRF (`b.forms`).

package/index.js

@@ -113,6 +113,7 @@ var time = require("./lib/time");
 var uuid = require("./lib/uuid");
 var mail = require("./lib/mail");
 var mailBounce = require("./lib/mail-bounce");
+var pubsub = require("./lib/pubsub");
 var websocketChannels = require("./lib/websocket-channels");
 var nonceStore = require("./lib/nonce-store");
 var scheduler = require("./lib/scheduler");
@@ -227,6 +228,7 @@ module.exports = {
   uuid:             uuid,
   mail:             mail,
   mailBounce:       mailBounce,
+  pubsub:            pubsub,
   websocketChannels: websocketChannels,
   nonceStore:        nonceStore,
   scheduler:        scheduler,

package/lib/cache.js

@@ -739,6 +739,15 @@ function create(opts) {
     "redisUrl", "redisPassword", "redisUsername", "redisTls", "redisCa",
     "redisServername", "redisConnectTimeoutMs", "redisCommandTimeoutMs",
     "redisMaxReconnectAttempts",
+    // Cross-node invalidation: when set, every successful
+    // del/clear/invalidateTag publishes an event on the supplied
+    // pubsub instance. Other cache instances on other nodes (or in
+    // other processes sharing the pubsub backend) react locally —
+    // mostly useful for the memory backend so stale per-node entries
+    // don't survive a global tag wipe. The cluster + redis backends
+    // are coherent by virtue of their shared store, but a hot
+    // memory-tier on top of either still benefits.
+    "invalidationPubsub",
   ], "cache");
   _validateCreateOpts(opts);
 
@@ -756,6 +765,19 @@ function create(opts) {
   var audit            = opts.audit || null;
   var operatorObs      = opts.observability || null;
   var clock            = opts.clock || function () { return Date.now(); };
+  var invalidationPubsub = opts.invalidationPubsub || null;
+  if (invalidationPubsub && (
+        typeof invalidationPubsub.publish !== "function" ||
+        typeof invalidationPubsub.subscribe !== "function" ||
+        typeof invalidationPubsub.unsubscribe !== "function")) {
+    throw _err("BAD_OPT",
+      "cache.create: invalidationPubsub must implement { publish, subscribe, unsubscribe } (b.pubsub.create instance)");
+  }
+  var invalidationChannel = "cache:" + namespace + ":invalidate";
+  var invalidationToken = null;
+  // Re-entrancy guard — when we receive an invalidation event from
+  // another node we MUST NOT re-publish it (infinite fan-out loop).
+  var inboundInvalidation = false;
 
   function emitObs(name, labels) {
     try {
@@ -908,6 +930,7 @@ function create(opts) {
     }
     if (existed) emitObs("cache.del", { namespace: namespace });
     softExpiry.delete(key);
+    _publishInvalidation({ kind: "del", key: key });
     return existed;
   }
 
@@ -946,6 +969,7 @@ function create(opts) {
     inflight.clear();
     swrInflight.clear();
     softExpiry.clear();
+    _publishInvalidation({ kind: "clear" });
     return purged;
   }
 
@@ -1003,6 +1027,7 @@ function create(opts) {
     // drop matches clear()'s safer-than-stale posture.
     inflight.clear();
     swrInflight.clear();
+    _publishInvalidation({ kind: "tag", tag: tag });
     return purged;
   }
 
@@ -1134,9 +1159,45 @@ function create(opts) {
     return promise;
   }
 
+  function _publishInvalidation(ev) {
+    if (!invalidationPubsub || inboundInvalidation) return;
+    try { invalidationPubsub.publish(invalidationChannel, ev); }
+    catch (_e) { /* publish best-effort — local invalidation already happened */ }
+  }
+
+  async function _onInboundInvalidation(ev /*, meta */) {
+    if (!ev || closed) return;
+    inboundInvalidation = true;
+    try {
+      if (ev.kind === "tag" && typeof ev.tag === "string" &&
+          typeof backend.invalidateTag === "function") {
+        try { await backend.invalidateTag(ev.tag); } catch (_e) {}
+      } else if (ev.kind === "del" && typeof ev.key === "string") {
+        try { await backend.del(ev.key); } catch (_e) {}
+      } else if (ev.kind === "clear") {
+        try { await backend.clear(); } catch (_e) {}
+      }
+      // Wipe local in-flight memoization so a freshly-invalidated key
+      // can't resolve from a still-pending fetch on this node.
+      inflight.clear();
+      swrInflight.clear();
+      softExpiry.clear();
+    } finally {
+      inboundInvalidation = false;
+    }
+  }
+
+  if (invalidationPubsub) {
+    invalidationToken = invalidationPubsub.subscribe(invalidationChannel, _onInboundInvalidation);
+  }
+
   async function close() {
     if (closed) return;
     closed = true;
+    if (invalidationPubsub && invalidationToken) {
+      try { invalidationPubsub.unsubscribe(invalidationToken); } catch (_e) {}
+      invalidationToken = null;
+    }
     inflight.clear();
     swrInflight.clear();
     softExpiry.clear();

package/lib/db.js

@@ -110,7 +110,7 @@ var RESERVED_TABLE_NAMES = new Set([
   "_blamejs_audit_purge_anchor",
   "_blamejs_scheduler_ticks",
   "_blamejs_rate_limit_counters",
-  "_blamejs_ws_messages",
+  "_blamejs_pubsub_messages",
   "_blamejs_api_encrypt_nonces",
   "_blamejs_api_keys",
   "_blamejs_cache",
@@ -260,15 +260,16 @@ var FRAMEWORK_SCHEMA = [
     sealedFields: [],
   },
   {
-    // _blamejs_ws_messages — cluster fan-out for the WebSocket
-    // channel hub. publish() on any node writes a row here; the
-    // other nodes poll for new ids and dispatch to their local
-    // subscribers. Rows older than the configured retention window
-    // are pruned by the hub on a rate-limited basis.
-    name: "_blamejs_ws_messages",
+    // _blamejs_pubsub_messages — cluster fan-out for `b.pubsub` (the
+    // generalization of the previous WebSocket-specific table). Any
+    // pubsub instance using the `cluster` backend writes a row on
+    // publish; other nodes poll for new ids and dispatch to their
+    // local subscribers. Rows older than the configured retention
+    // window are pruned by the backend on a rate-limited basis.
+    name: "_blamejs_pubsub_messages",
     columns: {
       id:          "INTEGER PRIMARY KEY AUTOINCREMENT",
-      channel:     "TEXT NOT NULL",
+      topic:       "TEXT NOT NULL",
       payload:     "TEXT NOT NULL",
       publishedAt: "INTEGER NOT NULL",
       publishedBy: "TEXT NOT NULL",

package/lib/framework-schema.js

@@ -94,7 +94,7 @@ var LOCAL_TO_EXTERNAL = Object.freeze({
   // WebSocket channel-hub cluster fan-out — publish() writes a row,
   // other nodes poll for new ids and dispatch to their local
   // subscribers. Same dual-storage shape as sessions / jobs / etc.
-  _blamejs_ws_messages:        "_blamejs_ws_messages",
+  _blamejs_pubsub_messages:        "_blamejs_pubsub_messages",
   _blamejs_api_encrypt_nonces: "_blamejs_api_encrypt_nonces",
   // _blamejs_api_keys — operator-facing API-key registry table for the
   // b.apiKey primitive. PRIMARY KEY is namespace-scoped id (so multiple
@@ -368,14 +368,15 @@ function _rateLimitCountersDDL(dialect) {
   };
 }
 
-// _blamejs_ws_messages — cluster fan-out for the WebSocket channel
-// hub. publish() on any node writes a row; the other nodes poll for
-// new ids past their last seen and dispatch to local subscribers.
-// Auto-incrementing id is essential — postgres needs BIGSERIAL,
-// sqlite gets INTEGER PRIMARY KEY (which auto-increments implicitly).
-function _wsMessagesDDL(dialect) {
+// _blamejs_pubsub_messages — cluster fan-out for `b.pubsub` (the
+// generalization of the previous WebSocket-specific table). publish()
+// on any node writes a row; other nodes poll for new ids past their
+// last seen and dispatch to local subscribers. Auto-incrementing id
+// is essential — postgres needs BIGSERIAL, sqlite gets INTEGER
+// PRIMARY KEY (which auto-increments implicitly).
+function _pubsubMessagesDDL(dialect) {
   var t = _types(dialect);
-  var name = LOCAL_TO_EXTERNAL._blamejs_ws_messages;
+  var name = LOCAL_TO_EXTERNAL._blamejs_pubsub_messages;
   var idCol = dialect === "postgres"
     ? "id          BIGSERIAL PRIMARY KEY"
     : "id          INTEGER PRIMARY KEY AUTOINCREMENT";
@@ -383,7 +384,7 @@ function _wsMessagesDDL(dialect) {
     create:
       "CREATE TABLE IF NOT EXISTS " + name + " (" +
       "  " + idCol + "," +
-      "  channel     TEXT NOT NULL," +
+      "  topic       TEXT NOT NULL," +
       "  payload     TEXT NOT NULL," +
       "  publishedAt " + t.INT + " NOT NULL," +
       "  publishedBy TEXT NOT NULL" +
@@ -683,7 +684,7 @@ async function ensureSchema(opts) {
     _auditPurgeAnchorDDL(dialect),
     _schedulerTicksDDL(dialect),
     _rateLimitCountersDDL(dialect),
-    _wsMessagesDDL(dialect),
+    _pubsubMessagesDDL(dialect),
     _apiEncryptNoncesDDL(dialect),
     _apiKeysDDL(dialect),
     _sessionsDDL(dialect),

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 };