layercache 1.2.1 → 1.2.3

package/dist/index.cjs

@@ -400,11 +400,13 @@ var CircuitBreakerManager = class {
 
 // src/internal/FetchRateLimiter.ts
 var FetchRateLimiter = class {
-  active = 0;
-  queue = [];
-  startedAt = [];
+  buckets = /* @__PURE__ */ new Map();
+  queuesByBucket = /* @__PURE__ */ new Map();
+  pendingBuckets = /* @__PURE__ */ new Set();
+  fetcherBuckets = /* @__PURE__ */ new WeakMap();
+  nextFetcherBucketId = 0;
   drainTimer;
-  async schedule(options, task) {
+  async schedule(options, context, task) {
     if (!options) {
       return task();
     }
@@ -412,8 +414,18 @@ var FetchRateLimiter = class {
     if (!normalized) {
       return task();
     }
-    return new Promise((resolve, reject) => {
-      this.queue.push({ options: normalized, task, resolve, reject });
+    return new Promise((resolve2, reject) => {
+      const bucketKey = this.resolveBucketKey(normalized, context);
+      const queue = this.queuesByBucket.get(bucketKey) ?? [];
+      queue.push({
+        bucketKey,
+        options: normalized,
+        task,
+        resolve: resolve2,
+        reject
+      });
+      this.queuesByBucket.set(bucketKey, queue);
+      this.pendingBuckets.add(bucketKey);
       this.drain();
     });
   }
@@ -427,63 +439,159 @@ var FetchRateLimiter = class {
     return {
       maxConcurrent,
       intervalMs,
-      maxPerInterval
+      maxPerInterval,
+      scope: options.scope ?? "global",
+      bucketKey: options.bucketKey
     };
   }
+  resolveBucketKey(options, context) {
+    if (options.bucketKey) {
+      return `custom:${options.bucketKey}`;
+    }
+    if (options.scope === "key") {
+      return `key:${context.key}`;
+    }
+    if (options.scope === "fetcher") {
+      const existing = this.fetcherBuckets.get(context.fetcher);
+      if (existing) {
+        return existing;
+      }
+      const bucket = `fetcher:${this.nextFetcherBucketId}`;
+      this.nextFetcherBucketId += 1;
+      this.fetcherBuckets.set(context.fetcher, bucket);
+      return bucket;
+    }
+    return "global";
+  }
   drain() {
     if (this.drainTimer) {
       clearTimeout(this.drainTimer);
       this.drainTimer = void 0;
     }
-    while (this.queue.length > 0) {
-      const next = this.queue[0];
-      if (!next) {
-        return;
+    while (this.pendingBuckets.size > 0) {
+      let nextBucketKey;
+      let nextWaitMs = Number.POSITIVE_INFINITY;
+      for (const bucketKey of this.pendingBuckets) {
+        const queue2 = this.queuesByBucket.get(bucketKey);
+        if (!queue2 || queue2.length === 0) {
+          this.pendingBuckets.delete(bucketKey);
+          this.queuesByBucket.delete(bucketKey);
+          continue;
+        }
+        const next2 = queue2[0];
+        if (!next2) {
+          this.pendingBuckets.delete(bucketKey);
+          this.queuesByBucket.delete(bucketKey);
+          continue;
+        }
+        const waitMs = this.waitTime(bucketKey, next2.options);
+        if (waitMs <= 0) {
+          nextBucketKey = bucketKey;
+          break;
+        }
+        nextWaitMs = Math.min(nextWaitMs, waitMs);
       }
-      const waitMs = this.waitTime(next.options);
-      if (waitMs > 0) {
-        this.drainTimer = setTimeout(() => {
-          this.drainTimer = void 0;
-          this.drain();
-        }, waitMs);
-        this.drainTimer.unref?.();
+      if (!nextBucketKey) {
+        if (Number.isFinite(nextWaitMs)) {
+          this.drainTimer = setTimeout(() => {
+            this.drainTimer = void 0;
+            this.drain();
+          }, nextWaitMs);
+          this.drainTimer.unref?.();
+        }
         return;
       }
-      this.queue.shift();
-      this.active += 1;
-      this.startedAt.push(Date.now());
+      const queue = this.queuesByBucket.get(nextBucketKey);
+      const next = queue?.shift();
+      if (!next) {
+        this.pendingBuckets.delete(nextBucketKey);
+        this.queuesByBucket.delete(nextBucketKey);
+        continue;
+      }
+      if (!queue || queue.length === 0) {
+        this.pendingBuckets.delete(nextBucketKey);
+        this.queuesByBucket.delete(nextBucketKey);
+      }
+      const bucket = this.bucketState(next.bucketKey);
+      if (bucket.cleanupTimer) {
+        clearTimeout(bucket.cleanupTimer);
+        bucket.cleanupTimer = void 0;
+      }
+      bucket.active += 1;
+      if (next.options.intervalMs && next.options.maxPerInterval) {
+        bucket.startedAt.push(Date.now());
+      }
       void next.task().then(next.resolve, next.reject).finally(() => {
-        this.active -= 1;
+        bucket.active -= 1;
+        if ((this.queuesByBucket.get(next.bucketKey)?.length ?? 0) > 0) {
+          this.pendingBuckets.add(next.bucketKey);
+        }
+        this.cleanupBucket(next.bucketKey, bucket, next.options.intervalMs);
         this.drain();
       });
     }
   }
-  waitTime(options) {
+  waitTime(bucketKey, options) {
+    const bucket = this.bucketState(bucketKey);
     const now = Date.now();
-    if (options.maxConcurrent && this.active >= options.maxConcurrent) {
+    if (options.maxConcurrent && bucket.active >= options.maxConcurrent) {
       return 1;
     }
     if (!options.intervalMs || !options.maxPerInterval) {
       return 0;
     }
-    this.prune(now, options.intervalMs);
-    if (this.startedAt.length < options.maxPerInterval) {
+    this.prune(bucket, now, options.intervalMs);
+    if (bucket.startedAt.length < options.maxPerInterval) {
       return 0;
     }
-    const oldest = this.startedAt[0];
+    const oldest = bucket.startedAt[0];
     if (!oldest) {
       return 0;
     }
     return Math.max(1, options.intervalMs - (now - oldest));
   }
-  prune(now, intervalMs) {
-    while (this.startedAt.length > 0) {
-      const startedAt = this.startedAt[0];
+  prune(bucket, now, intervalMs) {
+    while (bucket.startedAt.length > 0) {
+      const startedAt = bucket.startedAt[0];
       if (startedAt === void 0 || now - startedAt < intervalMs) {
         break;
       }
-      this.startedAt.shift();
+      bucket.startedAt.shift();
+    }
+  }
+  bucketState(bucketKey) {
+    const existing = this.buckets.get(bucketKey);
+    if (existing) {
+      return existing;
     }
+    const bucket = { active: 0, startedAt: [] };
+    this.buckets.set(bucketKey, bucket);
+    return bucket;
+  }
+  cleanupBucket(bucketKey, bucket, intervalMs) {
+    const queued = this.queuesByBucket.get(bucketKey)?.length ?? 0;
+    if (queued === 0 && bucket.active === 0 && bucket.startedAt.length === 0) {
+      this.buckets.delete(bucketKey);
+      this.queuesByBucket.delete(bucketKey);
+      this.pendingBuckets.delete(bucketKey);
+      return;
+    }
+    if (!intervalMs || bucket.active > 0 || queued > 0) {
+      return;
+    }
+    if (bucket.cleanupTimer) {
+      clearTimeout(bucket.cleanupTimer);
+    }
+    bucket.cleanupTimer = setTimeout(() => {
+      bucket.cleanupTimer = void 0;
+      this.prune(bucket, Date.now(), intervalMs);
+      if (bucket.active === 0 && bucket.startedAt.length === 0 && (this.queuesByBucket.get(bucketKey)?.length ?? 0) === 0) {
+        this.buckets.delete(bucketKey);
+        this.queuesByBucket.delete(bucketKey);
+        this.pendingBuckets.delete(bucketKey);
+      }
+    }, intervalMs);
+    bucket.cleanupTimer.unref?.();
   }
 };
 
@@ -563,7 +671,30 @@ var MetricsCollector = class {
 
 // src/internal/StoredValue.ts
 function isStoredValueEnvelope(value) {
-  return typeof value === "object" && value !== null && "__layercache" in value && value.__layercache === 1 && "kind" in value;
+  if (typeof value !== "object" || value === null) {
+    return false;
+  }
+  const v = value;
+  if (v.__layercache !== 1) {
+    return false;
+  }
+  if (v.kind !== "value" && v.kind !== "empty") {
+    return false;
+  }
+  if (v.freshUntil !== null && typeof v.freshUntil !== "number") {
+    return false;
+  }
+  if (v.staleUntil !== null && typeof v.staleUntil !== "number") {
+    return false;
+  }
+  if (v.errorUntil !== null && typeof v.errorUntil !== "number") {
+    return false;
+  }
+  const maxTimestamp = Date.now() + 10 * 365 * 24 * 60 * 60 * 1e3;
+  if (typeof v.freshUntil === "number" && v.freshUntil > maxTimestamp) {
+    return false;
+  }
+  return true;
 }
 function createStoredValueEnvelope(options) {
   const now = options.now ?? Date.now();
@@ -828,15 +959,17 @@ var TagIndex = class {
   keyToTags = /* @__PURE__ */ new Map();
   knownKeys = /* @__PURE__ */ new Set();
   maxKnownKeys;
+  nextNodeId = 1;
+  root = this.createTrieNode();
   constructor(options = {}) {
-    this.maxKnownKeys = options.maxKnownKeys;
+    this.maxKnownKeys = options.maxKnownKeys ?? 1e5;
   }
   async touch(key) {
-    this.knownKeys.add(key);
+    this.insertKnownKey(key);
     this.pruneKnownKeysIfNeeded();
   }
   async track(key, tags) {
-    this.knownKeys.add(key);
+    this.insertKnownKey(key);
     this.pruneKnownKeysIfNeeded();
     if (tags.length === 0) {
       return;
@@ -862,18 +995,104 @@ var TagIndex = class {
     return [...this.tagToKeys.get(tag) ?? /* @__PURE__ */ new Set()];
   }
   async keysForPrefix(prefix) {
-    return [...this.knownKeys].filter((key) => key.startsWith(prefix));
+    const node = this.findNode(prefix);
+    if (!node) {
+      return [];
+    }
+    const matches = [];
+    this.collectFromNode(node, prefix, matches);
+    return matches;
   }
   async tagsForKey(key) {
     return [...this.keyToTags.get(key) ?? /* @__PURE__ */ new Set()];
   }
   async matchPattern(pattern) {
-    return [...this.knownKeys].filter((key) => PatternMatcher.matches(pattern, key));
+    const matches = /* @__PURE__ */ new Set();
+    this.collectPatternMatches(this.root, "", pattern, 0, matches, /* @__PURE__ */ new Set());
+    return [...matches];
   }
   async clear() {
     this.tagToKeys.clear();
     this.keyToTags.clear();
     this.knownKeys.clear();
+    this.root.children.clear();
+    this.root.terminal = false;
+    this.nextNodeId = this.root.id + 1;
+  }
+  createTrieNode() {
+    return {
+      id: this.nextNodeId++,
+      terminal: false,
+      children: /* @__PURE__ */ new Map()
+    };
+  }
+  insertKnownKey(key) {
+    if (this.knownKeys.has(key)) {
+      return;
+    }
+    this.knownKeys.add(key);
+    let node = this.root;
+    for (const character of key) {
+      let child = node.children.get(character);
+      if (!child) {
+        child = this.createTrieNode();
+        node.children.set(character, child);
+      }
+      node = child;
+    }
+    node.terminal = true;
+  }
+  findNode(prefix) {
+    let node = this.root;
+    for (const character of prefix) {
+      node = node.children.get(character);
+      if (!node) {
+        return void 0;
+      }
+    }
+    return node;
+  }
+  collectFromNode(node, prefix, matches) {
+    if (node.terminal) {
+      matches.push(prefix);
+    }
+    for (const [character, child] of node.children) {
+      this.collectFromNode(child, `${prefix}${character}`, matches);
+    }
+  }
+  collectPatternMatches(node, prefix, pattern, patternIndex, matches, visited) {
+    const stateKey = `${node.id}:${patternIndex}`;
+    if (visited.has(stateKey)) {
+      return;
+    }
+    visited.add(stateKey);
+    if (patternIndex === pattern.length) {
+      if (node.terminal) {
+        matches.add(prefix);
+      }
+      return;
+    }
+    const patternChar = pattern[patternIndex];
+    if (patternChar === void 0) {
+      return;
+    }
+    if (patternChar === "*") {
+      this.collectPatternMatches(node, prefix, pattern, patternIndex + 1, matches, visited);
+      for (const [character, child2] of node.children) {
+        this.collectPatternMatches(child2, `${prefix}${character}`, pattern, patternIndex, matches, visited);
+      }
+      return;
+    }
+    if (patternChar === "?") {
+      for (const [character, child2] of node.children) {
+        this.collectPatternMatches(child2, `${prefix}${character}`, pattern, patternIndex + 1, matches, visited);
+      }
+      return;
+    }
+    const child = node.children.get(patternChar);
+    if (child) {
+      this.collectPatternMatches(child, `${prefix}${patternChar}`, pattern, patternIndex + 1, matches, visited);
+    }
   }
   pruneKnownKeysIfNeeded() {
     if (this.maxKnownKeys === void 0 || this.knownKeys.size <= this.maxKnownKeys) {
@@ -890,7 +1109,7 @@ var TagIndex = class {
     }
   }
   removeKey(key) {
-    this.knownKeys.delete(key);
+    this.removeKnownKey(key);
     const tags = this.keyToTags.get(key);
     if (!tags) {
       return;
@@ -907,7 +1126,70 @@ var TagIndex = class {
     }
     this.keyToTags.delete(key);
   }
+  removeKnownKey(key) {
+    if (!this.knownKeys.delete(key)) {
+      return;
+    }
+    const path = [];
+    let node = this.root;
+    for (const character of key) {
+      const child = node.children.get(character);
+      if (!child) {
+        return;
+      }
+      path.push([node, character]);
+      node = child;
+    }
+    node.terminal = false;
+    for (let index = path.length - 1; index >= 0; index -= 1) {
+      const entry = path[index];
+      if (!entry) {
+        continue;
+      }
+      const [parent, character] = entry;
+      const child = parent.children.get(character);
+      if (!child || child.terminal || child.children.size > 0) {
+        break;
+      }
+      parent.children.delete(character);
+    }
+  }
+};
+
+// src/serialization/JsonSerializer.ts
+var DANGEROUS_JSON_KEYS = /* @__PURE__ */ new Set(["__proto__", "prototype", "constructor"]);
+var JsonSerializer = class {
+  serialize(value) {
+    return JSON.stringify(value);
+  }
+  deserialize(payload) {
+    const normalized = Buffer.isBuffer(payload) ? payload.toString("utf8") : payload;
+    return sanitizeJsonValue(JSON.parse(normalized), 0);
+  }
 };
+var MAX_SANITIZE_DEPTH = 200;
+function sanitizeJsonValue(value, depth) {
+  if (depth > MAX_SANITIZE_DEPTH) {
+    return value;
+  }
+  if (Array.isArray(value)) {
+    return value.map((entry) => sanitizeJsonValue(entry, depth + 1));
+  }
+  if (!isPlainObject(value)) {
+    return value;
+  }
+  const sanitized = {};
+  for (const [key, entry] of Object.entries(value)) {
+    if (DANGEROUS_JSON_KEYS.has(key)) {
+      continue;
+    }
+    sanitized[key] = sanitizeJsonValue(entry, depth + 1);
+  }
+  return sanitized;
+}
+function isPlainObject(value) {
+  return Object.prototype.toString.call(value) === "[object Object]";
+}
 
 // src/stampede/StampedeGuard.ts
 var import_async_mutex2 = require("async-mutex");
@@ -919,7 +1201,8 @@ var StampedeGuard = class {
       return await entry.mutex.runExclusive(task);
     } finally {
       entry.references -= 1;
-      if (entry.references === 0 && !entry.mutex.isLocked()) {
+      const current = this.mutexes.get(key);
+      if (current === entry && entry.references === 0 && !entry.mutex.isLocked()) {
         this.mutexes.delete(key);
       }
     }
@@ -949,8 +1232,10 @@ var CacheMissError = class extends Error {
 var DEFAULT_SINGLE_FLIGHT_LEASE_MS = 3e4;
 var DEFAULT_SINGLE_FLIGHT_TIMEOUT_MS = 5e3;
 var DEFAULT_SINGLE_FLIGHT_POLL_MS = 50;
+var DEFAULT_BACKGROUND_REFRESH_TIMEOUT_MS = 3e4;
 var MAX_CACHE_KEY_LENGTH = 1024;
 var DEFAULT_MAX_PROFILE_ENTRIES = 1e5;
+var DANGEROUS_OBJECT_KEYS = /* @__PURE__ */ new Set(["__proto__", "prototype", "constructor"]);
 var DebugLogger = class {
   enabled;
   constructor(enabled) {
@@ -997,6 +1282,21 @@ var CacheStack = class extends import_node_events.EventEmitter {
     const debugEnv = process.env.DEBUG?.split(",").includes("layercache:debug") ?? false;
     this.logger = typeof options.logger === "object" ? options.logger : new DebugLogger(Boolean(options.logger) || debugEnv);
     this.tagIndex = options.tagIndex ?? new TagIndex();
+    if (!options.tagIndex && layers.some((layer) => layer.isLocal === false)) {
+      this.logger.warn?.(
+        "Using the default in-memory TagIndex with a shared cache layer only tracks keys seen by this process. Use RedisTagIndex for cross-instance tag invalidation."
+      );
+    }
+    if (!options.tagIndex && layers.some((layer) => layer.isLocal === false && !layer.keys)) {
+      this.logger.warn?.(
+        "Using the default in-memory TagIndex with a shared cache layer that does not implement keys() can leave invalidateByPattern() and invalidateByPrefix() incomplete after restarts. Use RedisTagIndex or implement keys() on the shared layer."
+      );
+    }
+    if (options.invalidationBus && options.broadcastL1Invalidation === void 0 && options.publishSetInvalidation === void 0) {
+      this.logger.warn?.(
+        "broadcastL1Invalidation defaults to false when an invalidation bus is configured; opt in explicitly if write-triggered L1 invalidation is desired."
+      );
+    }
     this.initializeWriteBehind(options.writeBehind);
     this.startup = this.initialize();
   }
@@ -1010,6 +1310,7 @@ var CacheStack = class extends import_node_events.EventEmitter {
   logger;
   tagIndex;
   fetchRateLimiter = new FetchRateLimiter();
+  snapshotSerializer = new JsonSerializer();
   backgroundRefreshes = /* @__PURE__ */ new Map();
   layerDegradedUntil = /* @__PURE__ */ new Map();
   ttlResolver;
@@ -1018,6 +1319,7 @@ var CacheStack = class extends import_node_events.EventEmitter {
   writeBehindQueue = [];
   writeBehindTimer;
   writeBehindFlushPromise;
+  generationCleanupPromise;
   isDisconnecting = false;
   disconnectPromise;
   /**
@@ -1030,6 +1332,9 @@ var CacheStack = class extends import_node_events.EventEmitter {
     const normalizedKey = this.qualifyKey(this.validateCacheKey(key));
     this.validateWriteOptions(options);
     await this.awaitStartup("get");
+    return this.getPrepared(normalizedKey, fetcher, options);
+  }
+  async getPrepared(normalizedKey, fetcher, options) {
     const hit = await this.readFromLayers(normalizedKey, options, "allow-stale");
     if (hit.found) {
       this.ttlResolver.recordAccess(normalizedKey);
@@ -1107,6 +1412,7 @@ var CacheStack = class extends import_node_events.EventEmitter {
             return true;
           }
         } catch {
+          await this.reportRecoverableLayerFailure(layer, "has", new Error(`has() failed for layer "${layer.name}"`));
         }
       } else {
         try {
@@ -1114,7 +1420,8 @@ var CacheStack = class extends import_node_events.EventEmitter {
           if (value !== null) {
             return true;
           }
-        } catch {
+        } catch (error) {
+          await this.reportRecoverableLayerFailure(layer, "has", error);
         }
       }
     }
@@ -1206,13 +1513,14 @@ var CacheStack = class extends import_node_events.EventEmitter {
     normalizedEntries.forEach((entry) => this.validateWriteOptions(entry.options));
     const canFastPath = normalizedEntries.every((entry) => entry.fetch === void 0 && entry.options === void 0);
     if (!canFastPath) {
+      await this.awaitStartup("mget");
       const pendingReads = /* @__PURE__ */ new Map();
       return Promise.all(
         normalizedEntries.map((entry) => {
           const optionsSignature = this.serializeOptions(entry.options);
           const existing = pendingReads.get(entry.key);
           if (!existing) {
-            const promise = this.get(entry.key, entry.fetch, entry.options);
+            const promise = this.getPrepared(entry.key, entry.fetch, entry.options);
             pendingReads.set(entry.key, {
               promise,
               fetch: entry.fetch,
@@ -1351,14 +1659,14 @@ var CacheStack = class extends import_node_events.EventEmitter {
   }
   async invalidateByPattern(pattern) {
     await this.awaitStartup("invalidateByPattern");
-    const keys = await this.tagIndex.matchPattern(this.qualifyPattern(pattern));
+    const keys = await this.collectKeysMatchingPattern(this.qualifyPattern(pattern));
     await this.deleteKeys(keys);
     await this.publishInvalidation({ scope: "keys", keys, sourceId: this.instanceId, operation: "invalidate" });
   }
   async invalidateByPrefix(prefix) {
     await this.awaitStartup("invalidateByPrefix");
     const qualifiedPrefix = this.qualifyKey(this.validateCacheKey(prefix));
-    const keys = this.tagIndex.keysForPrefix ? await this.tagIndex.keysForPrefix(qualifiedPrefix) : await this.tagIndex.matchPattern(`${qualifiedPrefix}*`);
+    const keys = await this.collectKeysWithPrefix(qualifiedPrefix);
     await this.deleteKeys(keys);
     await this.publishInvalidation({ scope: "keys", keys, sourceId: this.instanceId, operation: "invalidate" });
   }
@@ -1408,9 +1716,18 @@ var CacheStack = class extends import_node_events.EventEmitter {
       })
     );
   }
+  /**
+   * Rotates the active generation prefix used for all future cache keys.
+   * Previous-generation keys remain in the underlying layers until they expire,
+   * unless `generationCleanup` is enabled to prune them in the background.
+   */
   bumpGeneration(nextGeneration) {
     const current = this.currentGeneration ?? 0;
+    const previousGeneration = this.currentGeneration;
     this.currentGeneration = nextGeneration ?? current + 1;
+    if (previousGeneration !== void 0 && previousGeneration !== this.currentGeneration && this.shouldCleanupGenerations()) {
+      this.scheduleGenerationCleanup(previousGeneration);
+    }
     return this.currentGeneration;
   }
   /**
@@ -1494,27 +1811,28 @@ var CacheStack = class extends import_node_events.EventEmitter {
     this.assertActive("persistToFile");
     const snapshot = await this.exportState();
     const { promises: fs2 } = await import("fs");
-    await fs2.writeFile(filePath, JSON.stringify(snapshot, null, 2), "utf8");
+    await fs2.writeFile(await this.validateSnapshotFilePath(filePath), JSON.stringify(snapshot, null, 2), "utf8");
   }
   async restoreFromFile(filePath) {
     this.assertActive("restoreFromFile");
     const { promises: fs2 } = await import("fs");
-    const raw = await fs2.readFile(filePath, "utf8");
+    const raw = await fs2.readFile(await this.validateSnapshotFilePath(filePath), "utf8");
     let parsed;
     try {
-      parsed = JSON.parse(raw, (_key, value) => {
-        if (value !== null && typeof value === "object" && !Array.isArray(value)) {
-          return Object.assign(/* @__PURE__ */ Object.create(null), value);
-        }
-        return value;
-      });
+      parsed = JSON.parse(raw);
     } catch (cause) {
       throw new Error(`Invalid snapshot file: could not parse JSON (${this.formatError(cause)})`);
     }
     if (!this.isCacheSnapshotEntries(parsed)) {
       throw new Error("Invalid snapshot file: expected an array of { key: string, value, ttl? } entries");
     }
-    await this.importState(parsed);
+    await this.importState(
+      parsed.map((entry) => ({
+        key: entry.key,
+        value: this.sanitizeSnapshotValue(entry.value),
+        ttl: entry.ttl
+      }))
+    );
   }
   async disconnect() {
     if (!this.disconnectPromise) {
@@ -1523,6 +1841,7 @@ var CacheStack = class extends import_node_events.EventEmitter {
         await this.startup;
         await this.unsubscribeInvalidation?.();
         await this.flushWriteBehindQueue();
+        await this.generationCleanupPromise;
         await Promise.allSettled([...this.backgroundRefreshes.values()]);
         if (this.writeBehindTimer) {
           clearInterval(this.writeBehindTimer);
@@ -1590,6 +1909,7 @@ var CacheStack = class extends import_node_events.EventEmitter {
     try {
       fetched = await this.fetchRateLimiter.schedule(
         options?.fetcherRateLimit ?? this.options.fetcherRateLimit,
+        { key, fetcher },
         fetcher
       );
       this.circuitBreakerManager.recordSuccess(key);
@@ -1605,8 +1925,14 @@ var CacheStack = class extends import_node_events.EventEmitter {
       await this.storeEntry(key, "empty", null, options);
       return null;
     }
-    if (options?.shouldCache && !options.shouldCache(fetched)) {
-      return fetched;
+    if (options?.shouldCache) {
+      try {
+        if (!options.shouldCache(fetched)) {
+          return fetched;
+        }
+      } catch (error) {
+        this.logger.warn?.("shouldCache-error", { key, error: this.formatError(error) });
+      }
     }
     await this.storeEntry(key, "value", fetched, options);
     return fetched;
@@ -1833,7 +2159,7 @@ var CacheStack = class extends import_node_events.EventEmitter {
     const refresh = (async () => {
       this.metricsCollector.increment("refreshes");
       try {
-        await this.fetchWithGuards(key, fetcher, options);
+        await this.runBackgroundRefresh(key, fetcher, options);
       } catch (error) {
         this.metricsCollector.increment("refreshErrors");
         this.logger.debug?.("refresh-error", { key, error: this.formatError(error) });
@@ -1843,11 +2169,22 @@ var CacheStack = class extends import_node_events.EventEmitter {
     })();
     this.backgroundRefreshes.set(key, refresh);
   }
+  async runBackgroundRefresh(key, fetcher, options) {
+    const timeoutMs = this.options.backgroundRefreshTimeoutMs ?? DEFAULT_BACKGROUND_REFRESH_TIMEOUT_MS;
+    await this.fetchWithGuards(
+      key,
+      () => this.withTimeout(fetcher(), timeoutMs, () => {
+        return new Error(`Background refresh timed out after ${timeoutMs}ms for key "${key}".`);
+      }),
+      options
+    );
+  }
   resolveSingleFlightOptions() {
     return {
       leaseMs: this.options.singleFlightLeaseMs ?? DEFAULT_SINGLE_FLIGHT_LEASE_MS,
       waitTimeoutMs: this.options.singleFlightTimeoutMs ?? DEFAULT_SINGLE_FLIGHT_TIMEOUT_MS,
-      pollIntervalMs: this.options.singleFlightPollMs ?? DEFAULT_SINGLE_FLIGHT_POLL_MS
+      pollIntervalMs: this.options.singleFlightPollMs ?? DEFAULT_SINGLE_FLIGHT_POLL_MS,
+      renewIntervalMs: this.options.singleFlightRenewIntervalMs
     };
   }
   async deleteKeys(keys) {
@@ -1907,10 +2244,122 @@ var CacheStack = class extends import_node_events.EventEmitter {
     return String(error);
   }
   sleep(ms) {
-    return new Promise((resolve) => setTimeout(resolve, ms));
+    return new Promise((resolve2) => setTimeout(resolve2, ms));
+  }
+  async withTimeout(promise, timeoutMs, onTimeout) {
+    if (timeoutMs <= 0) {
+      return promise;
+    }
+    let timer;
+    const observedPromise = promise.then(
+      (value) => ({ kind: "value", value }),
+      (error) => ({ kind: "error", error })
+    );
+    try {
+      const result = await Promise.race([
+        observedPromise,
+        new Promise((_, reject) => {
+          timer = setTimeout(() => reject(onTimeout()), timeoutMs);
+          timer.unref?.();
+        })
+      ]);
+      if (result && typeof result === "object" && "kind" in result) {
+        if (result.kind === "error") {
+          throw result.error;
+        }
+        return result.value;
+      }
+      return result;
+    } finally {
+      if (timer) {
+        clearTimeout(timer);
+      }
+    }
   }
   shouldBroadcastL1Invalidation() {
-    return this.options.broadcastL1Invalidation ?? this.options.publishSetInvalidation ?? true;
+    return this.options.broadcastL1Invalidation ?? this.options.publishSetInvalidation ?? false;
+  }
+  async collectKeysWithPrefix(prefix) {
+    const matches = new Set(
+      this.tagIndex.keysForPrefix ? await this.tagIndex.keysForPrefix(prefix) : await this.tagIndex.matchPattern(`${prefix}*`)
+    );
+    await Promise.all(
+      this.layers.map(async (layer) => {
+        if (!layer.keys || this.shouldSkipLayer(layer)) {
+          return;
+        }
+        try {
+          const keys = await layer.keys();
+          for (const key of keys) {
+            if (key.startsWith(prefix)) {
+              matches.add(key);
+            }
+          }
+        } catch (error) {
+          await this.handleLayerFailure(layer, "invalidate-prefix-scan", error);
+        }
+      })
+    );
+    return [...matches];
+  }
+  async collectKeysMatchingPattern(pattern) {
+    const matches = new Set(await this.tagIndex.matchPattern(pattern));
+    await Promise.all(
+      this.layers.map(async (layer) => {
+        if (!layer.keys || this.shouldSkipLayer(layer)) {
+          return;
+        }
+        try {
+          const keys = await layer.keys();
+          for (const key of keys) {
+            if (PatternMatcher.matches(pattern, key)) {
+              matches.add(key);
+            }
+          }
+        } catch (error) {
+          await this.handleLayerFailure(layer, "invalidate-pattern-scan", error);
+        }
+      })
+    );
+    return [...matches];
+  }
+  shouldCleanupGenerations() {
+    return Boolean(this.options.generationCleanup);
+  }
+  generationCleanupBatchSize() {
+    const configured = typeof this.options.generationCleanup === "object" ? this.options.generationCleanup.batchSize : void 0;
+    return configured ?? 500;
+  }
+  scheduleGenerationCleanup(generation) {
+    const task = (this.generationCleanupPromise ?? Promise.resolve()).then(() => this.cleanupGeneration(generation)).catch((error) => {
+      this.logger.warn?.("generation-cleanup-error", {
+        generation,
+        error: this.formatError(error)
+      });
+    });
+    this.generationCleanupPromise = task.finally(() => {
+      if (this.generationCleanupPromise === task) {
+        this.generationCleanupPromise = void 0;
+      }
+    });
+  }
+  async cleanupGeneration(generation) {
+    const prefix = `v${generation}:`;
+    const keys = await this.collectKeysWithPrefix(prefix);
+    if (keys.length === 0) {
+      return;
+    }
+    const batchSize = this.generationCleanupBatchSize();
+    for (let index = 0; index < keys.length; index += batchSize) {
+      const batch = keys.slice(index, index + batchSize);
+      await this.deleteKeys(batch);
+      await this.publishInvalidation({
+        scope: "keys",
+        keys: batch,
+        sourceId: this.instanceId,
+        operation: "invalidate"
+      });
+    }
   }
   initializeWriteBehind(options) {
     if (this.options.writeStrategy !== "write-behind") {
@@ -1948,7 +2397,17 @@ var CacheStack = class extends import_node_events.EventEmitter {
     const batchSize = this.options.writeBehind?.batchSize ?? 100;
     const batch = this.writeBehindQueue.splice(0, batchSize);
     this.writeBehindFlushPromise = (async () => {
-      await Promise.allSettled(batch.map((operation) => operation()));
+      const results = await Promise.allSettled(batch.map((operation) => operation()));
+      const failures = results.filter((result) => result.status === "rejected");
+      if (failures.length > 0) {
+        this.metricsCollector.increment("writeFailures", failures.length);
+        this.logger.error?.("write-behind-flush-failure", {
+          failed: failures.length,
+          total: batch.length,
+          errors: failures.map((failure) => this.formatError(failure.reason))
+        });
+        this.emitError("write-behind", { failed: failures.length, total: batch.length });
+      }
     })();
     await this.writeBehindFlushPromise;
     this.writeBehindFlushPromise = void 0;
@@ -2052,8 +2511,14 @@ var CacheStack = class extends import_node_events.EventEmitter {
     this.validatePositiveNumber("singleFlightLeaseMs", this.options.singleFlightLeaseMs);
     this.validatePositiveNumber("singleFlightTimeoutMs", this.options.singleFlightTimeoutMs);
     this.validatePositiveNumber("singleFlightPollMs", this.options.singleFlightPollMs);
+    this.validatePositiveNumber("singleFlightRenewIntervalMs", this.options.singleFlightRenewIntervalMs);
+    this.validatePositiveNumber("backgroundRefreshTimeoutMs", this.options.backgroundRefreshTimeoutMs);
+    this.validateRateLimitOptions("fetcherRateLimit", this.options.fetcherRateLimit);
     this.validateAdaptiveTtlOptions(this.options.adaptiveTtl);
     this.validateCircuitBreakerOptions(this.options.circuitBreaker);
+    if (typeof this.options.generationCleanup === "object") {
+      this.validatePositiveNumber("generationCleanup.batchSize", this.options.generationCleanup.batchSize);
+    }
     if (this.options.generation !== void 0) {
       this.validateNonNegativeNumber("generation", this.options.generation);
     }
@@ -2071,6 +2536,7 @@ var CacheStack = class extends import_node_events.EventEmitter {
     this.validateTtlPolicy("options.ttlPolicy", options.ttlPolicy);
     this.validateAdaptiveTtlOptions(options.adaptiveTtl);
     this.validateCircuitBreakerOptions(options.circuitBreaker);
+    this.validateRateLimitOptions("options.fetcherRateLimit", options.fetcherRateLimit);
   }
   validateLayerNumberOption(name, value) {
     if (value === void 0) {
@@ -2095,6 +2561,20 @@ var CacheStack = class extends import_node_events.EventEmitter {
       throw new Error(`${name} must be a positive finite number.`);
     }
   }
+  validateRateLimitOptions(name, options) {
+    if (!options) {
+      return;
+    }
+    this.validatePositiveNumber(`${name}.maxConcurrent`, options.maxConcurrent);
+    this.validatePositiveNumber(`${name}.intervalMs`, options.intervalMs);
+    this.validatePositiveNumber(`${name}.maxPerInterval`, options.maxPerInterval);
+    if (options.scope && !["global", "key", "fetcher"].includes(options.scope)) {
+      throw new Error(`${name}.scope must be one of "global", "key", or "fetcher".`);
+    }
+    if (options.bucketKey !== void 0 && options.bucketKey.length === 0) {
+      throw new Error(`${name}.bucketKey must not be empty.`);
+    }
+  }
   validateNonNegativeNumber(name, value) {
     if (!Number.isFinite(value) || value < 0) {
       throw new Error(`${name} must be a non-negative finite number.`);
@@ -2110,6 +2590,9 @@ var CacheStack = class extends import_node_events.EventEmitter {
     if (/[\u0000-\u001F\u007F]/.test(key)) {
       throw new Error("Cache key contains unsupported control characters.");
     }
+    if (/[\uD800-\uDFFF]/.test(key)) {
+      throw new Error("Cache key contains unsupported surrogate code points.");
+    }
     return key;
   }
   validateTtlPolicy(name, policy) {
@@ -2187,6 +2670,14 @@ var CacheStack = class extends import_node_events.EventEmitter {
     this.emitError(operation, { layer: layer.name, degraded: true, error: this.formatError(error) });
     return null;
   }
+  async reportRecoverableLayerFailure(layer, operation, error) {
+    if (this.isGracefulDegradationEnabled()) {
+      await this.handleLayerFailure(layer, operation, error);
+      return;
+    }
+    this.logger.warn?.("layer-operation-failed", { layer: layer.name, operation, error: this.formatError(error) });
+    this.emitError(operation, { layer: layer.name, degraded: false, error: this.formatError(error) });
+  }
   isGracefulDegradationEnabled() {
     return Boolean(this.options.gracefulDegradation);
   }
@@ -2210,10 +2701,16 @@ var CacheStack = class extends import_node_events.EventEmitter {
     }
   }
   serializeKeyPart(value) {
-    if (typeof value === "string" || typeof value === "number" || typeof value === "boolean") {
-      return String(value);
+    if (typeof value === "string") {
+      return `s:${value}`;
+    }
+    if (typeof value === "number") {
+      return `n:${value}`;
     }
-    return JSON.stringify(this.normalizeForSerialization(value));
+    if (typeof value === "boolean") {
+      return `b:${value}`;
+    }
+    return `j:${JSON.stringify(this.normalizeForSerialization(value))}`;
   }
   isCacheSnapshotEntries(value) {
     return Array.isArray(value) && value.every((entry) => {
@@ -2221,15 +2718,39 @@ var CacheStack = class extends import_node_events.EventEmitter {
         return false;
       }
       const candidate = entry;
-      return typeof candidate.key === "string";
+      return typeof candidate.key === "string" && (candidate.ttl === void 0 || typeof candidate.ttl === "number" && Number.isFinite(candidate.ttl) && candidate.ttl >= 0);
     });
   }
+  sanitizeSnapshotValue(value) {
+    return this.snapshotSerializer.deserialize(this.snapshotSerializer.serialize(value));
+  }
+  async validateSnapshotFilePath(filePath) {
+    if (filePath.length === 0) {
+      throw new Error("filePath must not be empty.");
+    }
+    if (filePath.includes("\0")) {
+      throw new Error("filePath must not contain null bytes.");
+    }
+    const path = await import("path");
+    const resolved = path.resolve(filePath);
+    const baseDir = this.options.snapshotBaseDir === false ? false : path.resolve(this.options.snapshotBaseDir ?? process.cwd());
+    if (baseDir !== false) {
+      const relative = path.relative(baseDir, resolved);
+      if (relative === ".." || relative.startsWith(`..${path.sep}`) || path.isAbsolute(relative)) {
+        throw new Error(`filePath is outside the allowed snapshot directory: ${baseDir}`);
+      }
+    }
+    return resolved;
+  }
   normalizeForSerialization(value) {
     if (Array.isArray(value)) {
       return value.map((entry) => this.normalizeForSerialization(entry));
     }
     if (value && typeof value === "object") {
       return Object.keys(value).sort().reduce((normalized, key) => {
+        if (DANGEROUS_OBJECT_KEYS.has(key)) {
+          return normalized;
+        }
         normalized[key] = this.normalizeForSerialization(value[key]);
         return normalized;
       }, {});
@@ -2323,19 +2844,21 @@ var RedisTagIndex = class {
   client;
   prefix;
   scanCount;
+  knownKeysShards;
   constructor(options) {
     this.client = options.client;
     this.prefix = options.prefix ?? "layercache:tag-index";
     this.scanCount = options.scanCount ?? 100;
+    this.knownKeysShards = normalizeKnownKeysShards(options.knownKeysShards);
   }
   async touch(key) {
-    await this.client.sadd(this.knownKeysKey(), key);
+    await this.client.sadd(this.knownKeysKeyFor(key), key);
   }
   async track(key, tags) {
     const keyTagsKey = this.keyTagsKey(key);
     const existingTags = await this.client.smembers(keyTagsKey);
     const pipeline = this.client.pipeline();
-    pipeline.sadd(this.knownKeysKey(), key);
+    pipeline.sadd(this.knownKeysKeyFor(key), key);
     for (const tag of existingTags) {
       pipeline.srem(this.tagKeysKey(tag), key);
     }
@@ -2352,7 +2875,7 @@ var RedisTagIndex = class {
     const keyTagsKey = this.keyTagsKey(key);
     const existingTags = await this.client.smembers(keyTagsKey);
     const pipeline = this.client.pipeline();
-    pipeline.srem(this.knownKeysKey(), key);
+    pipeline.srem(this.knownKeysKeyFor(key), key);
     pipeline.del(keyTagsKey);
     for (const tag of existingTags) {
       pipeline.srem(this.tagKeysKey(tag), key);
@@ -2364,12 +2887,14 @@ var RedisTagIndex = class {
   }
   async keysForPrefix(prefix) {
     const matches = [];
-    let cursor = "0";
-    do {
-      const [nextCursor, keys] = await this.client.sscan(this.knownKeysKey(), cursor, "COUNT", this.scanCount);
-      cursor = nextCursor;
-      matches.push(...keys.filter((key) => key.startsWith(prefix)));
-    } while (cursor !== "0");
+    for (const knownKeysKey of this.knownKeysKeys()) {
+      let cursor = "0";
+      do {
+        const [nextCursor, keys] = await this.client.sscan(knownKeysKey, cursor, "COUNT", this.scanCount);
+        cursor = nextCursor;
+        matches.push(...keys.filter((key) => key.startsWith(prefix)));
+      } while (cursor !== "0");
+    }
     return matches;
   }
   async tagsForKey(key) {
@@ -2377,19 +2902,21 @@ var RedisTagIndex = class {
   }
   async matchPattern(pattern) {
     const matches = [];
-    let cursor = "0";
-    do {
-      const [nextCursor, keys] = await this.client.sscan(
-        this.knownKeysKey(),
-        cursor,
-        "MATCH",
-        pattern,
-        "COUNT",
-        this.scanCount
-      );
-      cursor = nextCursor;
-      matches.push(...keys.filter((key) => PatternMatcher.matches(pattern, key)));
-    } while (cursor !== "0");
+    for (const knownKeysKey of this.knownKeysKeys()) {
+      let cursor = "0";
+      do {
+        const [nextCursor, keys] = await this.client.sscan(
+          knownKeysKey,
+          cursor,
+          "MATCH",
+          pattern,
+          "COUNT",
+          this.scanCount
+        );
+        cursor = nextCursor;
+        matches.push(...keys.filter((key) => PatternMatcher.matches(pattern, key)));
+      } while (cursor !== "0");
+    }
     return matches;
   }
   async clear() {
@@ -2410,8 +2937,17 @@ var RedisTagIndex = class {
     } while (cursor !== "0");
     return matches;
   }
-  knownKeysKey() {
-    return `${this.prefix}:keys`;
+  knownKeysKeyFor(key) {
+    if (this.knownKeysShards === 1) {
+      return `${this.prefix}:keys`;
+    }
+    return `${this.prefix}:keys:${simpleHash(key) % this.knownKeysShards}`;
+  }
+  knownKeysKeys() {
+    if (this.knownKeysShards === 1) {
+      return [`${this.prefix}:keys`];
+    }
+    return Array.from({ length: this.knownKeysShards }, (_, index) => `${this.prefix}:keys:${index}`);
   }
   keyTagsKey(key) {
     return `${this.prefix}:key:${encodeURIComponent(key)}`;
@@ -2420,6 +2956,22 @@ var RedisTagIndex = class {
     return `${this.prefix}:tag:${encodeURIComponent(tag)}`;
   }
 };
+function normalizeKnownKeysShards(value) {
+  if (value === void 0) {
+    return 1;
+  }
+  if (!Number.isInteger(value) || value <= 0) {
+    throw new Error("RedisTagIndex.knownKeysShards must be a positive integer.");
+  }
+  return value;
+}
+function simpleHash(value) {
+  let hash = 0;
+  for (let index = 0; index < value.length; index += 1) {
+    hash = hash * 31 + value.charCodeAt(index) >>> 0;
+  }
+  return hash;
+}
 
 // src/http/createCacheStatsHandler.ts
 function createCacheStatsHandler(cache) {
@@ -2459,7 +3011,7 @@ function createCachedMethodDecorator(options) {
 function createFastifyLayercachePlugin(cache, options = {}) {
   return async (fastify) => {
     fastify.decorate("cache", cache);
-    if (options.exposeStatsRoute !== false && fastify.get) {
+    if (options.exposeStatsRoute === true && fastify.get) {
       fastify.get(options.statsPath ?? "/cache/stats", async () => cache.getStats());
     }
   };
@@ -2475,7 +3027,8 @@ function createExpressCacheMiddleware(cache, options = {}) {
         next();
         return;
       }
-      const key = options.keyResolver ? options.keyResolver(req) : `${method}:${req.originalUrl ?? req.url ?? "/"}`;
+      const rawUrl = req.originalUrl ?? req.url ?? "/";
+      const key = options.keyResolver ? options.keyResolver(req) : `${method}:${normalizeUrl(rawUrl)}`;
       const cached = await cache.get(key, void 0, options);
       if (cached !== null) {
         res.setHeader?.("content-type", "application/json; charset=utf-8");
@@ -2491,7 +3044,12 @@ function createExpressCacheMiddleware(cache, options = {}) {
       if (originalJson) {
         res.json = (body) => {
           res.setHeader?.("x-cache", "MISS");
-          void cache.set(key, body, options);
+          cache.set(key, body, options).catch((err) => {
+            cache.emit("error", {
+              operation: "set",
+              error: err instanceof Error ? err.message : String(err)
+            });
+          });
           return originalJson(body);
         };
       }
@@ -2501,6 +3059,15 @@ function createExpressCacheMiddleware(cache, options = {}) {
     }
   };
 }
+function normalizeUrl(url) {
+  try {
+    const parsed = new URL(url, "http://localhost");
+    parsed.searchParams.sort();
+    return decodeURIComponent(parsed.pathname) + parsed.search;
+  } catch {
+    return url;
+  }
+}
 
 // src/integrations/graphql.ts
 function cacheGraphqlResolver(cache, prefix, resolver, options = {}) {
@@ -2520,7 +3087,8 @@ function createHonoCacheMiddleware(cache, options = {}) {
       await next();
       return;
     }
-    const key = options.keyResolver ? options.keyResolver(context.req) : `${method}:${context.req.path ?? context.req.url ?? "/"}`;
+    const rawPath = context.req.path ?? context.req.url ?? "/";
+    const key = options.keyResolver ? options.keyResolver(context.req) : `${method}:${normalizeUrl2(rawPath)}`;
     const cached = await cache.get(key, void 0, options);
     if (cached !== null) {
       context.header?.("x-cache", "HIT");
@@ -2531,12 +3099,26 @@ function createHonoCacheMiddleware(cache, options = {}) {
     const originalJson = context.json.bind(context);
     context.json = (body, status) => {
       context.header?.("x-cache", "MISS");
-      void cache.set(key, body, options);
+      cache.set(key, body, options).catch((err) => {
+        cache.emit("error", {
+          operation: "set",
+          error: err instanceof Error ? err.message : String(err)
+        });
+      });
       return originalJson(body, status);
     };
     await next();
   };
 }
+function normalizeUrl2(url) {
+  try {
+    const parsed = new URL(url, "http://localhost");
+    parsed.searchParams.sort();
+    return decodeURIComponent(parsed.pathname) + parsed.search;
+  } catch {
+    return url;
+  }
+}
 
 // src/integrations/opentelemetry.ts
 function createOpenTelemetryPlugin(cache, tracer) {
@@ -2671,16 +3253,10 @@ var MemoryLayer = class {
     return entry.value;
   }
   async getMany(keys) {
-    const values = [];
-    for (const key of keys) {
-      values.push(await this.getEntry(key));
-    }
-    return values;
+    return Promise.all(keys.map((key) => this.getEntry(key)));
   }
   async setMany(entries) {
-    for (const entry of entries) {
-      await this.set(entry.key, entry.value, entry.ttl);
-    }
+    await Promise.all(entries.map((entry) => this.set(entry.key, entry.value, entry.ttl)));
   }
   async set(key, value, ttl = this.defaultTtl) {
     this.entries.delete(key);
@@ -2816,19 +3392,6 @@ var MemoryLayer = class {
 // src/layers/RedisLayer.ts
 var import_node_util = require("util");
 var import_node_zlib = require("zlib");
-
-// src/serialization/JsonSerializer.ts
-var JsonSerializer = class {
-  serialize(value) {
-    return JSON.stringify(value);
-  }
-  deserialize(payload) {
-    const normalized = Buffer.isBuffer(payload) ? payload.toString("utf8") : payload;
-    return JSON.parse(normalized);
-  }
-};
-
-// src/layers/RedisLayer.ts
 var BATCH_DELETE_SIZE = 500;
 var gzipAsync = (0, import_node_util.promisify)(import_node_zlib.gzip);
 var gunzipAsync = (0, import_node_util.promisify)(import_node_zlib.gunzip);
@@ -2845,6 +3408,7 @@ var RedisLayer = class {
   scanCount;
   compression;
   compressionThreshold;
+  decompressionMaxBytes;
   disconnectOnDispose;
   constructor(options) {
     this.client = options.client;
@@ -2856,6 +3420,7 @@ var RedisLayer = class {
     this.scanCount = options.scanCount ?? 100;
     this.compression = options.compression;
     this.compressionThreshold = options.compressionThreshold ?? 1024;
+    this.decompressionMaxBytes = options.decompressionMaxBytes ?? 64 * 1024 * 1024;
     this.disconnectOnDispose = options.disconnectOnDispose ?? false;
   }
   async get(key) {
@@ -3055,16 +3620,29 @@ var RedisLayer = class {
   }
   /**
    * Decompresses the payload asynchronously if a compression header is present.
+   * Enforces a maximum decompressed size to prevent decompression bomb attacks.
    */
   async decodePayload(payload) {
     if (!Buffer.isBuffer(payload)) {
       return payload;
     }
     if (payload.subarray(0, 10).toString() === "LCZ1:gzip:") {
-      return gunzipAsync(payload.subarray(10));
+      const decompressed = await gunzipAsync(payload.subarray(10));
+      if (decompressed.byteLength > this.decompressionMaxBytes) {
+        throw new Error(
+          `Decompressed payload (${decompressed.byteLength} bytes) exceeds decompressionMaxBytes limit (${this.decompressionMaxBytes} bytes).`
+        );
+      }
+      return decompressed;
     }
     if (payload.subarray(0, 12).toString() === "LCZ1:brotli:") {
-      return brotliDecompressAsync(payload.subarray(12));
+      const decompressed = await brotliDecompressAsync(payload.subarray(12));
+      if (decompressed.byteLength > this.decompressionMaxBytes) {
+        throw new Error(
+          `Decompressed payload (${decompressed.byteLength} bytes) exceeds decompressionMaxBytes limit (${this.decompressionMaxBytes} bytes).`
+        );
+      }
+      return decompressed;
     }
     return payload;
   }
@@ -3083,11 +3661,11 @@ var DiskLayer = class {
   maxFiles;
   writeQueue = Promise.resolve();
   constructor(options) {
-    this.directory = options.directory;
+    this.directory = this.resolveDirectory(options.directory);
     this.defaultTtl = options.ttl;
     this.name = options.name ?? "disk";
     this.serializer = options.serializer ?? new JsonSerializer();
-    this.maxFiles = options.maxFiles;
+    this.maxFiles = this.normalizeMaxFiles(options.maxFiles);
   }
   async get(key) {
     return unwrapStoredValue(await this.getEntry(key));
@@ -3102,7 +3680,7 @@ var DiskLayer = class {
     }
     let entry;
     try {
-      entry = this.serializer.deserialize(raw);
+      entry = this.deserializeEntry(raw);
     } catch {
       await this.safeDelete(filePath);
       return null;
@@ -3124,8 +3702,13 @@ var DiskLayer = class {
       const payload = this.serializer.serialize(entry);
       const targetPath = this.keyToPath(key);
       const tempPath = `${targetPath}.${process.pid}.${Date.now()}.${Math.random().toString(36).slice(2)}.tmp`;
-      await import_node_fs.promises.writeFile(tempPath, payload);
-      await import_node_fs.promises.rename(tempPath, targetPath);
+      try {
+        await import_node_fs.promises.writeFile(tempPath, payload);
+        await import_node_fs.promises.rename(tempPath, targetPath);
+      } catch (error) {
+        await this.safeDelete(tempPath);
+        throw error;
+      }
       if (this.maxFiles !== void 0) {
         await this.enforceMaxFiles();
       }
@@ -3135,9 +3718,7 @@ var DiskLayer = class {
     return Promise.all(keys.map((key) => this.getEntry(key)));
   }
   async setMany(entries) {
-    for (const entry of entries) {
-      await this.set(entry.key, entry.value, entry.ttl);
-    }
+    await Promise.all(entries.map((entry) => this.set(entry.key, entry.value, entry.ttl)));
   }
   async has(key) {
     const value = await this.getEntry(key);
@@ -3153,8 +3734,9 @@ var DiskLayer = class {
     }
     let entry;
     try {
-      entry = this.serializer.deserialize(raw);
+      entry = this.deserializeEntry(raw);
     } catch {
+      await this.safeDelete(filePath);
       return null;
     }
     if (entry.expiresAt === null) {
@@ -3211,7 +3793,7 @@ var DiskLayer = class {
         }
         let entry;
         try {
-          entry = this.serializer.deserialize(raw);
+          entry = this.deserializeEntry(raw);
         } catch {
           await this.safeDelete(filePath);
           return;
@@ -3243,6 +3825,31 @@ var DiskLayer = class {
     const hash = (0, import_node_crypto.createHash)("sha256").update(key).digest("hex");
     return (0, import_node_path.join)(this.directory, `${hash}.lc`);
   }
+  resolveDirectory(directory) {
+    if (typeof directory !== "string" || directory.trim().length === 0) {
+      throw new Error("DiskLayer.directory must be a non-empty path.");
+    }
+    if (directory.includes("\0")) {
+      throw new Error("DiskLayer.directory must not contain null bytes.");
+    }
+    return (0, import_node_path.resolve)(directory);
+  }
+  normalizeMaxFiles(maxFiles) {
+    if (maxFiles === void 0) {
+      return void 0;
+    }
+    if (!Number.isInteger(maxFiles) || maxFiles <= 0) {
+      throw new Error("DiskLayer.maxFiles must be a positive integer.");
+    }
+    return maxFiles;
+  }
+  deserializeEntry(raw) {
+    const entry = this.serializer.deserialize(raw);
+    if (!isDiskEntry(entry)) {
+      throw new Error("Invalid disk cache entry.");
+    }
+    return entry;
+  }
   async safeDelete(filePath) {
     try {
       await import_node_fs.promises.unlink(filePath);
@@ -3287,6 +3894,14 @@ var DiskLayer = class {
     await Promise.all(toEvict.map(({ filePath }) => this.safeDelete(filePath)));
   }
 };
+function isDiskEntry(value) {
+  if (!value || typeof value !== "object") {
+    return false;
+  }
+  const candidate = value;
+  const validExpiry = candidate.expiresAt === null || typeof candidate.expiresAt === "number";
+  return typeof candidate.key === "string" && validExpiry && "value" in candidate;
+}
 
 // src/layers/MemcachedLayer.ts
 var MemcachedLayer = class {
@@ -3307,6 +3922,7 @@ var MemcachedLayer = class {
     return unwrapStoredValue(await this.getEntry(key));
   }
   async getEntry(key) {
+    this.validateKey(key);
     const result = await this.client.get(this.withPrefix(key));
     if (!result || result.value === null) {
       return null;
@@ -3321,16 +3937,19 @@ var MemcachedLayer = class {
     return Promise.all(keys.map((key) => this.getEntry(key)));
   }
   async set(key, value, ttl = this.defaultTtl) {
+    this.validateKey(key);
     const payload = this.serializer.serialize(value);
     await this.client.set(this.withPrefix(key), payload, {
       expires: ttl && ttl > 0 ? ttl : void 0
     });
   }
   async has(key) {
+    this.validateKey(key);
     const result = await this.client.get(this.withPrefix(key));
     return result !== null && result.value !== null;
   }
   async delete(key) {
+    this.validateKey(key);
     await this.client.delete(this.withPrefix(key));
   }
   async deleteMany(keys) {
@@ -3344,19 +3963,50 @@ var MemcachedLayer = class {
   withPrefix(key) {
     return `${this.keyPrefix}${key}`;
   }
+  validateKey(key) {
+    const fullKey = this.withPrefix(key);
+    if (Buffer.byteLength(fullKey, "utf8") > 250) {
+      throw new Error(`MemcachedLayer: key exceeds 250-byte Memcached limit: "${fullKey.slice(0, 60)}..."`);
+    }
+    if (/[\s\x00-\x1f\x7f]/.test(fullKey)) {
+      throw new Error(
+        "MemcachedLayer: key contains invalid characters (whitespace or control characters are not allowed)."
+      );
+    }
+  }
 };
 
 // src/serialization/MsgpackSerializer.ts
 var import_msgpack = require("@msgpack/msgpack");
+var DANGEROUS_KEYS = /* @__PURE__ */ new Set(["__proto__", "prototype", "constructor"]);
 var MsgpackSerializer = class {
   serialize(value) {
     return Buffer.from((0, import_msgpack.encode)(value));
   }
   deserialize(payload) {
     const normalized = Buffer.isBuffer(payload) ? payload : Buffer.from(payload);
-    return (0, import_msgpack.decode)(normalized);
+    return sanitizeMsgpackValue((0, import_msgpack.decode)(normalized));
   }
 };
+function sanitizeMsgpackValue(value) {
+  if (Array.isArray(value)) {
+    return value.map((entry) => sanitizeMsgpackValue(entry));
+  }
+  if (!isPlainObject2(value)) {
+    return value;
+  }
+  const sanitized = {};
+  for (const [key, entry] of Object.entries(value)) {
+    if (DANGEROUS_KEYS.has(key)) {
+      continue;
+    }
+    sanitized[key] = sanitizeMsgpackValue(entry);
+  }
+  return sanitized;
+}
+function isPlainObject2(value) {
+  return Object.prototype.toString.call(value) === "[object Object]";
+}
 
 // src/singleflight/RedisSingleFlightCoordinator.ts
 var import_node_crypto2 = require("crypto");
@@ -3366,6 +4016,12 @@ if redis.call("get", KEYS[1]) == ARGV[1] then
 end
 return 0
 `;
+var RENEW_SCRIPT = `
+if redis.call("get", KEYS[1]) == ARGV[1] then
+  return redis.call("pexpire", KEYS[1], ARGV[2])
+end
+return 0
+`;
 var RedisSingleFlightCoordinator = class {
   client;
   prefix;
@@ -3378,14 +4034,29 @@ var RedisSingleFlightCoordinator = class {
     const token = (0, import_node_crypto2.randomUUID)();
     const acquired = await this.client.set(lockKey, token, "PX", options.leaseMs, "NX");
     if (acquired === "OK") {
+      const renewTimer = this.startLeaseRenewal(lockKey, token, options);
       try {
         return await worker();
       } finally {
+        if (renewTimer) {
+          clearInterval(renewTimer);
+        }
         await this.client.eval(RELEASE_SCRIPT, 1, lockKey, token);
       }
     }
     return waiter();
   }
+  startLeaseRenewal(lockKey, token, options) {
+    const renewIntervalMs = options.renewIntervalMs ?? Math.max(100, Math.floor(options.leaseMs / 2));
+    if (renewIntervalMs <= 0 || renewIntervalMs >= options.leaseMs) {
+      return void 0;
+    }
+    const timer = setInterval(() => {
+      void this.client.eval(RENEW_SCRIPT, 1, lockKey, token, String(options.leaseMs)).catch(() => void 0);
+    }, renewIntervalMs);
+    timer.unref?.();
+    return timer;
+  }
 };
 
 // src/metrics/PrometheusExporter.ts
@@ -3464,7 +4135,7 @@ function createPrometheusMetricsExporter(stacks) {
   };
 }
 function sanitizeLabel(value) {
-  return value.replace(/["\\\n]/g, "_");
+  return value.replace(/["\\\n\r]/g, "_");
 }
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {