@blamejs/core 0.6.31 → 0.6.32

package/CHANGELOG.md

@@ -8,6 +8,7 @@ upgrading across more than a few patches at a time.
 
 ## v0.6.x
 
+- **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.
 - **0.6.30** (2026-05-02) — wiki-app integration gate + framework follow-ups surfaced by it. **`scripts/test-wiki-integration.js`** boots `examples/wiki` against the docker-compose fixture stack (real Redis / MinIO / Mailpit / CoreDNS / NTP / mtls-ca) and drives every backend through the wiki's HTTP surface AND the underlying framework primitives — validates that each primitive routes through the configured backend (cache → custom backend, queue → Redis Streams, mail → Mailpit SMTP, object-store → MinIO sigv4, log-stream → webhook receiver) AND that every fix shipped in v0.6.28 holds in a real-app context, not just in unit-test isolation. **Wiki gains test-only routes** under `/test/*` (gated by `WIKI_INTEGRATION_TEST=1`, mounted before CSRF/staticServe so test POSTs don't have to round-trip a token cookie) covering cache get/set/del, queue enqueue/size, mail send, object-store put/get, http-client fetch, log-stream emit, mtls-ca issue, ntp query, dns lookup, ssrf classify+check, plus `/test/diagnostic` that surfaces the active backend posture (network snapshot, queue backends, log sinks, mtls algorithm). **External-integration two-gate rule** — when a release diff touches a primitive that talks to an external service (`lib/redis-client.js`, `lib/queue-redis.js`, `lib/mail.js`, `lib/network-dns.js`, `lib/object-store/*`, `lib/log-stream*.js`, `lib/external-db.js`, `lib/cluster-*.js`, `lib/mtls-ca.js`, `lib/ssrf-guard.js`, `lib/http-client.js`, `lib/ntp-check.js`, `lib/cache.js`, `lib/webhook.js`), operators MUST run BOTH `scripts/test-integration.js` (per-primitive against real backends) AND `scripts/test-wiki-integration.js` (wiki app exercising the same backends end-to-end) before pushing. Documented in CONTRIBUTING.md's pre-push gate list and CLAUDE.md's release workflow as step 4a. The smoke + wiki-e2e gates above stay PURE (no docker dependency, runs in CI / on a developer laptop / inside prepack-guard); the two-gate is operator-run, opt-in, and surfaces bugs that mocks miss — fire-and-forget races, shutdown drains, TLS pinning, real DNS resolution, real protocol handshakes. **Framework fixes surfaced by the new gate**: `b.mtlsCa.create` now auto-creates `opts.dataDir` with `mode: 0o700` if it doesn't exist (matches `b.logStream`'s local sink, `b.backup`, `b.restoreBundle` — without it the first `initCA()` call hit `ENOENT` writing `ca.key.tmp`); `b.logStream` webhook-sink `close()` now waits for the in-flight `_flush()` before draining the buffer (the v0.6.28 drain fix only tracked emit-time wrapper promises, not the actual HTTP POST in flight; a record arriving mid-flush would buffer + the emit-time `_flush` early-returned on `if (inFlight) return`, and shutdown would then strand it). `b.queue.bootFromEnv()` is now wired in the wiki app's `build-app.js` unconditionally so the wiki picks up `BLAMEJS_QUEUE_PROTOCOL=redis` from env without code changes (was previously a documented-but-commented call site). **Test architecture rule (extends the v0.6.28 rule)** — live tests for the framework's primitives go under `test/integration/`; live tests for the wiki app exercising the framework end-to-end go under `examples/wiki/test/integration.js`. Smoke (`test/smoke.js`) and the existing wiki e2e (`examples/wiki/test/e2e.js`) stay pure. Smoke / wiki-e2e green; per-primitive integration suite green; wiki integration green. Eslint pin alignment + shellcheck added to the documented gate list (carry-over from v0.6.29).
 - **0.6.29** (2026-05-02) — CI cleanup. **shellcheck gate green**: `docker/init/generate-certs.sh`'s footer line counted output via `ls "$CERT_DIR" | wc -l` (SC2012 — fragile on filenames with newlines or quoting metacharacters); replaced with `find "$CERT_DIR" -maxdepth 1 -mindepth 1 | wc -l`. Same semantics, robust to any cert filename pki-init might end up writing. **shellcheck added to the documented pre-push gate list** in CONTRIBUTING.md alongside smoke / wiki e2e / eslint / api-snapshot / primitive-section validators — CI's `Lint summary` job has always run it, but the local-dev recipe didn't, so contributors hit it post-push instead of catching it locally. **eslint pin alignment**: `.github/PULL_REQUEST_TEMPLATE.md` and CONTRIBUTING.md still pinned `eslint@10` even though v0.6.16 swapped CI runners to `eslint@latest`; both bumped to `@latest` to match the forward-track posture of every other CI tool. No framework code changes; the script + doc updates never ship in the npm package (excluded by `files` array).

