@blamejs/core 0.6.29 → 0.6.32

package/CHANGELOG.md

@@ -8,6 +8,9 @@ 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).
 - **0.6.28** (2026-05-02) — bug-finding pass: live integration test suite + every framework bug it caught. **`b.ssrfGuard.checkUrl` cloud-metadata hard-deny** — `allowInternal: true` no longer permits 169.254.169.254 (AWS / GCP / Azure metadata). Loopback / private / link-local / reserved stay allowInternal-overridable per existing semantics; cloud-metadata is unconditional because a blanket override would let any compromised request exfiltrate instance credentials. **`b.mtlsCa` issues server certs and dual-EKU certs** — `generateClientCert({ usage: "client" | "server" | "both", sans: [...] })`. `usage` controls EKU (`client` = clientAuth, `server` = serverAuth, `both` = both); `sans` accepts `DNS:` / `IP:` / bare-DNS entries; serverAuth without an explicit SAN auto-adds the CN. Operators wiring inbound mTLS reverse-proxy fronts no longer hit "unsuitable certificate purpose" on the handshake. **`b.mtlsCa` algorithm auto-detect** — the engine probes webcrypto + the vendored x509 library at first cert issuance and picks the highest-PQC option that round-trips: SLH-DSA-SHAKE-256f → SLH-DSA-SHAKE-128f → ML-DSA-87 → ML-DSA-65 → ECDSA-P384-SHA384 (current bridge — what the X.509 ecosystem accepts today). When the bridge condition lifts and the vendor refresh ships, the same `b.mtlsCa.create(...)` call self-upgrades; `b.mtlsCa.status().cert.label` and `.posture` surface the chosen algorithm. **`b.redisClient.create({ ca, servername })`** — managed-Redis / on-prem-cluster operators connecting over `rediss://` against a private CA can pin trust roots; `servername` auto-suppresses for IP literals so `rediss://127.0.0.1:6380` no longer trips node:tls's IP-as-SNI rule. **`b.network.dns.useDnsOverTls` / `useDnsOverHttps` accept `ca`** — same trust-pinning surface for self-signed / private-PKI DoT and DoH endpoints. **DoT TLS handshake errors** now route as DnsError on the lookup promise rather than leaking as `unhandledRejection` — the secureConnect / error event-listener race had let cert-verification failures escape the per-query Promise wrapping. **DoT socket lifecycle** — was unconditionally `sock.unref()`'d after construct, causing node to exit during in-flight lookups when no other I/O kept the loop alive; now ref'd while a query is in flight and unref'd when idle. **`b.ntpCheck.querySingle` honours IPv6 servers** — was hardcoded to `dgram.createSocket("udp4")`, so `::1` / `fd00::…` queries failed with EINVAL; now auto-detects family from the server string. **`b.logStream.shutdown` drains in-flight emit microtasks** before closing sink fds — fire-and-forget emits queued just before shutdown were silently dropped because `close()` ran ahead of the microtask. **`b.logStream` webhook-sink `close()` flushes BEFORE setting `closed = true`** — `_flush`'s while loop bailed on `!closed`, leaving any records buffered just before shutdown stranded. **Integration test suite** (`test/integration/`, runner at `scripts/test-integration.js`) — 13 live test files across `b.redisClient` plain + TLS, `b.queue` Redis backend lifecycle, `b.mail` SMTP + STARTTLS + multi-rcpt + dot-stuffing transparency, `b.mail.dkim` rsa-sha256 + ed25519-sha256 + bad-algorithm reject, `b.ntpCheck` v4 + v6 + bootCheck + bad-host + bad-port, `b.network.dns` plain + DoT + DoH with strict CA pinning + bad-servername + cache, `b.network.heartbeat` http + tcp + state-change callbacks, `b.objectStore` sigv4 PUT / GET / list / delete on plain HTTP + TLS variants, `b.cache` memory + Redis-backed cluster, `b.httpClient` direct + Squid forward proxy + TLS pin, `b.ssrfGuard` classify + checkUrl + cloud-metadata block, `b.logStream` local + webhook + deferred-syslog error path, `b.mtlsCa` CA bootstrap + clientAuth + serverAuth + dual-EKU live mTLS handshakes. Companion `docker-compose.test.yml` stands up redis (plain + TLS) / postgres / mysql / mongo / minio (HTTP + HTTPS variants) / rabbitmq (plain + TLS) / nats / syslog / ntp / mailpit / coredns (plain + DoT + DoH) / haproxy / caddy / mitmproxy / squid / pki-init (auto-generates Ed25519 CA + per-service leaf certs into a docker volume); host port bindings dual-stack on `127.0.0.1` AND `[::1]`. `scripts/check-services.js` does host-side TCP / TLS handshake / SNTPv4 / DNS-A / Redis-PING / SMTP-banner / HTTP probes across every endpoint; `scripts/test-integration.js` exports the test CA via `docker cp` and sets `NODE_EXTRA_CA_CERTS` per-test child process so the framework's TLS verification stays strict (no `rejectUnauthorized: false` bypass anywhere in the test surface). **Test architecture rule** — live tests go in `test/integration/`, NEVER in `test/layer-N-*/`: smoke must remain pure (no docker dependency, runs in CI / on a developer laptop / inside prepack-guard) and a "skip silently when service is down" branch in a layer-N test makes the gate's pass count misleading and masks bugs that only surface against a live backend. The `0.6.27` `queue-redis.test.js` was moved to `test/integration/queue-redis.test.js` to enforce this. Smoke and wiki e2e green; integration suite ships green against the docker-compose stack.
 - **0.6.27** (2026-05-02) — Redis backend for `b.queue` so multi-replica apps can share a single queue without each needing to be cluster leader. **Bespoke RESP2 client** (`lib/redis-client.js`) — zero npm runtime deps. TCP via `node:net` + TLS via `node:tls` (`rediss://` auto-detected), legacy single-arg AUTH + ACL `AUTH user pass`, `SELECT db`, pipelining, exponential-backoff reconnect, EVAL helper. **`b.queue` protocol "redis"** (`lib/queue-redis.js`) — full enqueue/lease/extendLease/complete/fail/sweepExpired/size/purge/dlqList/dlqRetry/dlqSize parity with the local backend. Atomicity comes from server-side Lua scripts so concurrent consumers can't double-lease and a sweep can't race a complete. Storage layout: per-job HASH (sealed payload + lastError via `cryptoField.sealRow("_blamejs_jobs", row)` — same crypto config as the local backend), per-queue ready ZSET scored by availableAt, per-queue inflight ZSET scored by leaseExpiresAt, per-queue dlq ZSET scored by finishedAt, plus a queues SET so sweepExpired walks every known queue without a global secondary index. Cron-repeat handled in `complete()` JS — re-enqueues the next firing as a fresh jobId with availableAt=next-cron-fire. **`b.queue.bootFromEnv({ env })`** — env-driven init mirroring `b.network.bootFromEnv` and `b.logStream.bootFromEnv`. Reads `BLAMEJS_QUEUE_PROTOCOL` (`local`|`redis`), `BLAMEJS_QUEUE_REDIS_URL`, `BLAMEJS_QUEUE_REDIS_PASSWORD`, `BLAMEJS_QUEUE_REDIS_USERNAME`, `BLAMEJS_QUEUE_REDIS_TLS`, `BLAMEJS_QUEUE_REDIS_KEY_PREFIX`. Operators flip from local to Redis without a code change; both wiki docker-compose configs declare the new env knobs. Removed `redis` from `DEFERRED_PROTOCOLS`. **Out of scope for v1** (deferred to follow-up patches with explicit re-open conditions): Redis Cluster (slot-routing), Sentinel (managed primary failover), priority ordering on the Redis backend (queue-local supports `priority` opt; Redis backend orders strictly by availableAt for v1), flow children with `dependsOn` cascade. **Wiki**: queue-cache page documents the Redis backend opts schema, bootFromEnv, and the layout. **Tests**: 24 RESP2 protocol parser unit tests (`test/layer-0-primitives/redis-client.test.js`) cover URL parsing, command encoding (binary-safe), every reply type (simple string / error / integer / bulk / nil bulk / nested array / pipelined / incomplete-mid-frame). Live Redis round-trip tests (`test/layer-0-primitives/queue-redis.test.js`) cover enqueue+lease, availableAt scheduling, visibility-timeout sweep, fail+retry path, DLQ list/retry/size, extendLease, purge, and concurrent-leaser no-double-lease — skip cleanly when `BLAMEJS_TEST_REDIS_URL` is not set so the smoke suite passes on dev boxes without a Redis container. Smoke 6780 OK.

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/lib/log-stream-webhook.js

