@blamejs/core 0.6.32 → 0.6.34

package/lib/log-stream-syslog.js

@@ -0,0 +1,297 @@
+"use strict";
+/**
+ * Syslog log-stream sink — RFC 5424 framing over UDP / TCP / TLS.
+ *
+ * Wire format (RFC 5424 §6):
+ *   <PRI>VERSION SP TIMESTAMP SP HOSTNAME SP APP-NAME SP PROCID SP MSGID SP STRUCTURED-DATA SP MSG
+ *
+ *   PRI    = (facility * 8) + severity
+ *   facility (default 16 = local0; 1 = user — operators commonly pick
+ *            local0..local7 for app-emitted records)
+ *   severity is mapped from the framework's level field:
+ *     debug → 7, info → 6, warn → 4, error → 3
+ *
+ * Transport:
+ *   udp                — single datagram per record (no framing)
+ *   tcp                — octet-counting framing (RFC 6587 §3.4.1):
+ *                        "<length> <message>" with a SPACE between
+ *                        length and the rfc5424 message bytes
+ *   tls                — same octet-counting framing on a TLS socket
+ *                        (RFC 5425). Standard port 6514.
+ *
+ * Defaults match RFC 3164/5424 conventions: appName = "blamejs",
+ * facility = local0 (16), hostname = os.hostname(), structuredData = "-".
+ *
+ * Flow control:
+ *   The TCP / TLS variants buffer pending writes during socket
+ *   reconnect and replay them on the new connection. UDP is best-effort
+ *   (datagrams that race a closed socket are dropped to onDrop).
+ */
+var dgram = require("dgram");
+var net   = require("net");
+var os    = require("os");
+var tls   = require("tls");
+var C = require("./constants");
+var { LogStreamError } = require("./framework-error");
+
+var _err = LogStreamError.factory;
+
+var DEFAULT_FACILITY    = 16;          // local0
+var DEFAULT_APP_NAME    = "blamejs";
+var DEFAULT_PROC_ID     = String(process.pid);
+var DEFAULT_MSG_ID      = "-";
+var DEFAULT_STRUCT_DATA = "-";
+var TCP_DEFAULT_PORT    = 514;
+var TLS_DEFAULT_PORT    = 6514;
+var UDP_DEFAULT_PORT    = 514;
+var DEFAULT_TIMEOUT_MS  = C.TIME.seconds(10);
+var DEFAULT_RECONNECT_BASE_MS = 250;
+var DEFAULT_RECONNECT_MAX_MS  = 30000;
+var DEFAULT_BUFFER_LIMIT = 10000;
+
+// RFC 5424 severity codes from the framework's level names.
+var LEVEL_TO_SEVERITY = {
+  debug: 7,
+  info:  6,
+  warn:  4,
+  error: 3,
+};
+
+function _toRfc3339(tsMs) {
+  return new Date(tsMs).toISOString();
+}
+
+function _formatRfc5424(record, cfg) {
+  var severity = LEVEL_TO_SEVERITY[record.level] != null
+    ? LEVEL_TO_SEVERITY[record.level] : 6;
+  var pri = (cfg.facility * 8) + severity;
+  var ts  = _toRfc3339(record.ts || Date.now());
+  // Body — JSON-encode meta + message together so the structured
+  // payload survives the wire as a single MSG token. Operators with
+  // their own RFC 5424 STRUCTURED-DATA producers pass cfg.structuredData
+  // (string) to override the default "-".
+  var body = record.message || "";
+  if (record.meta && Object.keys(record.meta).length > 0) {
+    try { body += " " + JSON.stringify(record.meta); }
+    catch (_e) { /* best-effort */ }
+  }
+  return "<" + pri + ">1 " + ts + " " + cfg.hostname + " " +
+         cfg.appName + " " + cfg.procId + " " + cfg.msgId + " " +
+         (cfg.structuredData || "-") + " " + body;
+}
+
+function create(config) {
+  if (!config) throw _err("BAD_OPT", "log-stream syslog requires { url } (e.g. udp://host:514, tcp://host:514, tls://host:6514)");
+  var url = config.url;
+  if (typeof url !== "string" || url.length === 0) {
+    throw _err("BAD_OPT", "log-stream syslog requires { url } (string)");
+  }
+  // Parse URL — accept udp://, tcp://, tls://. safeUrl rejects http://
+  // by default; allow these explicit transports.
+  var parsed;
+  try {
+    parsed = new URL(url);
+  } catch (e) {
+    throw _err("BAD_URL", "log-stream syslog: bad url '" + url + "': " +
+      ((e && e.message) || String(e)));
+  }
+  var transport = parsed.protocol.replace(/:$/, "").toLowerCase();
+  if (transport !== "udp" && transport !== "tcp" && transport !== "tls") {
+    throw _err("BAD_URL",
+      "log-stream syslog: protocol must be udp / tcp / tls, got " +
+      JSON.stringify(parsed.protocol));
+  }
+  var defaultPort = transport === "tls" ? TLS_DEFAULT_PORT
+                  : transport === "tcp" ? TCP_DEFAULT_PORT
+                  : UDP_DEFAULT_PORT;
+  var host = parsed.hostname;
+  var port = parsed.port ? parseInt(parsed.port, 10) : defaultPort;
+
+  var cfg = {
+    transport:        transport,
+    host:             host,
+    port:             port,
+    facility:         (typeof config.facility === "number" && config.facility >= 0 && config.facility <= 23)
+                        ? Math.floor(config.facility) : DEFAULT_FACILITY,
+    appName:          config.appName || DEFAULT_APP_NAME,
+    procId:           config.procId  || DEFAULT_PROC_ID,
+    msgId:            config.msgId   || DEFAULT_MSG_ID,
+    hostname:         config.hostname || os.hostname(),
+    structuredData:   config.structuredData || DEFAULT_STRUCT_DATA,
+    timeoutMs:        config.timeoutMs || DEFAULT_TIMEOUT_MS,
+    bufferLimit:      config.bufferLimit || DEFAULT_BUFFER_LIMIT,
+    reconnectBaseMs:  config.reconnectBaseMs || DEFAULT_RECONNECT_BASE_MS,
+    reconnectMaxMs:   config.reconnectMaxMs  || DEFAULT_RECONNECT_MAX_MS,
+    ca:               config.ca || null,
+    rejectUnauthorized: config.rejectUnauthorized !== false,
+    servername:       config.servername || null,
+  };
+  // safeUrl-style guard for the URL — reject userinfo (no auth in
+  // syslog wire) so a stray "syslog://user:pw@host" doesn't silently
+  // get through.
+  if (parsed.username || parsed.password) {
+    throw _err("BAD_URL",
+      "log-stream syslog: url must not contain userinfo");
+  }
+  // Track the operator's onDrop so dropped events surface.
+  var onDrop = typeof config.onDrop === "function" ? config.onDrop : null;
+  function _emitDrop(reason, batch, err) {
+    if (!onDrop) return;
+    try { onDrop({ reason: reason, batch: batch, error: err || null }); }
+    catch (_e) {}
+  }
+
+  // ---- UDP transport ----
+  if (transport === "udp") {
+    var udpFamily = host.indexOf(":") !== -1 ? "udp6" : "udp4";
+    var udpSock = dgram.createSocket(udpFamily);
+    udpSock.unref && udpSock.unref();
+    var udpClosed = false;
+    udpSock.on("error", function () { /* non-fatal — datagrams race */ });
+
+    return {
+      protocol: "syslog-udp",
+      emit: function (record) {
+        if (udpClosed) {
+          _emitDrop("sink-closed", [record], null);
+          return Promise.resolve({ accepted: false, reason: "closed" });
+        }
+        var msg = _formatRfc5424(record, cfg);
+        var buf = Buffer.from(msg, "utf8");
+        return new Promise(function (resolve) {
+          udpSock.send(buf, 0, buf.length, cfg.port, cfg.host, function (err) {
+            if (err) _emitDrop("udp-send-error", [record], err);
+            resolve({ accepted: !err, queued: 0 });
+          });
+        });
+      },
+      close: function () {
+        udpClosed = true;
+        try { udpSock.close(); } catch (_e) {}
+        return Promise.resolve();
+      },
+    };
+  }
+
+  // ---- TCP / TLS transport — octet-counting framing (RFC 6587) ----
+  // Buffer outgoing records during socket-down windows; replay on
+  // reconnect. Operator opts: bufferLimit caps the queue; oldest
+  // dropped first with the onDrop "overflow" reason.
+  var sock = null;
+  var sockReady = false;
+  var connecting = false;
+  var queue = [];
+  var closed = false;
+  var reconnectAttempt = 0;
+
+  function _writeFramed(record) {
+    var msg = _formatRfc5424(record, cfg);
+    var msgBuf = Buffer.from(msg, "utf8");
+    var prefix = Buffer.from(msgBuf.length + " ", "utf8");
+    sock.write(Buffer.concat([prefix, msgBuf]));
+  }
+
+  function _connect() {
+    if (closed || connecting) return;
+    connecting = true;
+    sockReady = false;
+    var connectOpts = { host: cfg.host, port: cfg.port };
+    var onConnect = function () {
+      connecting = false;
+      sockReady = true;
+      reconnectAttempt = 0;
+      // Drain queue in arrival order on (re)connect.
+      while (queue.length > 0 && sockReady) {
+        try { _writeFramed(queue.shift()); }
+        catch (e) { _emitDrop("write-error", [/* drained */], e); break; }
+      }
+    };
+    if (transport === "tls") {
+      var tlsOpts = Object.assign({}, connectOpts, {
+        rejectUnauthorized: cfg.rejectUnauthorized,
+        minVersion:         "TLSv1.3",
+      });
+      if (cfg.ca) tlsOpts.ca = cfg.ca;
+      if (cfg.servername) tlsOpts.servername = cfg.servername;
+      sock = tls.connect(tlsOpts, onConnect);
+    } else {
+      sock = net.connect(connectOpts, onConnect);
+    }
+    sock.unref && sock.unref();
+    sock.on("error", function () { /* defer to 'close' for reconnect */ });
+    sock.on("close", function () {
+      sockReady = false;
+      connecting = false;
+      try { sock.destroy(); } catch (_e) {}
+      sock = null;
+      if (closed) return;
+      reconnectAttempt += 1;
+      var delay = Math.min(cfg.reconnectMaxMs,
+        cfg.reconnectBaseMs * Math.pow(2, reconnectAttempt - 1));
+      var t = setTimeout(_connect, delay);
+      t.unref && t.unref();
+    });
+  }
+  _connect();
+
+  return {
+    protocol: "syslog-" + transport,
+    emit: function (record) {
+      if (closed) {
+        _emitDrop("sink-closed", [record], null);
+        return Promise.resolve({ accepted: false, reason: "closed" });
+      }
+      if (sockReady) {
+        try { _writeFramed(record); }
+        catch (e) {
+          _emitDrop("write-error", [record], e);
+          return Promise.resolve({ accepted: false, reason: "write-error" });
+        }
+        return Promise.resolve({ accepted: true, queued: 0 });
+      }
+      // Socket not yet up — buffer with overflow-by-oldest semantics.
+      if (queue.length >= cfg.bufferLimit) {
+        var dropped = queue.shift();
+        _emitDrop("overflow", [dropped], null);
+      }
+      queue.push(record);
+      return Promise.resolve({ accepted: true, queued: queue.length });
+    },
+    close: function () {
+      // Give an in-flight (re)connect a brief window to complete and
+      // drain the buffer. Without this, records emitted just before
+      // shutdown race the slower TLS handshake and surface as
+      // "sink-closed" drops even though the framework had a viable
+      // connection in progress.
+      var DRAIN_TIMEOUT_MS = 3000;
+      var started = Date.now();
+      return new Promise(function (resolve) {
+        function _finish() {
+          closed = true;
+          var pending = queue.splice(0, queue.length);
+          if (pending.length > 0) _emitDrop("sink-closed", pending, null);
+          try { if (sock) sock.end(); } catch (_e) {}
+          try { if (sock) sock.destroy(); } catch (_e) {}
+          sock = null;
+          resolve();
+        }
+        function _tick() {
+          if (queue.length === 0 || Date.now() - started > DRAIN_TIMEOUT_MS) {
+            return _finish();
+          }
+          // Keep the timer ref'd — close() is being awaited; if we
+          // unref the drain-tick timer the event loop can exit between
+          // ticks (UDP/TCP socket are also unref'd) and the close
+          // promise pends forever silently.
+          setTimeout(_tick, 25);
+        }
+        _tick();
+      });
+    },
+    // Test-only: returns the in-flight queue size for assertions.
+    _queueSizeForTest: function () { return queue.length; },
+    _formatRfc5424ForTest: function (rec) { return _formatRfc5424(rec, cfg); },
+  };
+}
+
+module.exports = { create: create };