package/lib/cache-redis.js

@@ -0,0 +1,261 @@
+"use strict";
+/**
+ * Redis-backed cache backend for b.cache.
+ *
+ * Storage layout (operator-overridable namespace; default = "blamejs:cache"):
+ *   <namespace>:e:<key>            STRING — JSON-encoded value
+ *                                          PEXPIREAT honours the cache's TTL
+ *   <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)
+ *
+ * Same backend contract as the framework's other cache backends (memory,
+ * cluster, custom): get / set / del / has / clear / size / close, plus
+ * the optional invalidateTag + getTags + bytes + _startSweep hooks the
+ * `_customBackend` wrapper looks for.
+ *
+ * TTL is enforced by Redis itself (PEXPIREAT) — the framework does NOT
+ * run a sweep timer for this backend; expired entries vanish from the
+ * key space without app-side intervention.
+ *
+ * Sliding TTL: bumps the entry's expiry to `now + defaultTtlMs` on every
+ * read when the cache was created with `slidingTtl: true` and the cache
+ * has a finite defaultTtlMs. Same shape as the cluster backend.
+ *
+ * Concurrency: Redis is single-threaded for command execution; our get
+ * + set + tag updates are sequential, not pipelined inside a MULTI, so
+ * a worst-case interleaving might leave a tag set with a key that no
+ * longer exists. The reverse `keyTags` set + `del()` cleanup means the
+ * stale entry is reaped on the next `invalidateTag` (the SET membership
+ * is filtered against actual key existence — see invalidateTag below).
+ */
+
+var redisClient = require("./redis-client");
+var { CacheError } = require("./framework-error");
+
+var _err = CacheError.factory;
+
+function _toStr(v) {
+  if (v === null || v === undefined) return null;
+  return Buffer.isBuffer(v) ? v.toString("utf8") : String(v);
+}
+
+function create(cfg) {
+  cfg = cfg || {};
+  if (typeof cfg.url !== "string" || cfg.url.length === 0) {
+    throw _err("BAD_OPT", "cache-redis: opts.url is required (e.g. redis://localhost:6379/0)");
+  }
+  var namespace      = cfg.namespace;
+  var clock          = cfg.clock || function () { return Date.now(); };
+  var emitObs        = cfg.emitObs || function () {};
+  var slidingTtl     = cfg.slidingTtl;
+  var defaultTtlMs   = cfg.defaultTtlMs;
+
+  var client = redisClient.create({
+    url:                   cfg.url,
+    password:              cfg.password,
+    username:              cfg.username,
+    tls:                   cfg.tls,
+    ca:                    cfg.ca,
+    servername:            cfg.servername,
+    connectTimeoutMs:      cfg.connectTimeoutMs,
+    commandTimeoutMs:      cfg.commandTimeoutMs,
+    maxReconnectAttempts:  cfg.maxReconnectAttempts,
+  });
+
+  // Lazy connect — defer until first op so cache.create stays sync-safe.
+  var connectPromise = null;
+  function _ensureConnected() {
+    if (client.isOpen()) return Promise.resolve();
+    if (!connectPromise) connectPromise = client.connect();
+    return connectPromise;
+  }
+
+  function _key(k)         { return namespace + ":e:" + k; }
+  function _tagKey(t)      { return namespace + ":t:" + t; }
+  function _keyTagsKey(k)  { return namespace + ":k:" + k + ":tags"; }
+
+  async function get(key) {
+    await _ensureConnected();
+    var v = await client.command("GET", _key(key));
+    var s = _toStr(v);
+    if (s === null) return undefined;
+    var parsed;
+    try { parsed = JSON.parse(s); }
+    catch (_e) { return undefined; }
+    // Sliding TTL: extend the entry's life on every read. Best-effort
+    // (PEXPIREAT may race with delete; if it fails the operator just
+    // sees the original TTL play out).
+    if (slidingTtl && typeof defaultTtlMs === "number" && isFinite(defaultTtlMs) && defaultTtlMs > 0) {
+      var newExp = clock() + defaultTtlMs;
+      client.command("PEXPIREAT", _key(key), String(Math.floor(newExp)))
+        .catch(function () { /* best-effort */ });
+      client.command("PEXPIREAT", _keyTagsKey(key), String(Math.floor(newExp)))
+        .catch(function () { /* best-effort */ });
+    }
+    return parsed;
+  }
+
+  async function set(key, value, expiresAt, meta) {
+    await _ensureConnected();
+    var json = JSON.stringify(value);
+
+    // Drop any prior tag membership for this key (tags may have changed
+    // across sets). The reverse-tag set tells us which tag SETs need
+    // pruning without scanning every tag in the namespace.
+    var oldTagsRv = await client.command("SMEMBERS", _keyTagsKey(key));
+    var oldTags = (oldTagsRv || []).map(_toStr).filter(Boolean);
+    for (var ot = 0; ot < oldTags.length; ot++) {
+      try { await client.command("SREM", _tagKey(oldTags[ot]), key); }
+      catch (_e) { /* best-effort */ }
+    }
+    if (oldTags.length > 0) {
+      try { await client.command("DEL", _keyTagsKey(key)); }
+      catch (_e) { /* best-effort */ }
+    }
+
+    // Write the value with PEXPIREAT for finite TTLs; un-expiring SET
+    // for Infinity (operator opted for "cache forever until evicted").
+    if (typeof expiresAt === "number" && isFinite(expiresAt)) {
+      await client.command("SET", _key(key), json, "PXAT", String(Math.floor(expiresAt)));
+    } else {
+      await client.command("SET", _key(key), json);
+    }
+
+    // Wire the new tags. SADD is idempotent on duplicate tag names.
+    var tags = meta && Array.isArray(meta.tags) ? meta.tags : null;
+    if (tags && tags.length > 0) {
+      for (var t = 0; t < tags.length; t++) {
+        await client.command("SADD", _tagKey(tags[t]), key);
+        await client.command("SADD", _keyTagsKey(key), tags[t]);
+      }
+      // Match the entry's lifetime on the keyTags reverse-set so
+      // membership doesn't outlive the value.
+      if (typeof expiresAt === "number" && isFinite(expiresAt)) {
+        try { await client.command("PEXPIREAT", _keyTagsKey(key), String(Math.floor(expiresAt))); }
+        catch (_e) { /* best-effort */ }
+      }
+    }
+    emitObs("cache.redis.set", { namespace: namespace });
+  }
+
+  async function del(key) {
+    await _ensureConnected();
+    var oldTagsRv = await client.command("SMEMBERS", _keyTagsKey(key));
+    var oldTags = (oldTagsRv || []).map(_toStr).filter(Boolean);
+    for (var i = 0; i < oldTags.length; i++) {
+      try { await client.command("SREM", _tagKey(oldTags[i]), key); }
+      catch (_e) { /* best-effort */ }
+    }
+    var dels = await Promise.all([
+      client.command("DEL", _key(key)),
+      client.command("DEL", _keyTagsKey(key)),
+    ]);
+    return Number(dels[0]) === 1;
+  }
+
+  async function has(key) {
+    await _ensureConnected();
+    var rv = await client.command("EXISTS", _key(key));
+    return Number(rv) === 1;
+  }
+
+  async function clear() {
+    await _ensureConnected();
+    // SCAN-and-DEL every key under this namespace. Using SCAN avoids
+    // KEYS' O(N) blocking pass and lets a busy Redis serve other
+    // commands between cursor batches.
+    var cursor = "0";
+    do {
+      var rv = await client.command("SCAN", cursor, "MATCH", namespace + ":*", "COUNT", "200");
+      cursor = _toStr(rv[0]) || "0";
+      var keys = (rv[1] || []).map(_toStr).filter(Boolean);
+      if (keys.length > 0) {
+        await client.command.apply(client, ["DEL"].concat(keys));
+      }
+    } while (cursor !== "0");
+  }
+
+  async function size() {
+    await _ensureConnected();
+    var cursor = "0";
+    var n = 0;
+    do {
+      var rv = await client.command("SCAN", cursor, "MATCH", namespace + ":e:*", "COUNT", "200");
+      cursor = _toStr(rv[0]) || "0";
+      n += (rv[1] || []).length;
+    } while (cursor !== "0");
+    return n;
+  }
+
+  function bytes() {
+    // Per-entry byte accounting on Redis would mean a MEMORY USAGE call
+    // per key, which is operator-expensive and Redis-version-dependent.
+    // Operators wanting this use the memory backend or run their own
+    // monitoring against MEMORY STATS at the cluster level.
+    return Promise.resolve(0);
+  }
+
+  async function invalidateTag(tag) {
+    await _ensureConnected();
+    var rv = await client.command("SMEMBERS", _tagKey(tag));
+    var keys = (rv || []).map(_toStr).filter(Boolean);
+    var dropped = 0;
+    for (var i = 0; i < keys.length; i++) {
+      // Filter out stale tag-membership entries (key already expired
+      // from PEXPIREAT but lingered in the tag SET) by checking
+      // EXISTS before del. Saves an unnecessary DEL round-trip on
+      // ghost keys.
+      var existsRv = await client.command("EXISTS", _key(keys[i]));
+      if (Number(existsRv) === 1) {
+        await del(keys[i]);
+        dropped += 1;
+      } else {
+        // Ghost — just SREM from this tag set + drop the reverse.
+        try { await client.command("SREM", _tagKey(tag), keys[i]); }
+        catch (_e) {}
+      }
+    }
+    // Drop the tag set itself if it's now empty (or empty after the
+    // ghost cleanup above).
+    var remaining = await client.command("SCARD", _tagKey(tag));
+    if (Number(remaining) === 0) {
+      try { await client.command("DEL", _tagKey(tag)); }
+      catch (_e) {}
+    }
+    emitObs("cache.redis.invalidateTag", { namespace: namespace, tag: tag, dropped: dropped });
+    return dropped;
+  }
+
+  async function getTags(key) {
+    await _ensureConnected();
+    var rv = await client.command("SMEMBERS", _keyTagsKey(key));
+    return (rv || []).map(_toStr).filter(Boolean);
+  }
+
+  async function close() {
+    try { await client.close(); }
+    catch (_e) { /* best-effort */ }
+  }
+
+  return {
+    name:           "redis",
+    get:            get,
+    set:            set,
+    del:            del,
+    has:            has,
+    clear:          clear,
+    size:           size,
+    bytes:          bytes,
+    invalidateTag:  invalidateTag,
+    getTags:        getTags,
+    close:          close,
+    // Redis enforces TTL itself; the framework's sweeper is a no-op here.
+    _startSweep:    function () {},
+  };
+}
+
+module.exports = { create: create };

package/lib/cache.js

@@ -184,10 +184,15 @@ function _validateCreateOpts(opts) {
   }
   if (opts.backend !== undefined) {
     if (typeof opts.backend === "string") {
-      if (opts.backend !== "memory" && opts.backend !== "cluster") {
-        throw _err("BAD_OPT", "cache.create: backend string must be 'memory' or 'cluster', got " +
+      if (opts.backend !== "memory" && opts.backend !== "cluster" && opts.backend !== "redis") {
+        throw _err("BAD_OPT", "cache.create: backend string must be 'memory' | 'cluster' | 'redis', got " +
           JSON.stringify(opts.backend));
       }
+      if (opts.backend === "redis") {
+        if (typeof opts.redisUrl !== "string" || opts.redisUrl.length === 0) {
+          throw _err("BAD_OPT", "cache.create: backend='redis' requires opts.redisUrl (e.g. redis://localhost:6379/0)");
+        }
+      }
     } else {
       _validateBackendObject(opts.backend);
     }
@@ -729,6 +734,11 @@ function create(opts) {
     "sweepIntervalMs", "staleWhileRevalidate", "slidingTtl",
     "auditFailures", "auditClear",
     "audit", "observability", "clock",
+    // backend === "redis" connection options. Ignored for memory /
+    // cluster / custom-backend modes.
+    "redisUrl", "redisPassword", "redisUsername", "redisTls", "redisCa",
+    "redisServername", "redisConnectTimeoutMs", "redisCommandTimeoutMs",
+    "redisMaxReconnectAttempts",
   ], "cache");
   _validateCreateOpts(opts);
 
@@ -792,6 +802,24 @@ function create(opts) {
     backend = _memoryBackend(cfg);
   } else if (backendKind === "cluster") {
     backend = _clusterBackend(cfg);
+  } else if (backendKind === "redis") {
+    var cacheRedis = require("./cache-redis");
+    backend = _customBackend(cacheRedis.create({
+      namespace:             namespace,
+      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,
+      slidingTtl:            slidingTtl,
+      defaultTtlMs:          defaultTtlMs,
+      clock:                 clock,
+      emitObs:               emitObs,
+    }), cfg);
   } else {
     backend = _customBackend(opts.backend, cfg);
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blamejs/core",
-  "version": "0.6.31",
+  "version": "0.6.32",
   "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:1f3b5321-8232-4a90-a6f9-c43160b7018d",
+  "serialNumber": "urn:uuid:bf737d55-37d5-49a4-95fb-c1149d627468",
   "version": 1,
   "metadata": {
-    "timestamp": "2026-05-02T19:03:09.695Z",
+    "timestamp": "2026-05-02T19:10:22.247Z",
     "lifecycles": [
       {
         "phase": "build"
@@ -19,14 +19,14 @@
       }
     ],
     "component": {
-      "bom-ref": "@blamejs/core@0.6.31",
+      "bom-ref": "@blamejs/core@0.6.32",
       "type": "library",
       "name": "blamejs",
-      "version": "0.6.31",
+      "version": "0.6.32",
       "scope": "required",
       "author": "blamejs contributors",
       "description": "The Node framework that owns its stack.",
-      "purl": "pkg:npm/%40blamejs/core@0.6.31",
+      "purl": "pkg:npm/%40blamejs/core@0.6.32",
       "properties": [],
       "externalReferences": [
         {
@@ -54,7 +54,7 @@
   "components": [],
   "dependencies": [
     {
-      "ref": "@blamejs/core@0.6.31",
+      "ref": "@blamejs/core@0.6.32",
       "dependsOn": []
     }
   ]