@blamejs/core 0.4.10 → 0.4.11

package/CHANGELOG.md

@@ -8,6 +8,7 @@ upgrading across more than a few patches at a time.
 
 ## v0.4.x
 
+- **0.4.10** (2026-04-30) — bodyParser multipart: fileFilter + per-field maxBytes/mimeTypes
 - **0.4.9** (2026-04-30) — Origin-Agent-Cluster + DNS-Prefetch-Control headers; b.auth.lockout primitive
 - **0.4.8** (2026-04-30) — wiki SEO surface: per-page OG / Twitter / JSON-LD + sitemap.xml + robots.txt
 - **0.4.7** (2026-04-30) — audit-fix the welcome page's "what's in the box" table

package/lib/cache.js

@@ -7,10 +7,13 @@
  *     backend:     "memory",
  *     ttlMs:       C.TIME.minutes(5),
  *     maxEntries:  10000,
- *     audit:       b.audit,           // optional
+ *     maxBytes:    C.BYTES.mib(100),                 // memory backend only
+ *     sizeOf:      function (v) { return v.byteLength; },  // optional override
+ *     slidingTtl:  true,                              // bump expiresAt on hit
+ *     audit:       b.audit,                           // optional
  *   });
  *
- *   await cache.set("u-42", record);
+ *   await cache.set("u-42", record, { ttlMs: C.TIME.minutes(10), tags: ["user:42", "session"] });
  *   var hit = await cache.get("u-42");
  *
  *   // Memoize / read-through:
@@ -18,15 +21,21 @@
  *     return db.users.findOne({ _id: "u-42" });
  *   });
  *
+ *   // Bulk invalidate (memory backend):
+ *   await cache.invalidateTag("user:42");          // purges every entry tagged user:42
+ *
  * Surface (returned by create):
  *
  *   get(key)                  → value | undefined
- *   set(key, value, opts?)    → void                  (opts: { ttlMs })
+ *   set(key, value, opts?)    → void                  (opts: { ttlMs, tags })
  *   del(key)                  → boolean (existed)
  *   has(key)                  → boolean (does NOT bump LRU recency)
  *   clear(opts?)              → number (purged)        (opts: { req, context })
  *   size()                    → number
+ *   bytes()                   → number (memory backend only — total stored bytes)
  *   wrap(key, fn, opts?)      → fn's return value      (opts: { ttlMs, singleFlight })
+ *   invalidateTag(tag, opts?) → number (purged)        (opts: { req, context })
+ *   getTags(key)              → string[] | null
  *   close()                   → void
  *
  * Backends:
@@ -59,14 +68,26 @@
  *     would drown at any reasonable QPS)
  *
  * The cache supports single-flight wrap (concurrent calls collapse),
- * stale-while-revalidate, LRU eviction on the memory backend, a shared
- * cluster backend, and a custom-backend escape hatch.
+ * stale-while-revalidate, LRU + bytes eviction on the memory backend,
+ * sliding TTL on hit, tag-based bulk invalidation (memory backend), a
+ * shared cluster backend, and a custom-backend escape hatch.
+ *
+ * What is NOT in the box:
  *
- * Distributed pubsub invalidation, tag-based invalidation, and
- * compression for the cluster backend are not built in — the cluster
- * backend is always-fresh-by-shared-table, memory caches go
- * stale-on-other-nodes by design, and read-through is what `wrap()`
- * is for.
+ *   - Tag invalidation on the cluster backend — invalidating tagged
+ *     entries across cluster nodes ties to a future distributed-pubsub
+ *     slice. invalidateTag against a cluster-backend cache throws
+ *     NOT_SUPPORTED today; operators wanting cluster-scope tag wipe
+ *     run their own DELETE against _blamejs_cache.
+ *   - maxBytes on the cluster backend — per-row size accounting against
+ *     a shared table would mean an aggregate query on every set. The
+ *     operator controls cluster-table size with their own pruning if
+ *     bytes pressure surfaces.
+ *   - Per-entry exact slidingTtl on the cluster backend — sliding works
+ *     on cluster but extends by the cache's defaultTtlMs (we don't
+ *     store per-row ttl). Operators with mixed-TTL writes wanting
+ *     strict per-entry sliding use the memory backend or extend at
+ *     the application layer.
  */
 
 var clusterStorage = require("./cluster-storage");
@@ -84,8 +105,10 @@ var DEFAULTS = Object.freeze({
   backend:                 "memory",
   ttlMs:                   C.TIME.minutes(5),
   maxEntries:              10000,
+  maxBytes:                Infinity,
   sweepIntervalMs:         C.TIME.minutes(1),
   staleWhileRevalidate:    false,
+  slidingTtl:              false,
   auditFailures:           true,
   auditClear:              true,
 });
@@ -118,6 +141,29 @@ function _validateMaxEntries(value) {
   }
 }
 
+function _validateMaxBytes(value) {
+  if (value === Infinity) return;
+  if (!_isFiniteNonNegative(value) || value < 1) {
+    throw _err("BAD_OPT", "cache.create: maxBytes must be a positive finite number or Infinity, got " +
+      JSON.stringify(value));
+  }
+}
+
+// Default sizeOf — best-effort byte estimate. Operators with structured
+// values (large objects, custom classes) should pass their own sizeOf
+// for accuracy.
+function _defaultSizeOf(value) {
+  if (value === null || value === undefined) return 0;
+  if (Buffer.isBuffer(value)) return value.length;
+  if (typeof value === "string") return Buffer.byteLength(value, "utf8");
+  if (typeof value === "number" || typeof value === "boolean") return 8;
+  // Fallback: round-trip through JSON. Cost is real; documented in the
+  // DEFAULTS docstring so operators with hot-path size accounting know
+  // to supply their own sizeOf.
+  try { return Buffer.byteLength(JSON.stringify(value), "utf8"); }
+  catch (_e) { return 0; }
+}
+
 function _validateBackendObject(backend) {
   var required = ["get", "set", "del", "clear", "size", "close"];
   if (typeof backend !== "object" || backend === null) {
@@ -156,6 +202,13 @@ function _validateCreateOpts(opts) {
   }
   if (opts.ttlMs !== undefined) _validateTtl("cache.create: ttlMs", opts.ttlMs);
   if (opts.maxEntries !== undefined) _validateMaxEntries(opts.maxEntries);
+  if (opts.maxBytes !== undefined) _validateMaxBytes(opts.maxBytes);
+  if (opts.sizeOf !== undefined && typeof opts.sizeOf !== "function") {
+    throw _err("BAD_OPT", "cache.create: sizeOf must be a function (value) → bytes");
+  }
+  if (opts.slidingTtl !== undefined && typeof opts.slidingTtl !== "boolean") {
+    throw _err("BAD_OPT", "cache.create: slidingTtl must be a boolean");
+  }
   if (opts.sweepIntervalMs !== undefined) {
     if (!_isFiniteNonNegative(opts.sweepIntervalMs) || opts.sweepIntervalMs < 1000) {
       throw _err("BAD_OPT", "cache.create: sweepIntervalMs must be a finite number ≥ 1000ms, got " +
@@ -199,24 +252,54 @@ function _validateKey(key, ctx) {
 // re-inserting a key on hit moves it to the most-recent position).
 
 function _memoryBackend(cfg) {
-  var entries = new Map();    // key → { value, expiresAt }
+  var entries = new Map();         // key → { value, expiresAt, ttlMs, bytes, tags }
   var maxEntries = cfg.maxEntries;
-  var clock = cfg.clock;
-  var emitObs = cfg.emitObs;
-  var namespace = cfg.namespace;
+  var maxBytes   = cfg.maxBytes;
+  var sizeOf     = cfg.sizeOf;
+  var slidingTtl = cfg.slidingTtl;
+  var clock      = cfg.clock;
+  var emitObs    = cfg.emitObs;
+  var namespace  = cfg.namespace;
   var sweepTimer = null;
+  var totalBytes = 0;
+
+  // tag → Set<key>. Bidirectional with entry.tags for fast invalidate.
+  var tagIndex = new Map();
 
   function _isExpired(entry, now) {
     return entry.expiresAt !== Infinity && entry.expiresAt <= now;
   }
 
-  function _evictOldestIfFull() {
-    if (maxEntries === Infinity) return;
-    while (entries.size > maxEntries) {
+  function _untrack(key, entry) {
+    if (!entry) return;
+    totalBytes -= entry.bytes || 0;
+    if (totalBytes < 0) totalBytes = 0;
+    if (entry.tags && entry.tags.length > 0) {
+      for (var i = 0; i < entry.tags.length; i++) {
+        var s = tagIndex.get(entry.tags[i]);
+        if (s) {
+          s.delete(key);
+          if (s.size === 0) tagIndex.delete(entry.tags[i]);
+        }
+      }
+    }
+  }
+
+  function _evictByCounts() {
+    while (maxEntries !== Infinity && entries.size > maxEntries) {
       var oldest = entries.keys().next().value;
+      var e = entries.get(oldest);
+      _untrack(oldest, e);
       entries.delete(oldest);
       emitObs("cache.eviction.size", { namespace: namespace });
     }
+    while (maxBytes !== Infinity && totalBytes > maxBytes && entries.size > 0) {
+      var oldestB = entries.keys().next().value;
+      var eb = entries.get(oldestB);
+      _untrack(oldestB, eb);
+      entries.delete(oldestB);
+      emitObs("cache.eviction.bytes", { namespace: namespace });
+    }
   }
 
   async function get(key) {
@@ -224,32 +307,63 @@ function _memoryBackend(cfg) {
     var entry = entries.get(key);
     if (!entry) return undefined;
     if (_isExpired(entry, now)) {
+      _untrack(key, entry);
       entries.delete(key);
       emitObs("cache.eviction.expired", { namespace: namespace });
       return undefined;
     }
+    // Sliding TTL: extend lifetime on each successful read by the
+    // entry's original ttlMs. Infinity stays Infinity.
+    if (slidingTtl && entry.ttlMs !== Infinity && typeof entry.ttlMs === "number") {
+      entry.expiresAt = now + entry.ttlMs;
+    }
     // LRU recency bump: re-insert moves to the most-recent slot.
     entries.delete(key);
     entries.set(key, entry);
     return entry.value;
   }
 
-  async function set(key, value, expiresAt) {
-    // Existing key replacement: delete first so re-insert lands at the
-    // most-recent position (LRU on overwrite).
-    entries.delete(key);
-    entries.set(key, { value: value, expiresAt: expiresAt });
-    _evictOldestIfFull();
+  async function set(key, value, expiresAt, meta) {
+    // Existing key replacement: untrack first to rebalance bytes + tags.
+    var prior = entries.get(key);
+    if (prior) {
+      _untrack(key, prior);
+      entries.delete(key);
+    }
+    var bytes = sizeOf(value) || 0;
+    var ttlMs = meta && typeof meta.ttlMs === "number" ? meta.ttlMs : null;
+    var tags  = (meta && Array.isArray(meta.tags)) ? meta.tags.slice() : null;
+    entries.set(key, {
+      value:     value,
+      expiresAt: expiresAt,
+      ttlMs:     ttlMs,
+      bytes:     bytes,
+      tags:      tags,
+    });
+    totalBytes += bytes;
+    if (tags && tags.length > 0) {
+      for (var i = 0; i < tags.length; i++) {
+        var s = tagIndex.get(tags[i]);
+        if (!s) { s = new Set(); tagIndex.set(tags[i], s); }
+        s.add(key);
+      }
+    }
+    _evictByCounts();
   }
 
   async function del(key) {
-    return entries.delete(key);
+    var entry = entries.get(key);
+    if (!entry) return false;
+    _untrack(key, entry);
+    entries.delete(key);
+    return true;
   }
 
   async function has(key) {
     var entry = entries.get(key);
     if (!entry) return false;
     if (_isExpired(entry, clock())) {
+      _untrack(key, entry);
       entries.delete(key);
       emitObs("cache.eviction.expired", { namespace: namespace });
       return false;
@@ -260,6 +374,8 @@ function _memoryBackend(cfg) {
   async function clear() {
     var n = entries.size;
     entries.clear();
+    tagIndex.clear();
+    totalBytes = 0;
     return n;
   }
 
@@ -273,19 +389,45 @@ function _memoryBackend(cfg) {
     return live;
   }
 
+  async function invalidateTag(tag) {
+    var keys = tagIndex.get(tag);
+    if (!keys || keys.size === 0) return 0;
+    var purged = 0;
+    var toDelete = Array.from(keys);
+    for (var i = 0; i < toDelete.length; i++) {
+      var k = toDelete[i];
+      var entry = entries.get(k);
+      if (entry) {
+        _untrack(k, entry);
+        entries.delete(k);
+        purged++;
+      }
+    }
+    return purged;
+  }
+
+  async function getTags(key) {
+    var entry = entries.get(key);
+    if (!entry) return null;
+    return entry.tags ? entry.tags.slice() : [];
+  }
+
+  async function bytes() {
+    return totalBytes;
+  }
+
   function _sweep() {
     var now = clock();
     var purged = 0;
     for (var k of Array.from(entries.keys())) {
       var e = entries.get(k);
       if (_isExpired(e, now)) {
+        _untrack(k, e);
         entries.delete(k);
         purged++;
       }
     }
     if (purged > 0) {
-      // Single observability event per sweep cycle is enough — operators
-      // see "purge happened with N evictions" via labels in dashboards.
       for (var i = 0; i < purged; i++) emitObs("cache.eviction.expired", { namespace: namespace });
     }
   }
@@ -299,20 +441,25 @@ function _memoryBackend(cfg) {
   async function close() {
     if (sweepTimer) { clearInterval(sweepTimer); sweepTimer = null; }
     entries.clear();
+    tagIndex.clear();
+    totalBytes = 0;
   }
 
   return {
-    name:         "memory",
-    get:          get,
-    set:          set,
-    del:          del,
-    has:          has,
-    clear:        clear,
-    size:         size,
-    close:        close,
-    _startSweep:  _startSweep,
+    name:           "memory",
+    get:            get,
+    set:            set,
+    del:            del,
+    has:            has,
+    clear:          clear,
+    size:           size,
+    bytes:          bytes,
+    invalidateTag:  invalidateTag,
+    getTags:        getTags,
+    close:          close,
+    _startSweep:    _startSweep,
     // Test hook: raw entries map for state inspection
-    _entries:     entries,
+    _entries:       entries,
   };
 }
 
@@ -321,9 +468,11 @@ function _memoryBackend(cfg) {
 // value serialization. UPSERT via ON CONFLICT for atomic set.
 
 function _clusterBackend(cfg) {
-  var namespace = cfg.namespace;
-  var clock = cfg.clock;
-  var emitObs = cfg.emitObs;
+  var namespace      = cfg.namespace;
+  var clock          = cfg.clock;
+  var emitObs        = cfg.emitObs;
+  var slidingTtl     = cfg.slidingTtl;
+  var defaultTtlMs   = cfg.defaultTtlMs;
 
   // Composite cluster key. Namespace was validated to not contain ":"
   // at create time, so the split is unambiguous.
@@ -348,6 +497,18 @@ function _clusterBackend(cfg) {
       emitObs("cache.eviction.expired", { namespace: namespace });
       return undefined;
     }
+    // Sliding TTL on cluster: extend by the cache's defaultTtlMs (we don't
+    // store per-row ttl). Operators with mixed-TTL writes wanting strict
+    // per-entry sliding use the memory backend or extend at app layer.
+    // Fire-and-forget — best-effort lifetime extension.
+    if (slidingTtl && defaultTtlMs !== Infinity && typeof defaultTtlMs === "number") {
+      var newExpires = now + defaultTtlMs;
+      clusterStorage.execute(
+        "UPDATE _blamejs_cache SET expiresAt = ?, updatedAt = ? " +
+        "WHERE cacheKey = ? AND expiresAt > ?",
+        [newExpires, now, _composedKey(key), now]
+      ).catch(function () { /* best-effort */ });
+    }
     try { return JSON.parse(row.valueJson); }
     catch (_e) { return undefined; }
   }
@@ -451,7 +612,10 @@ function _customBackend(operatorBackend, cfg) {
   return {
     name:         "custom",
     get:          function (key) { return operatorBackend.get(key); },
-    set:          function (key, value, expiresAt) { return operatorBackend.set(key, value, expiresAt); },
+    set:          function (key, value, expiresAt, meta) {
+      // Older 3-arg backends remain compatible — meta is opt-in.
+      return operatorBackend.set(key, value, expiresAt, meta);
+    },
     del:          function (key) { return operatorBackend.del(key); },
     has:          function (key) {
       // Optional has() — fall back to get-and-coerce if operator didn't
@@ -461,6 +625,18 @@ function _customBackend(operatorBackend, cfg) {
     },
     clear:        function () { return operatorBackend.clear(); },
     size:         function () { return operatorBackend.size(); },
+    bytes:        function () {
+      if (typeof operatorBackend.bytes === "function") return operatorBackend.bytes();
+      return Promise.resolve(0);
+    },
+    invalidateTag: function (tag) {
+      if (typeof operatorBackend.invalidateTag === "function") return operatorBackend.invalidateTag(tag);
+      return Promise.resolve(0);
+    },
+    getTags: function (key) {
+      if (typeof operatorBackend.getTags === "function") return operatorBackend.getTags(key);
+      return Promise.resolve(null);
+    },
     close:        function () { return operatorBackend.close(); },
     _startSweep:  function () { /* operator backend manages its own sweep */ },
   };
@@ -471,8 +647,8 @@ function _customBackend(operatorBackend, cfg) {
 function create(opts) {
   opts = opts || {};
   validateOpts(opts, [
-    "namespace", "backend", "ttlMs", "maxEntries",
-    "sweepIntervalMs", "staleWhileRevalidate",
+    "namespace", "backend", "ttlMs", "maxEntries", "maxBytes", "sizeOf",
+    "sweepIntervalMs", "staleWhileRevalidate", "slidingTtl",
     "auditFailures", "auditClear",
     "audit", "observability", "clock",
   ], "cache");
@@ -482,8 +658,11 @@ function create(opts) {
   var backendKind      = opts.backend || DEFAULTS.backend;
   var defaultTtlMs     = (opts.ttlMs            === undefined) ? DEFAULTS.ttlMs            : opts.ttlMs;
   var maxEntries       = (opts.maxEntries       === undefined) ? DEFAULTS.maxEntries       : opts.maxEntries;
+  var maxBytes         = (opts.maxBytes         === undefined) ? DEFAULTS.maxBytes         : opts.maxBytes;
+  var sizeOf           = (typeof opts.sizeOf === "function") ? opts.sizeOf : _defaultSizeOf;
   var sweepIntervalMs  = (opts.sweepIntervalMs  === undefined) ? DEFAULTS.sweepIntervalMs  : opts.sweepIntervalMs;
   var staleRevalidate  = (opts.staleWhileRevalidate === undefined) ? DEFAULTS.staleWhileRevalidate : opts.staleWhileRevalidate;
+  var slidingTtl       = (opts.slidingTtl       === undefined) ? DEFAULTS.slidingTtl       : opts.slidingTtl;
   var auditFailures    = (opts.auditFailures    === undefined) ? DEFAULTS.auditFailures    : opts.auditFailures;
   var auditClear       = (opts.auditClear       === undefined) ? DEFAULTS.auditClear       : opts.auditClear;
   var audit            = opts.audit || null;
@@ -528,11 +707,15 @@ function create(opts) {
 
   // Resolve backend
   var cfg = {
-    namespace:    namespace,
-    maxEntries:   maxEntries,
-    clock:        clock,
-    emitObs:      emitObs,
-    _sweepTimer:  null,
+    namespace:     namespace,
+    maxEntries:    maxEntries,
+    maxBytes:      maxBytes,
+    sizeOf:        sizeOf,
+    slidingTtl:    slidingTtl,
+    defaultTtlMs:  defaultTtlMs,
+    clock:         clock,
+    emitObs:       emitObs,
+    _sweepTimer:   null,
   };
   var backend;
   if (backendKind === "memory") {
@@ -598,7 +781,15 @@ function create(opts) {
     var ttlMs = _resolveTtl(callerOpts, "set");
     if (ttlMs === 0) return;    // 0 means "do not cache"
     var expiresAt = (ttlMs === Infinity) ? Infinity : (clock() + ttlMs);
-    try { await backend.set(key, value, expiresAt); }
+    var tags = (callerOpts && Array.isArray(callerOpts.tags)) ? callerOpts.tags : null;
+    if (tags) {
+      for (var i = 0; i < tags.length; i++) {
+        if (typeof tags[i] !== "string" || tags[i].length === 0) {
+          throw _err("BAD_OPT", "cache.set: tags must be an array of non-empty strings");
+        }
+      }
+    }
+    try { await backend.set(key, value, expiresAt, { ttlMs: ttlMs, tags: tags }); }
     catch (e) {
       emitObs("cache.backend.failed", { namespace: namespace, op: "set" });
       _backendFailedAudit("set", e);
@@ -670,6 +861,66 @@ function create(opts) {
     }
   }
 
+  async function bytes() {
+    _ensureOpen("bytes");
+    try {
+      if (typeof backend.bytes !== "function") return 0;
+      return await backend.bytes();
+    } catch (e) {
+      emitObs("cache.backend.failed", { namespace: namespace, op: "bytes" });
+      _backendFailedAudit("bytes", e);
+      throw e;
+    }
+  }
+
+  async function invalidateTag(tag, callerOpts) {
+    _ensureOpen("invalidateTag");
+    if (typeof tag !== "string" || tag.length === 0) {
+      throw _err("BAD_OPT", "cache.invalidateTag: tag must be a non-empty string");
+    }
+    if (typeof backend.invalidateTag !== "function") {
+      throw _err("NOT_SUPPORTED",
+        "cache.invalidateTag: backend '" + (backend.name || "custom") +
+        "' does not support tag invalidation. Tags are memory-backend only " +
+        "in this release; the cluster backend gains tag support alongside " +
+        "the distributed-invalidation slice.");
+    }
+    var purged;
+    try { purged = await backend.invalidateTag(tag); }
+    catch (e) {
+      emitObs("cache.backend.failed", { namespace: namespace, op: "invalidateTag" });
+      _backendFailedAudit("invalidateTag", e);
+      throw e;
+    }
+    emitObs("cache.tag.invalidated", { namespace: namespace, tag: tag });
+    if (auditClear && purged > 0) {
+      emitAudit("cache.tag.invalidated", {
+        actor:    _actor(callerOpts),
+        resource: { kind: "cache.tag", id: namespace + ":" + tag },
+        outcome:  "success",
+        metadata: { tag: tag, itemCount: purged },
+      });
+    }
+    // Drop in-flight wrap promises whose key WOULD have just been
+    // invalidated. We don't track per-key tags inflight, so a coarse
+    // drop matches clear()'s safer-than-stale posture.
+    inflight.clear();
+    swrInflight.clear();
+    return purged;
+  }
+
+  async function getTags(key) {
+    _ensureOpen("getTags");
+    _validateKey(key, "cache.getTags");
+    if (typeof backend.getTags !== "function") return null;
+    try { return await backend.getTags(key); }
+    catch (e) {
+      emitObs("cache.backend.failed", { namespace: namespace, op: "getTags" });
+      _backendFailedAudit("getTags", e);
+      throw e;
+    }
+  }
+
   function _backgroundRefresh(key, fn, ttlMs) {
     if (swrInflight.has(key)) return;     // already refreshing
     var p = (async function () {
@@ -710,7 +961,7 @@ function create(opts) {
     }
     // Backend write — failure surfaces via observability + audit but
     // doesn't bubble (caller already has the computed value).
-    backend.set(key, value, expiresAt).catch(function (e) {
+    backend.set(key, value, expiresAt, { ttlMs: ttlMs }).catch(function (e) {
       emitObs("cache.backend.failed", { namespace: namespace, op: "set" });
       _backendFailedAudit("set", e);
     });
@@ -765,7 +1016,7 @@ function create(opts) {
           _writeWithSwr(key, computed, ttlMs);
         } else {
           var expiresAt = (ttlMs === Infinity) ? Infinity : (clock() + ttlMs);
-          try { await backend.set(key, computed, expiresAt); }
+          try { await backend.set(key, computed, expiresAt, { ttlMs: ttlMs }); }
           catch (e) {
             emitObs("cache.backend.failed", { namespace: namespace, op: "set" });
             _backendFailedAudit("set", e);
@@ -803,7 +1054,10 @@ function create(opts) {
     has:                    has,
     clear:                  clear,
     size:                   size,
+    bytes:                  bytes,
     wrap:                   wrap,
+    invalidateTag:          invalidateTag,
+    getTags:                getTags,
     close:                  close,
     namespace:              namespace,
     // Test hooks

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blamejs/core",
-  "version": "0.4.10",
+  "version": "0.4.11",
   "description": "The Node framework that owns its stack.",
   "license": "Apache-2.0",
   "author": "blamejs contributors",