package/lib/log-stream.js

@@ -15,15 +15,15 @@
  *              (k8s, cloud) get standard log forwarding without a
  *              vendor-specific adapter.
  *   cloudwatch — AWS CloudWatch Logs (PutLogEvents) over HTTPS with
- *              SigV4. Operator pre-creates the log group + log stream;
- *              the framework signs and POSTs batches respecting the
- *              10K-event / 1 MiB / 256 KiB-per-event AWS caps. Honors
- *              IAM role + STS session tokens.
- *
- * Adapters listed as deferred and surfacing a clear error when
- * selected:
- *
- *   syslog — RFC 5424 syslog over TLS
+ *              SigV4. Pass { autoCreate: true } to have the framework
+ *              issue CreateLogGroup + CreateLogStream on first emit
+ *              (idempotent — ResourceAlreadyExistsException treated as
+ *              success). Honors IAM role + STS session tokens. Respects
+ *              the 10K-event / 1 MiB / 256 KiB-per-event AWS caps.
+ *   syslog   — RFC 5424 with octet-counting framing over UDP / TCP /
+ *              TLS. UDP is best-effort; TCP/TLS buffer during socket
+ *              reconnect and replay on connect. Default ports 514
+ *              (UDP/TCP) and 6514 (TLS).
  *
  * Every emit goes through lib/redact.js BEFORE any sink sees it. PHI/PCI
  * never reaches operational logs even on a misconfigured field name —