@@ -122,32 +122,42 @@ function create(config) {
     flushTimer.unref();
   }
 
+  // Track the in-flight flush as a promise so close() can await it.
+  // Without this, a record arriving mid-flush gets buffered, the
+  // emit-time _flush() early-returns on `if (inFlight) return`, and
+  // the buffered record is stranded if shutdown fires before
+  // _scheduleFlush() drains it.
+  var inFlightPromise = null;
   async function _flush() {
-    if (inFlight) return;
+    if (inFlight) return inFlightPromise;
     if (buffer.length === 0) return;
     inFlight = true;
-    try {
-      while (buffer.length > 0 && !closed) {
-        var batch = buffer.splice(0, cfg.batchSize);
-        var body = _serializeBatch(batch, cfg.bodyShape);
-        try {
-          await retryHelper.withRetry(function () {
-            return _post(cfg.url, body, headers, cfg.timeoutMs, cfg.allowedProtocols, cfg.allowInternal);
-          }, cfg.retry);
-        } catch (e) {
-          // Batch permanently rejected — surface via dropCount AND the
-          // operator-supplied onDrop callback. The dispatcher path
-          // wraps its own audit hook around emit(); operators using
-          // this sink directly rely on dropCount + onDrop.
-          dropCount += batch.length;
-          _emitDrop("retry-exhausted", batch, e);
-          break;
+    inFlightPromise = (async function () {
+      try {
+        while (buffer.length > 0 && !closed) {
+          var batch = buffer.splice(0, cfg.batchSize);
+          var body = _serializeBatch(batch, cfg.bodyShape);
+          try {
+            await retryHelper.withRetry(function () {
+              return _post(cfg.url, body, headers, cfg.timeoutMs, cfg.allowedProtocols, cfg.allowInternal);
+            }, cfg.retry);
+          } catch (e) {
+            // Batch permanently rejected — surface via dropCount AND the
+            // operator-supplied onDrop callback. The dispatcher path
+            // wraps its own audit hook around emit(); operators using
+            // this sink directly rely on dropCount + onDrop.
+            dropCount += batch.length;
+            _emitDrop("retry-exhausted", batch, e);
+            break;
+          }
         }
+      } finally {
+        inFlight = false;
+        inFlightPromise = null;
+        if (buffer.length > 0) _scheduleFlush();
       }
-    } finally {
-      inFlight = false;
-      if (buffer.length > 0) _scheduleFlush();
-    }
+    })();
+    return inFlightPromise;
   }
 
   function emit(record) {
@@ -171,9 +181,13 @@ function create(config) {
     // Drain BEFORE flipping closed=true. _flush()'s while loop bails on
     // !closed, so flipping the flag first leaves any buffered records
     // stranded — the very records the operator queued just before
-    // calling shutdown(). Order: stop the timer, drain, then refuse
-    // any new enqueues by setting closed.
+    // calling shutdown(). Order: stop the timer, await any in-flight
+    // flush so its records POST before we touch the buffer, drain
+    // anything still queued, THEN refuse new enqueues.
     if (flushTimer) { clearTimeout(flushTimer); flushTimer = null; }
+    if (inFlightPromise) {
+      try { await inFlightPromise; } catch (_e) { /* surfaced via onDrop */ }
+    }
     await _flush();
     closed = true;
   }

package/lib/mtls-ca.js

@@ -129,6 +129,15 @@ function create(opts) {
     throw new MtlsCaError("mtls-ca/no-datadir",
       "mtlsCa.create requires opts.dataDir");
   }
+  // Auto-create the dataDir with restrictive perms (CA keys live here).
+  // Matches the behaviour of other framework primitives that own a
+  // dataDir — log-stream-local, backup, restore-bundle. Without this
+  // the first initCA() / generateClientCert() call fails with ENOENT
+  // on `ca.key.tmp` because the atomic-file write expects the parent
+  // dir to exist.
+  if (!fs.existsSync(opts.dataDir)) {
+    fs.mkdirSync(opts.dataDir, { recursive: true, mode: 0o700 });
+  }
   var paths = _resolvePaths(opts.dataDir, opts.paths);
   var vault = opts.vault || null;
   var caKeySealedMode = (opts.caKeySealedMode || "auto").toLowerCase();

package/lib/queue-redis.js

@@ -29,12 +29,6 @@
  * Out of scope (defer to follow-up patches):
  *   - Redis Cluster (slot-routing across multi-node Redis)
  *   - Sentinel (managed primary failover)
- *   - Job priority (queue-local supports `priority` opt; Redis backend
- *     orders strictly by availableAt for v1 — re-introduce when a real
- *     operator demand surfaces with a clean Lua-side ordering scheme)
- *   - Flow children with dependsOn (queue-local's _maybeReleaseFlowChildren
- *     coordination — orthogonal to backend choice; ships when flow primitive
- *     itself becomes backend-agnostic)
  */
 var C = require("./constants");
 var cryptoField = require("./crypto-field");
@@ -57,9 +51,23 @@ var DEFAULT_PREFIX = "blamejs:queue";
 // ---- Lua scripts ----
 //
 // LEASE_LUA — atomically pull up to maxRows jobs from the ready zset
-// whose score (availableAt) is <= nowMs, move them to the inflight
-// zset with score = leaseExpiresAt, increment attempts, flip status,
-// and return the jobIds. The JS side then HGETALLs each id.
+// whose availableAt is <= nowMs, move them to the inflight zset with
+// score = leaseExpiresAt, increment attempts, flip status, and return
+// the jobIds in priority order. The JS side then HGETALLs each id.
+//
+// Priority semantics — matches queue-local's `ORDER BY priority DESC,
+// availableAt ASC, enqueuedAt ASC` over the same `WHERE availableAt
+// <= nowMs` filter. The Redis ZSET orders by availableAt only (the
+// score), which is enough to filter "ready vs not-yet-ready" via
+// ZRANGEBYSCORE 0..nowMs but NOT enough to surface a high-priority
+// job ahead of an earlier-availableAt low-priority job. So we
+// over-fetch maxRows*5 candidates by score, HMGET the priority +
+// availableAt for each, sort priority-DESC / availableAt-ASC server-
+// side in Lua, and lease the top maxRows. The over-fetch factor is
+// chosen so a queue with a typical priority distribution surfaces
+// the right jobs without scanning the entire ready set; queues with
+// >5x as many priority-0 jobs as priority-N jobs would still pull
+// the top-priority ones first.
 //
 // KEYS[1] = ready zset
 // KEYS[2] = inflight zset
@@ -74,10 +82,29 @@ var LEASE_LUA = [
   'local leaseExpiresAt = tonumber(ARGV[2])',
   'local maxRows = tonumber(ARGV[3])',
   'local jobKeyPrefix = ARGV[4]',
-  'local jobIds = redis.call("ZRANGEBYSCORE", readyKey, 0, nowMs, "LIMIT", 0, maxRows)',
+  'local oversample = maxRows * 5',
+  'local jobIds = redis.call("ZRANGEBYSCORE", readyKey, 0, nowMs, "LIMIT", 0, oversample)',
   'if #jobIds == 0 then return {} end',
+  // Pull priority + availableAt + enqueuedAt for each candidate so the
+  // sort uses the same triple queue-local sorts on. enqueuedAt is the
+  // tiebreaker among same-priority same-availableAt jobs (FIFO within
+  // a priority lane).
+  'local rows = {}',
   'for i = 1, #jobIds do',
   '  local jobId = jobIds[i]',
+  '  local h = redis.call("HMGET", jobKeyPrefix..jobId, "priority", "availableAt", "enqueuedAt")',
+  '  rows[i] = { jobId, tonumber(h[1] or "0") or 0, tonumber(h[2] or "0") or 0, tonumber(h[3] or "0") or 0 }',
+  'end',
+  // priority DESC, availableAt ASC, enqueuedAt ASC.
+  'table.sort(rows, function(a, b)',
+  '  if a[2] ~= b[2] then return a[2] > b[2] end',
+  '  if a[3] ~= b[3] then return a[3] < b[3] end',
+  '  return a[4] < b[4]',
+  'end)',
+  'local picked = {}',
+  'local n = math.min(maxRows, #rows)',
+  'for i = 1, n do',
+  '  local jobId = rows[i][1]',
   '  redis.call("ZREM", readyKey, jobId)',
   '  redis.call("ZADD", inflightKey, leaseExpiresAt, jobId)',
   '  redis.call("HINCRBY", jobKeyPrefix..jobId, "attempts", 1)',
@@ -85,8 +112,9 @@ var LEASE_LUA = [
   '             "status", "inflight",',
   '             "leasedAt", nowMs,',
   '             "leaseExpiresAt", leaseExpiresAt)',
+  '  picked[i] = jobId',
   'end',
-  'return jobIds',
+  'return picked',
 ].join("\n");
 
 // SWEEP_LUA — find jobs in inflight whose lease expired, push back to
@@ -251,6 +279,7 @@ function create(opts) {
   function _dlqKey(queueName)     { return prefix + ":q:" + queueName + ":dlq"; }
   function _queuesKey()           { return prefix + ":queues"; }
   function _jobKeyPrefix()        { return prefix + ":job:"; }
+  function _flowKey(flowId)       { return prefix + ":flow:" + flowId; }
 
   // ---- Row encoding ----
   //
@@ -348,13 +377,22 @@ function create(opts) {
     };
     var sealed = cryptoField.sealRow("_blamejs_jobs", row);
 
-    // Pipeline: HSET job + ZADD ready + SADD queues. Pipelined writes
-    // hit Redis without round-trips between them.
+    // Pipeline: HSET job + ZADD ready + SADD queues + (if flowId)
+    // SADD flow set. Pipelined writes hit Redis without round-trips
+    // between them. The flow set is the per-flow registry that
+    // complete() walks to release dependents — it lets us avoid a
+    // SCAN over every job hash when releasing children, matching the
+    // queue-local pattern of "SELECT siblings WHERE flowId = ?".
     var hsetArgs = _hsetArgs(jobId, sealed);
-    var p1 = client.command.apply(null, hsetArgs);
-    var p2 = client.command("ZADD", _readyKey(queueName), String(availableAt), jobId);
-    var p3 = client.command("SADD", _queuesKey(), queueName);
-    await Promise.all([p1, p2, p3]);
+    var pipeline = [
+      client.command.apply(null, hsetArgs),
+      client.command("ZADD", _readyKey(queueName), String(availableAt), jobId),
+      client.command("SADD", _queuesKey(), queueName),
+    ];
+    if (row.flowId) {
+      pipeline.push(client.command("SADD", _flowKey(row.flowId), jobId));
+    }
+    await Promise.all(pipeline);
 
     return {
       jobId:          jobId,
@@ -450,9 +488,104 @@ function create(opts) {
           });
       } catch (_e) { /* best-effort — cron resumes next tick if op fixes the issue */ }
     }
+
+    // Flow propagation: walk siblings whose dependsOn includes this
+    // jobId (or this job's flowChildName) and bump availableAt to now
+    // if ALL their deps are now complete. Mirrors queue-local's
+    // _maybeReleaseFlowChildren, but uses a per-flow Redis SET as
+    // the sibling registry instead of a SQL SELECT.
+    if (raw.flowId) {
+      try {
+        await _maybeReleaseFlowChildren(raw.flowId, jobId, raw.flowChildName || null, nowMs);
+      } catch (_e) { /* best-effort — sweepExpired retries if a deps check fails */ }
+      // The completed job stays in the flow set so a LATER sibling
+      // whose dependsOn includes this job's flowChildName can still
+      // find a "done" sibling when its own complete() walks the flow.
+      // The set is purge()'d when the queue is purged or — for the
+      // typical case where the operator wants to reclaim flow memory
+      // after the whole flow finishes — by an explicit operator call
+      // to purge() OR by letting `_maybeReleaseFlowChildren` reach a
+      // state where every sibling has status='done' (which the
+      // operator can detect via b.queue.dlqList / app-level queries).
+    }
     return true;
   }
 
+  async function _maybeReleaseFlowChildren(flowId, completedJobId, completedChildName, nowMs) {
+    var flowKey = _flowKey(flowId);
+    var members = await client.command("SMEMBERS", flowKey);
+    if (!members || members.length === 0) return;
+
+    // Pull dependsOn + status + flowChildName for every sibling in one
+    // pipelined batch — far cheaper than per-sibling HMGET round trips.
+    var siblingIds = members.map(function (m) {
+      return Buffer.isBuffer(m) ? m.toString("utf8") : String(m);
+    }).filter(function (id) { return id !== completedJobId; });
+    if (siblingIds.length === 0) return;
+
+    var hmgetCalls = siblingIds.map(function (sibId) {
+      return client.command("HMGET", _jobKey(sibId),
+        "dependsOn", "status", "flowChildName");
+    });
+    var results = await Promise.all(hmgetCalls);
+
+    // For each pending sibling with a dependsOn array, check if all
+    // deps are satisfied (the just-completed job AND any prior
+    // already-done sibling in the flow).
+    for (var i = 0; i < siblingIds.length; i++) {
+      var sibId = siblingIds[i];
+      var rv = results[i];
+      if (!rv || rv.length < 3) continue;
+      var rawDeps  = rv[0] && (Buffer.isBuffer(rv[0]) ? rv[0].toString("utf8") : String(rv[0]));
+      var status   = rv[1] && (Buffer.isBuffer(rv[1]) ? rv[1].toString("utf8") : String(rv[1]));
+      if (!rawDeps || status !== "pending") continue;
+      var deps;
+      try { deps = JSON.parse(rawDeps); }
+      catch (_e) { continue; }
+      if (!Array.isArray(deps) || deps.length === 0) continue;
+
+      // Resolve each dep against the just-completed job (id or child
+      // name) OR a prior-completed sibling in the flow.
+      var allDone = true;
+      for (var d = 0; d < deps.length; d++) {
+        var dep = deps[d];
+        if (dep === completedJobId) continue;
+        if (completedChildName && dep === completedChildName) continue;
+        // Look up by id first; if no hit, fall back to scanning the
+        // flow set for a sibling whose flowChildName matches.
+        var depHash = await client.command("HMGET", _jobKey(dep), "status", "flowId");
+        if (depHash && depHash[0]) {
+          var depStatus = Buffer.isBuffer(depHash[0]) ? depHash[0].toString("utf8") : String(depHash[0]);
+          var depFlow   = depHash[1] ? (Buffer.isBuffer(depHash[1]) ? depHash[1].toString("utf8") : String(depHash[1])) : "";
+          if (depStatus === "done" && depFlow === flowId) continue;
+        }
+        // Scan the flow's set for a child-name match — cheap because
+        // a flow typically has 5-50 children, not thousands.
+        var matched = false;
+        for (var s = 0; s < siblingIds.length && !matched; s++) {
+          if (siblingIds[s] === sibId) continue;
+          var sRv = results[s];
+          if (!sRv || !sRv[2]) continue;
+          var sName = Buffer.isBuffer(sRv[2]) ? sRv[2].toString("utf8") : String(sRv[2]);
+          var sStatus = sRv[1] ? (Buffer.isBuffer(sRv[1]) ? sRv[1].toString("utf8") : String(sRv[1])) : "";
+          if (sName === dep && sStatus === "done") matched = true;
+        }
+        if (!matched) { allDone = false; break; }
+      }
+
+      if (allDone) {
+        // Read queueName so the ZADD targets the right ready zset.
+        var qBuf = await client.command("HGET", _jobKey(sibId), "queueName");
+        if (!qBuf) continue;
+        var queueName = Buffer.isBuffer(qBuf) ? qBuf.toString("utf8") : String(qBuf);
+        await Promise.all([
+          client.command("HSET", _jobKey(sibId), "availableAt", String(nowMs)),
+          client.command("ZADD", _readyKey(queueName), String(nowMs), sibId),
+        ]);
+      }
+    }
+  }
+
   async function fail(jobId, errorMessage, retryDelayMs) {
     await _ensureConnected();
     var nowMs = Date.now();
@@ -503,8 +636,11 @@ function create(opts) {
 
   async function purge(queueName) {
     await _ensureConnected();
-    // Walk the ready + inflight + dlq zsets, delete the per-job
-    // hashes, then drop the zsets and the queues-set membership.
+    // Walk the ready + inflight + dlq zsets, collect every job id,
+    // also clear each job from its flow set (if any), then DEL the
+    // job hashes + zsets + queues-membership. Flow sets are cleared
+    // job-by-job because a single flow can span multiple queues, and
+    // we only want to evict THIS queue's contributors.
     var [readyMembers, inflightMembers, dlqMembers] = await Promise.all([
       client.command("ZRANGE", _readyKey(queueName),    "0", "-1"),
       client.command("ZRANGE", _inflightKey(queueName), "0", "-1"),
@@ -512,6 +648,18 @@ function create(opts) {
     ]);
     var allIds = [].concat(readyMembers || [], inflightMembers || [], dlqMembers || [])
       .map(function (b) { return Buffer.isBuffer(b) ? b.toString("utf8") : String(b); });
+    // Pull the flowId for each job (if set) so we can SREM from the
+    // matching flow set BEFORE we DEL the job hash.
+    var flowIdLookups = await Promise.all(allIds.map(function (id) {
+      return client.command("HGET", _jobKey(id), "flowId");
+    }));
+    var flowSrems = [];
+    for (var fi = 0; fi < allIds.length; fi++) {
+      var fIdBuf = flowIdLookups[fi];
+      if (!fIdBuf) continue;
+      var fId = Buffer.isBuffer(fIdBuf) ? fIdBuf.toString("utf8") : String(fIdBuf);
+      if (fId) flowSrems.push(client.command("SREM", _flowKey(fId), allIds[fi]));
+    }
     var dels = allIds.map(function (id) { return client.command("DEL", _jobKey(id)); });
     var zdrops = [
       client.command("DEL", _readyKey(queueName)),
@@ -519,7 +667,7 @@ function create(opts) {
       client.command("DEL", _dlqKey(queueName)),
       client.command("SREM", _queuesKey(), queueName),
     ];
-    await Promise.all(dels.concat(zdrops));
+    await Promise.all(flowSrems.concat(dels, zdrops));
     return allIds.length;
   }
 

package/lib/websocket.js

@@ -82,6 +82,7 @@
  */
 
 var nodeCrypto = require("crypto");
+var zlib = require("zlib");
 var { EventEmitter } = require("events");
 var C = require("./constants");
 var requestHelpers = require("./request-helpers");
@@ -220,7 +221,7 @@ function isOriginAllowed(req, origins) {
   return false;
 }
 
-function buildUpgradeResponse(secWebSocketKey, subprotocol) {
+function buildUpgradeResponse(secWebSocketKey, subprotocol, extensionHeader) {
   var lines = [
     "HTTP/1.1 101 Switching Protocols",
     "Upgrade: websocket",
@@ -228,9 +229,107 @@ function buildUpgradeResponse(secWebSocketKey, subprotocol) {
     "Sec-WebSocket-Accept: " + computeAcceptKey(secWebSocketKey),
   ];
   if (subprotocol) lines.push("Sec-WebSocket-Protocol: " + subprotocol);
+  if (extensionHeader) lines.push("Sec-WebSocket-Extensions: " + extensionHeader);
   return lines.join("\r\n") + "\r\n\r\n";
 }
 
+// ---- permessage-deflate (RFC 7692) ----
+//
+// Negotiate compression at handshake, compress per-message on send,
+// decompress per-message on receive. The framework runs in
+// "no_context_takeover" mode in both directions — every message uses a
+// fresh zlib state, no LZ77 history carried across messages. This
+// trade-off makes message processing stateless (no per-connection
+// zlib stream lifetime to manage) at a small compression-ratio cost.
+// Operators with throughput-sensitive workloads can extend this later
+// to keep state across messages.
+//
+// Per RFC 7692 §7.2.1 the deflate output is the standard zlib raw
+// deflate WITH the trailing 4 bytes 0x00 0x00 0xff 0xff stripped. The
+// matching inflate path appends them back before inflating.
+var DEFLATE_TRAILING = Buffer.from([0x00, 0x00, 0xff, 0xff]);
+
+function _parseExtensionHeader(header) {
+  // Sec-WebSocket-Extensions: foo; param=val; param2, bar; ...
+  // Returns [{ name, params: { paramName: value | true } }]
+  if (!header) return [];
+  var entries = String(header).split(",");
+  var out = [];
+  for (var i = 0; i < entries.length; i++) {
+    var parts = entries[i].split(";").map(function (s) { return s.trim(); });
+    if (!parts[0]) continue;
+    var ext = { name: parts[0].toLowerCase(), params: {} };
+    for (var j = 1; j < parts.length; j++) {
+      var kv = parts[j].split("=");
+      var k = kv[0].trim().toLowerCase();
+      if (!k) continue;
+      var v = kv.length > 1 ? kv.slice(1).join("=").trim() : true;
+      // Strip surrounding quotes per the token-or-quoted-string grammar.
+      if (typeof v === "string" && v.length >= 2 &&
+          v.charAt(0) === '"' && v.charAt(v.length - 1) === '"') {
+        v = v.slice(1, -1);
+      }
+      ext.params[k] = v;
+    }
+    out.push(ext);
+  }
+  return out;
+}
+
+function _negotiatePermessageDeflate(reqHeader) {
+  var entries = _parseExtensionHeader(reqHeader);
+  for (var i = 0; i < entries.length; i++) {
+    if (entries[i].name !== "permessage-deflate") continue;
+    var p = entries[i].params;
+    // Reject unknown params (RFC 7692 §7 lists exactly four).
+    var KNOWN = {
+      "server_no_context_takeover": true, "client_no_context_takeover": true,
+      "server_max_window_bits": true,     "client_max_window_bits": true,
+    };
+    var ok = true;
+    for (var k in p) { if (Object.prototype.hasOwnProperty.call(p, k) && !KNOWN[k]) { ok = false; break; } }
+    if (!ok) continue;
+    // Always negotiate WITH no_context_takeover in BOTH directions, so
+    // every message uses a fresh zlib state. Echo any client window-
+    // bits constraints back unchanged (we honour them on the server's
+    // outgoing compression).
+    var responseParams = ["client_no_context_takeover", "server_no_context_takeover"];
+    if (p.client_max_window_bits && p.client_max_window_bits !== true) {
+      responseParams.push("client_max_window_bits=" + p.client_max_window_bits);
+    }
+    if (p.server_max_window_bits && p.server_max_window_bits !== true) {
+      responseParams.push("server_max_window_bits=" + p.server_max_window_bits);
+    }
+    return {
+      negotiated: true,
+      responseHeader: "permessage-deflate; " + responseParams.join("; "),
+      // window-bits constraints we honour; default 15 (max) when unset.
+      serverMaxWindowBits: p.server_max_window_bits && p.server_max_window_bits !== true
+        ? Math.max(8, Math.min(15, parseInt(p.server_max_window_bits, 10) || 15)) : 15,
+      clientMaxWindowBits: p.client_max_window_bits && p.client_max_window_bits !== true
+        ? Math.max(8, Math.min(15, parseInt(p.client_max_window_bits, 10) || 15)) : 15,
+    };
+  }
+  return { negotiated: false };
+}
+
+function _deflateMessage(payload, windowBits) {
+  // Per RFC 7692 §7.2.1, strip the 4-byte 0x00 0x00 0xff 0xff trailer.
+  var raw = zlib.deflateRawSync(payload, { windowBits: windowBits, level: zlib.constants.Z_DEFAULT_COMPRESSION });
+  if (raw.length >= 4 &&
+      raw[raw.length - 4] === 0x00 && raw[raw.length - 3] === 0x00 &&
+      raw[raw.length - 2] === 0xff && raw[raw.length - 1] === 0xff) {
+    return raw.slice(0, raw.length - 4);
+  }
+  return raw;
+}
+
+function _inflateMessage(payload, windowBits) {
+  // Per RFC 7692 §7.2.2, append the 4-byte trailer before inflating.
+  var withTrailer = Buffer.concat([payload, DEFLATE_TRAILING]);
+  return zlib.inflateRawSync(withTrailer, { windowBits: windowBits });
+}
+
 // ---- Frame parser ----
 //
 // Incremental — push(chunk) accepts arbitrary buffer slices from the
@@ -339,6 +438,11 @@ function serializeFrame(opcode, payload, opts) {
   opts = opts || {};
   var fin  = opts.fin !== false;
   var mask = opts.mask === true;       // server-side defaults false
+  // RSV1 — set on the first frame of a permessage-deflate-compressed
+  // message (RFC 7692). Caller passes opts.rsv1 = true; we wire it
+  // into the header byte. RSV2 / RSV3 stay zero (no other extensions
+  // negotiated).
+  var rsv1 = opts.rsv1 === true;
   payload = payload || Buffer.alloc(0);
   if (typeof payload === "string") payload = Buffer.from(payload, "utf8");
   if (!Buffer.isBuffer(payload)) {
@@ -355,7 +459,7 @@ function serializeFrame(opcode, payload, opts) {
   if (mask) headerLen += 4;
 
   var header = Buffer.alloc(headerLen);
-  header[0] = (fin ? 0x80 : 0) | (opcode & 0x0F);
+  header[0] = (fin ? 0x80 : 0) | (rsv1 ? 0x40 : 0) | (opcode & 0x0F);
   header[1] = (mask ? 0x80 : 0) | lenByte;
 
   var off = 2;
@@ -396,6 +500,10 @@ class WebSocketConnection extends EventEmitter {
     //                  exists to protect against in h1 (proxy
     //                  cache-poisoning via raw text on the wire).
     this.transport = opts.transport === "h2" ? "h2" : "h1";
+    // permessage-deflate state — `null` means extension not negotiated.
+    // When negotiated the object carries serverMaxWindowBits +
+    // clientMaxWindowBits the inflate/deflate paths use per message.
+    this._permessageDeflate = opts.permessageDeflate || null;
     var pingMs = opts.pingIntervalMs || DEFAULT_PING_INTERVAL_MS;
     var pongMs = opts.pongTimeoutMs  || DEFAULT_PONG_TIMEOUT_MS;
     // Grace period after we send a close frame before forcing the
@@ -488,11 +596,20 @@ class WebSocketConnection extends EventEmitter {
       return this._abort(CLOSE_PROTOCOL_ERROR, "frame must not be masked (h2)");
     }
     // Reserved bits — must be zero unless a negotiated extension uses them.
-    // We don't negotiate any extensions today (compression deferred), so
-    // any RSV bit set is a protocol error.
-    if (frame.rsv1 || frame.rsv2 || frame.rsv3) {
+    // RSV1 is permessage-deflate (RFC 7692). RSV2/RSV3 unused; any RSV2
+    // or RSV3 bit set, OR RSV1 set when permessage-deflate wasn't
+    // negotiated, is a protocol error.
+    if (frame.rsv2 || frame.rsv3) {
       return this._abort(CLOSE_PROTOCOL_ERROR, "reserved bits set without extension");
     }
+    if (frame.rsv1 && !this._permessageDeflate) {
+      return this._abort(CLOSE_PROTOCOL_ERROR, "RSV1 set without permessage-deflate negotiated");
+    }
+    // RSV1 is only legal on the FIRST frame of a message (TEXT/BINARY).
+    // Continuation frames inherit the compression flag from the start.
+    if (frame.rsv1 && frame.opcode === OPCODE_CONTINUATION) {
+      return this._abort(CLOSE_PROTOCOL_ERROR, "RSV1 on continuation frame (must be on start)");
+    }
 
     if (frame.opcode === OPCODE_CONTINUATION) {
       if (this._fragOpcode === null) {
@@ -506,6 +623,7 @@ class WebSocketConnection extends EventEmitter {
       this._fragOpcode = frame.opcode;
       this._fragChunks = [frame.payload];
       this._fragLen    = frame.payload.length;
+      this._fragCompressed = !!frame.rsv1;
       if (frame.fin) this._emitMessage();
     } else if (frame.opcode === OPCODE_CLOSE) {
       this._handleClose(frame);
@@ -535,9 +653,26 @@ class WebSocketConnection extends EventEmitter {
       ? this._fragChunks[0]
       : Buffer.concat(this._fragChunks, this._fragLen);
     var opcode = this._fragOpcode;
+    var wasCompressed = this._fragCompressed;
     this._fragOpcode = null;
     this._fragChunks = null;
     this._fragLen    = 0;
+    this._fragCompressed = false;
+    // Decompress before emitting if the start frame had RSV1 set.
+    // RFC 7692: malformed deflate is a protocol error, surfaced as
+    // CLOSE_INVALID_PAYLOAD per §5.6 / §6 of RFC 6455.
+    if (wasCompressed) {
+      try {
+        data = _inflateMessage(data, this._permessageDeflate.clientMaxWindowBits);
+      } catch (e) {
+        return this._abort(CLOSE_INVALID_PAYLOAD,
+          "permessage-deflate inflate failed: " + ((e && e.message) || String(e)));
+      }
+      if (data.length > this.maxMessageBytes) {
+        return this._abort(CLOSE_MESSAGE_TOO_BIG,
+          "decompressed message exceeds maxMessageBytes");
+      }
+    }
     if (opcode === OPCODE_TEXT) {
       // §5.6: text frames MUST be valid UTF-8. Buffer.toString silently
       // replaces invalid sequences with U+FFFD; explicit validation
@@ -581,7 +716,7 @@ class WebSocketConnection extends EventEmitter {
     this._sendFrame(OPCODE_CLOSE, payload);
   }
 
-  _sendFrame(opcode, payload) {
+  _sendFrame(opcode, payload, opts) {
     if (this._state === STATE_CLOSED) return;
     // Socket may have been destroyed by the peer between our last
     // 'close' event check and this write — Node's 'close' event is
@@ -593,28 +728,48 @@ class WebSocketConnection extends EventEmitter {
       return;
     }
     try {
-      this.socket.write(serializeFrame(opcode, payload));
+      this.socket.write(serializeFrame(opcode, payload, opts));
     } catch (err) {
       this._transitionToClosed(1006, (err && err.message) || "write failed", false, err);
     }
   }
 
+  _sendDataFrame(opcode, payload) {
+    // Compress entire-message-in-one-frame when permessage-deflate
+    // negotiated. RSV1 set on the FIRST frame of the message to mark
+    // it compressed; opcode-only continuation frames don't repeat
+    // RSV1 (see _onFrame's RSV1+continuation guard).
+    if (this._permessageDeflate && opcode !== OPCODE_PING &&
+        opcode !== OPCODE_PONG && opcode !== OPCODE_CLOSE) {
+      try {
+        var compressed = _deflateMessage(payload, this._permessageDeflate.serverMaxWindowBits);
+        this._sendFrame(opcode, compressed, { rsv1: true });
+        return;
+      } catch (_e) {
+        // Compression failure on send — fall through to uncompressed
+        // (we still have the original payload) so the connection
+        // keeps working. The underlying issue surfaces as observability.
+      }
+    }
+    this._sendFrame(opcode, payload);
+  }
+
   send(data) {
     if (this._state !== STATE_OPEN) {
       throw new WebSocketError("ws/closed",
         "connection is " + this._state + ", cannot send");
     }
     if (typeof data === "string") {
-      this._sendFrame(OPCODE_TEXT, Buffer.from(data, "utf8"));
+      this._sendDataFrame(OPCODE_TEXT, Buffer.from(data, "utf8"));
     } else if (Buffer.isBuffer(data)) {
-      this._sendFrame(OPCODE_BINARY, data);
+      this._sendDataFrame(OPCODE_BINARY, data);
     } else {
       data = safeBuffer.toBuffer(data, {
         errorClass: WebSocketError,
         typeCode:   "ws/invalid-payload",
         typeMessage: "send() requires Buffer, Uint8Array, or string",
       });
-      this._sendFrame(OPCODE_BINARY, data);
+      this._sendDataFrame(OPCODE_BINARY, data);
     }
   }
 
@@ -687,9 +842,20 @@ function handleUpgrade(req, socket, head, opts) {
   // Subprotocol negotiation.
   var subprotocol = negotiateSubprotocol(req, opts.subprotocols);
 
+  // permessage-deflate negotiation. Skipped (no echo header, no
+  // compression state on the connection) when the operator passes
+  // opts.permessageDeflate = false OR when the client didn't offer it.
+  var pmd = null;
+  if (opts.permessageDeflate !== false) {
+    var negotiated = _negotiatePermessageDeflate(req.headers["sec-websocket-extensions"]);
+    if (negotiated.negotiated) pmd = negotiated;
+  }
+
   // Send 101.
   try {
-    socket.write(buildUpgradeResponse(req.headers["sec-websocket-key"], subprotocol));
+    socket.write(buildUpgradeResponse(
+      req.headers["sec-websocket-key"], subprotocol,
+      pmd ? pmd.responseHeader : null));
   } catch (err) {
     log.error("failed to write upgrade response: " + err.message);
     try { socket.destroy(); } catch (_e) {}
@@ -701,10 +867,11 @@ function handleUpgrade(req, socket, head, opts) {
   // parser via a synthetic data event. Most clients don't send
   // anything before the 101 response, but the spec allows it.
   var conn = new WebSocketConnection(socket, {
-    subprotocol:     subprotocol,
-    maxMessageBytes: opts.maxMessageBytes,
-    pingIntervalMs:  opts.pingIntervalMs,
-    pongTimeoutMs:   opts.pongTimeoutMs,
+    subprotocol:        subprotocol,
+    maxMessageBytes:    opts.maxMessageBytes,
+    pingIntervalMs:     opts.pingIntervalMs,
+    pongTimeoutMs:      opts.pongTimeoutMs,
+    permessageDeflate:  pmd,
   });
   if (head && head.length > 0) {
     // Manually invoke the data path with the pre-read bytes.

package/package.json

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