@@ -50,6 +50,7 @@ var localProto      = require("./log-stream-local");
 var webhookProto    = require("./log-stream-webhook");
 var otlpProto       = require("./log-stream-otlp");
 var cloudwatchProto = require("./log-stream-cloudwatch");
+var syslogProto     = require("./log-stream-syslog");
 var redactor        = require("./redact");
 var lazyRequire     = require("./lazy-require");
 var protocolDispatcher = require("./protocol-dispatcher");
@@ -63,10 +64,9 @@ var dispatcher = protocolDispatcher.create({
     "webhook":    webhookProto,
     "otlp":       otlpProto,
     "cloudwatch": cloudwatchProto,
+    "syslog":     syslogProto,
   },
-  deferred:   {
-    "syslog":     { description: "RFC 5424 syslog over TLS" },
-  },
+  deferred:   {},
   fallbackProtocol: "local",
 });
 

package/lib/protocol-dispatcher.js

@@ -5,7 +5,7 @@
  *
  * Three framework modules ship a "pick a backend by protocol name" surface:
  *   - lib/queue.js                 (local, deferred: redis/sqs/amqp/nats)
- *   - lib/log-stream.js            (local + webhook, deferred: syslog/otlp/cloudwatch)
+ *   - lib/log-stream.js            (local + webhook + otlp + cloudwatch + syslog)
  *   - lib/object-store/index.js    (local + http-put + sigv4 + gcs + azure-blob)
  *
  * Each previously copied a ~30-line dispatch block: validate config has a

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