layercache 2.1.0 → 3.1.0

package/dist/index.js

@@ -12,12 +12,13 @@ import {
   validateTag,
   validateTags,
   validateTtlPolicy
-} from "./chunk-6X7NV5BG.js";
+} from "./chunk-L6L7QXYF.js";
 import {
   MemoryLayer,
   TagIndex,
-  createHonoCacheMiddleware
-} from "./chunk-IVX6ABFX.js";
+  createHonoCacheMiddleware,
+  normalizeHttpCacheUrl
+} from "./chunk-XMUT66SH.js";
 import {
   PatternMatcher,
   createStoredValueEnvelope,
@@ -70,39 +71,6 @@ function cloneNamespaceMetrics(metrics) {
     )
   };
 }
-function diffNamespaceMetrics(before, after) {
-  const latencyByLayer = Object.fromEntries(
-    Object.entries(after.latencyByLayer).map(([layer, value]) => [
-      layer,
-      {
-        avgMs: value.avgMs,
-        maxMs: value.maxMs,
-        count: Math.max(0, value.count - (before.latencyByLayer[layer]?.count ?? 0))
-      }
-    ])
-  );
-  return {
-    hits: after.hits - before.hits,
-    misses: after.misses - before.misses,
-    fetches: after.fetches - before.fetches,
-    sets: after.sets - before.sets,
-    deletes: after.deletes - before.deletes,
-    backfills: after.backfills - before.backfills,
-    invalidations: after.invalidations - before.invalidations,
-    staleHits: after.staleHits - before.staleHits,
-    refreshes: after.refreshes - before.refreshes,
-    refreshErrors: after.refreshErrors - before.refreshErrors,
-    writeFailures: after.writeFailures - before.writeFailures,
-    singleFlightWaits: after.singleFlightWaits - before.singleFlightWaits,
-    negativeCacheHits: after.negativeCacheHits - before.negativeCacheHits,
-    circuitBreakerTrips: after.circuitBreakerTrips - before.circuitBreakerTrips,
-    degradedOperations: after.degradedOperations - before.degradedOperations,
-    hitsByLayer: diffMetricMap(before.hitsByLayer, after.hitsByLayer),
-    missesByLayer: diffMetricMap(before.missesByLayer, after.missesByLayer),
-    latencyByLayer,
-    resetAt: after.resetAt
-  };
-}
 function addNamespaceMetrics(base, delta) {
   return {
     hits: base.hits + delta.hits,
@@ -138,14 +106,6 @@ function computeNamespaceHitRate(metrics) {
   }
   return { overall, byLayer };
 }
-function diffMetricMap(before, after) {
-  const keys = /* @__PURE__ */ new Set([...Object.keys(before), ...Object.keys(after)]);
-  const result = {};
-  for (const key of keys) {
-    result[key] = (after[key] ?? 0) - (before[key] ?? 0);
-  }
-  return result;
-}
 function addMetricMap(base, delta) {
   const keys = /* @__PURE__ */ new Set([...Object.keys(base), ...Object.keys(delta)]);
   const result = {};
@@ -182,6 +142,20 @@ var CacheNamespace = class _CacheNamespace {
   async getOrSet(key, fetcher, options) {
     return this.trackMetrics(() => this.cache.getOrSet(this.qualify(key), fetcher, this.qualifyGetOptions(options)));
   }
+  /**
+   * Returns a namespaced cache entry, or `null` on miss.
+   * Unlike `get()`, this distinguishes a stored `null` value from an absent key.
+   */
+  async getEntry(key) {
+    const entry = await this.trackMetrics(() => this.cache.getEntry(this.qualify(key)));
+    if (entry === null) {
+      return null;
+    }
+    return {
+      ...entry,
+      key
+    };
+  }
   /**
    * Like `get()`, but throws `CacheMissError` instead of returning `null`.
    */
@@ -416,13 +390,24 @@ var CacheNamespace = class _CacheNamespace {
     };
   }
   async trackMetrics(operation) {
-    return this.getMetricsMutex().runExclusive(async () => {
-      const before = this.cache.getMetrics();
-      const result = await operation();
-      const after = this.cache.getMetrics();
-      this.metrics = addNamespaceMetrics(this.metrics, diffNamespaceMetrics(before, after));
-      return result;
+    let result;
+    let metrics;
+    try {
+      ;
+      ({ result, metrics } = await this.cache.captureMetrics(operation));
+    } catch (error) {
+      const capturedMetrics = error.metrics;
+      if (capturedMetrics) {
+        await this.getMetricsMutex().runExclusive(() => {
+          this.metrics = addNamespaceMetrics(this.metrics, capturedMetrics);
+        });
+      }
+      throw error;
+    }
+    await this.getMetricsMutex().runExclusive(() => {
+      this.metrics = addNamespaceMetrics(this.metrics, metrics);
     });
+    return result;
   }
   getMetricsMutex() {
     const existing = _CacheNamespace.metricsMutexes.get(this.cache);
@@ -913,7 +898,9 @@ var CacheStackMaintenance = class {
   }
   bumpKeyEpochs(keys) {
     for (const key of keys) {
-      this.keyEpochs.set(key, this.currentKeyEpoch(key) + 1);
+      const nextEpoch = this.currentKeyEpoch(key) + 1;
+      this.keyEpochs.delete(key);
+      this.keyEpochs.set(key, nextEpoch);
     }
     this.pruneKeyEpochsIfNeeded();
   }
@@ -972,10 +959,13 @@ var CacheStackMaintenance = class {
     if (this.keyEpochs.size <= MAX_KEY_EPOCHS) {
       return;
     }
-    const sorted = [...this.keyEpochs.entries()].sort((a, b) => a[1] - b[1]);
-    const toDelete = Math.ceil(sorted.length * 0.1);
+    const toDelete = Math.ceil(this.keyEpochs.size * 0.1);
     for (let i = 0; i < toDelete; i++) {
-      this.keyEpochs.delete(sorted[i][0]);
+      const oldestKey = this.keyEpochs.keys().next().value;
+      if (oldestKey === void 0) {
+        break;
+      }
+      this.keyEpochs.delete(oldestKey);
     }
   }
 };
@@ -1021,6 +1011,9 @@ 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 SINGLE_FLIGHT_BACKOFF_FACTOR = 2;
+var SINGLE_FLIGHT_BACKOFF_JITTER = 0.2;
+var SINGLE_FLIGHT_MAX_POLL_MS = 1e3;
 var CacheStackReader = class {
   constructor(options) {
     this.options = options;
@@ -1109,22 +1102,28 @@ var CacheStackReader = class {
     if (upToIndex < 0) {
       return;
     }
+    const operations = [];
     for (let index = 0; index <= upToIndex; index += 1) {
       const layer = this.options.layers[index];
       if (!layer || this.options.shouldSkipLayer(layer)) {
         continue;
       }
       const ttl = remainingStoredTtlMs(stored) ?? this.options.resolveLayerMs(layer.name, options?.ttl, void 0, layer.defaultTtl);
-      try {
-        await layer.set(key, stored, ttl);
-      } catch (error) {
-        await this.options.handleLayerFailure(layer, "backfill", error);
-        continue;
-      }
-      this.options.metricsCollector.increment("backfills");
-      this.options.logger.debug?.("backfill", { key, layer: layer.name });
-      this.options.emit("backfill", { key, layer: layer.name });
+      operations.push(
+        (async () => {
+          try {
+            await layer.set(key, stored, ttl);
+          } catch (error) {
+            await this.options.handleLayerFailure(layer, "backfill", error);
+            return;
+          }
+          this.options.metricsCollector.increment("backfills");
+          this.options.logger.debug?.("backfill", { key, layer: layer.name });
+          this.options.emit("backfill", { key, layer: layer.name });
+        })()
+      );
     }
+    await Promise.all(operations);
   }
   abortAllRefreshes() {
     for (const key of this.backgroundRefreshAbort.keys()) {
@@ -1238,6 +1237,7 @@ var CacheStackReader = class {
     const timeoutMs = this.options.singleFlightTimeoutMs ?? DEFAULT_SINGLE_FLIGHT_TIMEOUT_MS;
     const pollIntervalMs = this.options.singleFlightPollMs ?? DEFAULT_SINGLE_FLIGHT_POLL_MS;
     const deadline = Date.now() + timeoutMs;
+    let nextPollMs = pollIntervalMs;
     this.options.metricsCollector.increment("singleFlightWaits");
     this.options.emit("stampede-dedupe", { key });
     while (Date.now() < deadline) {
@@ -1246,16 +1246,36 @@ var CacheStackReader = class {
         this.options.metricsCollector.increment("hits");
         return hit.value;
       }
-      await this.options.sleep(pollIntervalMs);
+      const remainingMs = deadline - Date.now();
+      if (remainingMs <= 0) {
+        break;
+      }
+      const delayMs = Math.min(this.jitterSingleFlightPoll(nextPollMs), remainingMs);
+      await this.options.sleep(delayMs);
+      nextPollMs = Math.min(nextPollMs * SINGLE_FLIGHT_BACKOFF_FACTOR, SINGLE_FLIGHT_MAX_POLL_MS, timeoutMs);
+    }
+    if (!this.options.singleFlightCoordinator) {
+      return this.fetchAndPopulate(key, fetcher, options, expectedClearEpoch, expectedKeyEpoch, fetcherContext);
     }
-    return this.fetchAndPopulate(key, fetcher, options, expectedClearEpoch, expectedKeyEpoch, fetcherContext);
+    return this.options.singleFlightCoordinator.execute(
+      key,
+      this.resolveSingleFlightOptions(),
+      () => this.fetchAndPopulate(key, fetcher, options, expectedClearEpoch, expectedKeyEpoch, fetcherContext),
+      () => this.waitForFreshValue(key, fetcher, options, expectedClearEpoch, expectedKeyEpoch, fetcherContext)
+    );
+  }
+  jitterSingleFlightPoll(delayMs) {
+    const jitterRange = delayMs * SINGLE_FLIGHT_BACKOFF_JITTER;
+    return Math.max(1, Math.round(delayMs - jitterRange + Math.random() * jitterRange * 2));
   }
   async fetchAndPopulate(key, fetcher, options, expectedClearEpoch, expectedKeyEpoch, fetcherContext = {
     key,
     currentValue: void 0,
     state: "miss"
   }) {
-    this.options.circuitBreakerManager.assertClosed(key, options?.circuitBreaker ?? this.options.circuitBreaker);
+    const circuitBreakerOptions = options?.circuitBreaker ?? this.options.circuitBreaker;
+    const breakerKey = this.resolveCircuitBreakerKey(key, circuitBreakerOptions);
+    this.options.circuitBreakerManager.assertClosed(breakerKey, circuitBreakerOptions);
     this.options.metricsCollector.increment("fetches");
     const fetchStart = Date.now();
     let fetched;
@@ -1265,13 +1285,13 @@ var CacheStackReader = class {
         { key, fetcher },
         () => fetcher(fetcherContext)
       );
-      this.options.circuitBreakerManager.recordSuccess(key);
+      this.options.circuitBreakerManager.recordSuccess(breakerKey);
       this.options.logger.debug?.("fetch", { key, durationMs: Date.now() - fetchStart });
     } catch (error) {
-      this.options.recordCircuitFailure(key, options?.circuitBreaker ?? this.options.circuitBreaker, error);
+      this.options.recordCircuitFailure(key, breakerKey, circuitBreakerOptions, error);
       throw error;
     }
-    if (fetched === null || fetched === void 0) {
+    if (fetched === void 0 || fetched === null && !this.shouldCacheNullValues(options)) {
       if (!this.shouldNegativeCache(options)) {
         return null;
       }
@@ -1313,6 +1333,18 @@ var CacheStackReader = class {
     await this.options.storeEntry(key, "value", fetched, options);
     return fetched;
   }
+  resolveCircuitBreakerKey(key, options) {
+    if (!options) {
+      return `key:${key}`;
+    }
+    if (options.breakerKey) {
+      return `custom:${options.breakerKey}`;
+    }
+    if (options.scope === "shared") {
+      return "scope:shared";
+    }
+    return `key:${key}`;
+  }
   runScheduleBackgroundRefresh(key, fetcher, options, fetcherContext) {
     this.scheduleBackgroundRefresh(key, fetcher, options, fetcherContext);
   }
@@ -1413,6 +1445,9 @@ var CacheStackReader = class {
   shouldNegativeCache(options) {
     return options?.negativeCache ?? this.options.negativeCaching ?? false;
   }
+  shouldCacheNullValues(options) {
+    return options?.cacheNullValues ?? this.options.cacheNullValues ?? false;
+  }
   isNegativeStoredValue(stored) {
     return isStoredValueEnvelope(stored) && stored.kind === "empty";
   }
@@ -1814,6 +1849,7 @@ var CircuitBreakerManager = class {
 // src/internal/FetchRateLimiter.ts
 var MAX_BUCKETS = 1e4;
 var MAX_QUEUE_PER_BUCKET = 1e4;
+var DEFAULT_QUEUE_OVERFLOW_POLICY = "reject";
 var FetchRateLimiter = class {
   buckets = /* @__PURE__ */ new Map();
   queuesByBucket = /* @__PURE__ */ new Map();
@@ -1838,8 +1874,12 @@ var FetchRateLimiter = class {
       const bucketKey = this.resolveBucketKey(normalized, context);
       const queue = this.queuesByBucket.get(bucketKey) ?? [];
       if (queue.length >= MAX_QUEUE_PER_BUCKET) {
-        this.rateLimitBypasses += 1;
-        task().then(resolve2, reject);
+        if ((normalized.queueOverflow ?? DEFAULT_QUEUE_OVERFLOW_POLICY) === "bypass") {
+          this.rateLimitBypasses += 1;
+          task().then(resolve2, reject);
+          return;
+        }
+        reject(new Error(`FetchRateLimiter queue overflow for bucket "${bucketKey}".`));
         return;
       }
       queue.push({
@@ -1887,7 +1927,8 @@ var FetchRateLimiter = class {
       intervalMs,
       maxPerInterval,
       scope: options.scope ?? "global",
-      bucketKey: options.bucketKey
+      bucketKey: options.bucketKey,
+      queueOverflow: options.queueOverflow
     };
   }
   resolveBucketKey(options, context) {
@@ -2072,7 +2113,9 @@ var FetchRateLimiter = class {
 };
 
 // src/internal/MetricsCollector.ts
+import { AsyncLocalStorage } from "async_hooks";
 var MetricsCollector = class {
+  captures = new AsyncLocalStorage();
   data = this.empty();
   get snapshot() {
     return {
@@ -2085,18 +2128,46 @@ var MetricsCollector = class {
   increment(field, amount = 1) {
     ;
     this.data[field] += amount;
+    for (const capture of this.captures.getStore() ?? []) {
+      ;
+      capture[field] += amount;
+    }
   }
   incrementLayer(map, layerName) {
     this.data[map][layerName] = (this.data[map][layerName] ?? 0) + 1;
+    for (const capture of this.captures.getStore() ?? []) {
+      capture[map][layerName] = (capture[map][layerName] ?? 0) + 1;
+    }
   }
   /**
    * Records a read latency sample for the given layer.
    * Maintains a rolling average and max using Welford's online algorithm.
    */
   recordLatency(layerName, durationMs) {
-    const existing = this.data.latencyByLayer[layerName];
+    this.recordLatencySample(this.data, layerName, durationMs);
+    for (const capture of this.captures.getStore() ?? []) {
+      this.recordLatencySample(capture, layerName, durationMs);
+    }
+  }
+  async capture(operation) {
+    const metrics = this.empty();
+    const activeCaptures = this.captures.getStore();
+    const captures = activeCaptures ? [...activeCaptures, metrics] : [metrics];
+    try {
+      const result = await this.captures.run(captures, operation);
+      return { result, metrics };
+    } catch (error) {
+      if ((typeof error === "object" || typeof error === "function") && error !== null) {
+        ;
+        error.metrics = metrics;
+      }
+      throw error;
+    }
+  }
+  recordLatencySample(metrics, layerName, durationMs) {
+    const existing = metrics.latencyByLayer[layerName];
     if (!existing) {
-      this.data.latencyByLayer[layerName] = { avgMs: durationMs, maxMs: durationMs, count: 1 };
+      metrics.latencyByLayer[layerName] = { avgMs: durationMs, maxMs: durationMs, count: 1 };
       return;
     }
     existing.count += 1;
@@ -2163,6 +2234,7 @@ var TtlResolver = class {
     const profile = this.accessProfiles.get(key) ?? { hits: 0, lastAccessAt: Date.now() };
     profile.hits += 1;
     profile.lastAccessAt = Date.now();
+    this.accessProfiles.delete(key);
     this.accessProfiles.set(key, profile);
     this.pruneIfNeeded();
   }
@@ -2252,12 +2324,12 @@ var TtlResolver = class {
       return;
     }
     const toRemove = Math.ceil(this.maxProfileEntries * 0.1);
-    const sorted = [...this.accessProfiles.entries()].sort((a, b) => a[1].lastAccessAt - b[1].lastAccessAt);
-    for (let i = 0; i < toRemove && i < sorted.length; i++) {
-      const entry = sorted[i];
-      if (entry) {
-        this.accessProfiles.delete(entry[0]);
+    for (let i = 0; i < toRemove; i++) {
+      const oldestKey = this.accessProfiles.keys().next().value;
+      if (oldestKey === void 0) {
+        break;
       }
+      this.accessProfiles.delete(oldestKey);
     }
   }
 };
@@ -2508,7 +2580,7 @@ var CacheStack = class extends EventEmitter {
       emitError: (operation, context) => this.emitError(operation, context),
       formatError: (error) => this.formatError(error),
       storeEntry: (key, kind, value, options2) => this.storeEntry(key, kind, value, options2),
-      recordCircuitFailure: (key, options2, error) => this.recordCircuitFailure(key, options2, error),
+      recordCircuitFailure: (key, breakerKey, options2, error) => this.recordCircuitFailure(key, breakerKey, options2, error),
       resolveLayerMs: (layerName, override, globalDefault, fallback) => this.resolveLayerMs(layerName, override, globalDefault, fallback),
       sleep: (ms) => this.sleep(ms),
       withTimeout: (promise, ms, createError) => this.withTimeout(promise, ms, createError),
@@ -2523,6 +2595,7 @@ var CacheStack = class extends EventEmitter {
       singleFlightRenewIntervalMs: options.singleFlightRenewIntervalMs,
       backgroundRefreshTimeoutMs: options.backgroundRefreshTimeoutMs,
       negativeCaching: options.negativeCaching,
+      cacheNullValues: options.cacheNullValues,
       refreshAhead: options.refreshAhead,
       circuitBreaker: options.circuitBreaker,
       fetcherRateLimit: options.fetcherRateLimit
@@ -2575,6 +2648,64 @@ var CacheStack = class extends EventEmitter {
   async getOrSet(key, fetcher, options) {
     return this.get(key, fetcher, options);
   }
+  /**
+   * Returns a discriminated cache entry, or `null` on miss.
+   * Unlike `get()`, this distinguishes a stored `null` value from an absent key.
+   */
+  async getEntry(key) {
+    return this.observeOperation("layercache.get_entry", { "layercache.key": String(key ?? "") }, async () => {
+      const userKey = validateCacheKey(key);
+      const normalizedKey = this.qualifyKey(userKey);
+      await this.awaitStartup("getEntry");
+      let sawRetainableValue = false;
+      for (let index = 0; index < this.layers.length; index += 1) {
+        const layer = this.layers[index];
+        if (!layer || this.shouldSkipLayer(layer)) {
+          continue;
+        }
+        const readStart = performance.now();
+        const stored = await this.readLayerEntry(layer, normalizedKey);
+        this.metricsCollector.recordLatency(layer.name, performance.now() - readStart);
+        if (stored === null) {
+          this.metricsCollector.incrementLayer("missesByLayer", layer.name);
+          continue;
+        }
+        const resolved = resolveStoredValue(stored);
+        if (resolved.state === "expired") {
+          await layer.delete(normalizedKey);
+          continue;
+        }
+        sawRetainableValue = true;
+        await this.tagIndex.touch(normalizedKey);
+        await this.reader.backfill(normalizedKey, stored, index - 1);
+        this.metricsCollector.increment("hits");
+        if (resolved.state === "stale-while-revalidate" || resolved.state === "stale-if-error") {
+          this.metricsCollector.increment("staleHits");
+        }
+        this.metricsCollector.incrementLayer("hitsByLayer", layer.name);
+        this.logger.debug?.("hit", { key: normalizedKey, layer: layer.name, state: resolved.state });
+        this.emit("hit", {
+          key: normalizedKey,
+          layer: layer.name,
+          state: resolved.state
+        });
+        return {
+          key: userKey,
+          value: resolved.value,
+          kind: resolved.envelope?.kind ?? "value",
+          state: resolved.state,
+          layer: layer.name
+        };
+      }
+      if (!sawRetainableValue) {
+        await this.tagIndex.remove(normalizedKey);
+      }
+      this.metricsCollector.increment("misses");
+      this.logger.debug?.("miss", { key: normalizedKey, mode: "getEntry" });
+      this.emit("miss", { key: normalizedKey, mode: "getEntry" });
+      return null;
+    });
+  }
   /**
    * Like `get()`, but throws `CacheMissError` instead of returning `null`.
    * Useful when the value is expected to exist or the fetcher is expected to
@@ -3039,6 +3170,13 @@ var CacheStack = class extends EventEmitter {
   getMetrics() {
     return this.metricsCollector.snapshot;
   }
+  /**
+   * Runs an operation while collecting only the metrics emitted by its async context.
+   * Used by namespaces so metrics tracking does not serialize the operation itself.
+   */
+  async captureMetrics(operation) {
+    return this.metricsCollector.capture(operation);
+  }
   /**
    * Returns metrics plus layer degradation state and active background refresh count.
    */
@@ -3112,6 +3250,12 @@ var CacheStack = class extends EventEmitter {
     }
     return this.currentGeneration;
   }
+  /**
+   * Returns the active generation prefix number used for future cache keys.
+   */
+  getGeneration() {
+    return this.currentGeneration;
+  }
   /**
    * Returns detailed metadata about a single cache key: which layers contain it,
    * remaining fresh/stale/error TTLs, and associated tags.
@@ -3336,7 +3480,7 @@ var CacheStack = class extends EventEmitter {
     for (const key of keys) {
       await this.tagIndex.remove(key);
       this.ttlResolver.deleteProfile(key);
-      this.circuitBreakerManager.delete(key);
+      this.circuitBreakerManager.delete(`key:${key}`);
     }
     this.metricsCollector.increment("deletes", keys.length);
     this.metricsCollector.increment("invalidations");
@@ -3355,7 +3499,7 @@ var CacheStack = class extends EventEmitter {
       }
       await this.tagIndex.remove(key);
       this.ttlResolver.deleteProfile(key);
-      this.circuitBreakerManager.delete(key);
+      this.circuitBreakerManager.delete(`key:${key}`);
     }
     this.metricsCollector.increment("invalidations");
     this.logger.debug?.("expire", { keys });
@@ -3397,7 +3541,7 @@ var CacheStack = class extends EventEmitter {
       for (const key of keys) {
         await this.tagIndex.remove(key);
         this.ttlResolver.deleteProfile(key);
-        this.circuitBreakerManager.delete(key);
+        this.circuitBreakerManager.delete(`key:${key}`);
       }
     }
   }
@@ -3642,15 +3786,15 @@ var CacheStack = class extends EventEmitter {
   isGracefulDegradationEnabled() {
     return Boolean(this.options.gracefulDegradation);
   }
-  recordCircuitFailure(key, options, error) {
+  recordCircuitFailure(key, breakerKey, options, error) {
     if (!options) {
       return;
     }
-    this.circuitBreakerManager.recordFailure(key, options);
-    if (this.circuitBreakerManager.isOpen(key)) {
+    this.circuitBreakerManager.recordFailure(breakerKey, options);
+    if (this.circuitBreakerManager.isOpen(breakerKey)) {
       this.metricsCollector.increment("circuitBreakerTrips");
     }
-    this.emitError("fetch", { key, error: this.formatError(error) });
+    this.emitError("fetch", { key, breakerKey, error: this.formatError(error) });
   }
   emitError(operation, context) {
     this.logger.error?.(operation, context);
@@ -3669,12 +3813,65 @@ var CacheStack = class extends EventEmitter {
   }
 };
 
+// src/generation/RedisGenerationStore.ts
+var DEFAULT_GENERATION_KEY = "layercache:generation";
+var RedisGenerationStore = class {
+  client;
+  key;
+  constructor(options) {
+    this.client = options.client;
+    this.key = options.key ?? DEFAULT_GENERATION_KEY;
+  }
+  async get() {
+    const stored = await this.client.get(this.key);
+    if (stored === null) {
+      return void 0;
+    }
+    return this.parseGeneration(stored);
+  }
+  async getOrInitialize(initialGeneration = 0) {
+    this.assertGeneration(initialGeneration);
+    await this.client.set(this.key, String(initialGeneration), "NX");
+    const generation = await this.get();
+    if (generation === void 0) {
+      throw new Error(`RedisGenerationStore failed to initialize generation key "${this.key}".`);
+    }
+    return generation;
+  }
+  async set(generation) {
+    this.assertGeneration(generation);
+    await this.client.set(this.key, String(generation));
+  }
+  async bump() {
+    const generation = await this.client.incr(this.key);
+    this.assertGeneration(generation);
+    return generation;
+  }
+  parseGeneration(value) {
+    const generation = Number.parseInt(value, 10);
+    if (String(generation) !== value || !this.isGeneration(generation)) {
+      throw new Error(`RedisGenerationStore found invalid persisted generation value for key "${this.key}".`);
+    }
+    return generation;
+  }
+  assertGeneration(value) {
+    if (!this.isGeneration(value)) {
+      throw new Error("RedisGenerationStore generation must be a non-negative safe integer.");
+    }
+  }
+  isGeneration(value) {
+    return Number.isSafeInteger(value) && value >= 0;
+  }
+};
+
 // src/invalidation/RedisInvalidationBus.ts
+import { createHash, createHmac, timingSafeEqual } from "crypto";
 var RedisInvalidationBus = class {
   channel;
   publisher;
   subscriber;
   logger;
+  signingKey;
   handlers = /* @__PURE__ */ new Set();
   sharedListener;
   subscribePromise;
@@ -3683,6 +3880,7 @@ var RedisInvalidationBus = class {
     this.subscriber = options.subscriber ?? options.publisher.duplicate();
     this.channel = options.channel ?? "layercache:invalidation";
     this.logger = options.logger;
+    this.signingKey = options.signingSecret ? normalizeSigningSecret(options.signingSecret) : void 0;
   }
   /**
    * Subscribes to invalidation messages and returns an unsubscribe function.
@@ -3722,7 +3920,7 @@ var RedisInvalidationBus = class {
    * Publishes an invalidation message to other subscribers.
    */
   async publish(message) {
-    await this.publisher.publish(this.channel, JSON.stringify(message));
+    await this.publisher.publish(this.channel, JSON.stringify(this.signingKey ? this.signMessage(message) : message));
   }
   async dispatchToHandlers(payload) {
     let message;
@@ -3733,10 +3931,11 @@ var RedisInvalidationBus = class {
         maxNodes: 1e4,
         createObject: () => /* @__PURE__ */ Object.create(null)
       });
-      if (!this.isInvalidationMessage(parsed)) {
+      const candidate = this.signingKey ? this.verifySignedEnvelope(parsed) : parsed;
+      if (!this.isInvalidationMessage(candidate)) {
         throw new Error("Invalid invalidation payload shape.");
       }
-      message = parsed;
+      message = candidate;
     } catch (error) {
       this.reportError("invalid invalidation payload", error);
       return;
@@ -3761,6 +3960,34 @@ var RedisInvalidationBus = class {
     const validKeys = candidate.keys === void 0 || Array.isArray(candidate.keys) && candidate.keys.every((key) => typeof key === "string");
     return validScope && typeof candidate.sourceId === "string" && candidate.sourceId.length > 0 && validOperation && validKeys;
   }
+  signMessage(message) {
+    const payload = JSON.stringify(message);
+    return {
+      payload: message,
+      signature: this.createSignature(payload)
+    };
+  }
+  verifySignedEnvelope(value) {
+    if (!value || typeof value !== "object") {
+      throw new Error("Signed invalidation envelope must be an object.");
+    }
+    const envelope = value;
+    if (!envelope.payload || typeof envelope.payload !== "object" || typeof envelope.signature !== "string") {
+      throw new Error("Signed invalidation envelope is missing payload or signature.");
+    }
+    const payload = JSON.stringify(envelope.payload);
+    const expected = this.createSignature(payload);
+    if (!isEqualSignature(envelope.signature, expected)) {
+      throw new Error("Invalid invalidation message signature.");
+    }
+    return envelope.payload;
+  }
+  createSignature(payload) {
+    if (!this.signingKey) {
+      throw new Error("RedisInvalidationBus signing key is not configured.");
+    }
+    return createHmac("sha256", this.signingKey).update(payload).digest("hex");
+  }
   reportError(message, error) {
     if (this.logger?.error) {
       this.logger.error(message, { error });
@@ -3769,6 +3996,15 @@ var RedisInvalidationBus = class {
     console.error(`[layercache] ${message}`, error);
   }
 };
+function normalizeSigningSecret(secret) {
+  const raw = Buffer.isBuffer(secret) ? secret : Buffer.from(secret, "utf8");
+  return createHash("sha256").update(raw).digest();
+}
+function isEqualSignature(actual, expected) {
+  const actualBuffer = Buffer.from(actual, "hex");
+  const expectedBuffer = Buffer.from(expected, "hex");
+  return actualBuffer.length === expectedBuffer.length && timingSafeEqual(actualBuffer, expectedBuffer);
+}
 
 // src/http/createCacheStatsHandler.ts
 function createCacheStatsHandler(cache, options = {}) {
@@ -3866,7 +4102,7 @@ function createExpressCacheMiddleware(cache, options = {}) {
         return;
       }
       const rawUrl = req.originalUrl ?? req.url ?? "/";
-      const key = options.keyResolver ? options.keyResolver(req) : `${method}:${normalizeUrl(rawUrl)}`;
+      const key = options.keyResolver ? options.keyResolver(req) : `${method}:${normalizeHttpCacheUrl(rawUrl)}`;
       const cached = await cache.get(key, void 0, options);
       if (cached !== null) {
         res.setHeader?.("content-type", "application/json; charset=utf-8");
@@ -3882,12 +4118,14 @@ function createExpressCacheMiddleware(cache, options = {}) {
       if (originalJson) {
         res.json = (body) => {
           res.setHeader?.("x-cache", "MISS");
-          cache.set(key, body, options).catch((err) => {
-            cache.emit("error", {
-              operation: "set",
-              error: err instanceof Error ? err.message : String(err)
+          if (isSuccessfulStatus(res.statusCode)) {
+            cache.set(key, body, options).catch((err) => {
+              cache.emit("error", {
+                operation: "set",
+                error: err instanceof Error ? err.message : String(err)
+              });
             });
-          });
+          }
           return originalJson(body);
         };
       }
@@ -3897,14 +4135,8 @@ function createExpressCacheMiddleware(cache, options = {}) {
     }
   };
 }
-function normalizeUrl(url) {
-  try {
-    const parsed = new URL(url, "http://localhost");
-    parsed.searchParams.sort();
-    return parsed.pathname + parsed.search;
-  } catch {
-    return url;
-  }
+function isSuccessfulStatus(statusCode) {
+  return statusCode === void 0 || statusCode >= 200 && statusCode < 300;
 }
 
 // src/integrations/graphql.ts
@@ -4471,12 +4703,12 @@ var RedisLayer = class {
 };
 
 // src/layers/DiskLayer.ts
-import { createHash as createHash2, randomBytes as randomBytes4 } from "crypto";
+import { createHash as createHash3, randomBytes as randomBytes4 } from "crypto";
 import { promises as fs2 } from "fs";
 import { join, resolve } from "path";
 
 // src/internal/PayloadProtection.ts
-import { createCipheriv, createDecipheriv, createHash, createHmac, randomBytes as randomBytes3, timingSafeEqual } from "crypto";
+import { createCipheriv, createDecipheriv, createHash as createHash2, createHmac as createHmac2, randomBytes as randomBytes3, timingSafeEqual as timingSafeEqual2 } from "crypto";
 var MAGIC_ENCRYPTED = Buffer.from("LCP1:");
 var MAGIC_SIGNED = Buffer.from("LCS1:");
 var ALGORITHM = "aes-256-gcm";
@@ -4489,11 +4721,11 @@ var PayloadProtection = class {
   constructor(options) {
     if (options.encryptionKey) {
       const raw = Buffer.isBuffer(options.encryptionKey) ? options.encryptionKey : Buffer.from(options.encryptionKey, "utf8");
-      this.encryptionKey = createHash("sha256").update(raw).digest();
+      this.encryptionKey = createHash2("sha256").update(raw).digest();
     }
     if (options.signingKey && !options.encryptionKey) {
       const raw = Buffer.isBuffer(options.signingKey) ? options.signingKey : Buffer.from(options.signingKey, "utf8");
-      this.signingKey = createHash("sha256").update(raw).digest();
+      this.signingKey = createHash2("sha256").update(raw).digest();
     }
   }
   /** Returns `true` when any protection (encryption or signing) is configured. */
@@ -4565,15 +4797,15 @@ var PayloadProtection = class {
   }
   // ── Signing (HMAC-SHA256) ─────────────────────────────────────────────
   sign(payload, key) {
-    const hmac = createHmac("sha256", key).update(payload).digest();
+    const hmac = createHmac2("sha256", key).update(payload).digest();
     return Buffer.concat([MAGIC_SIGNED, hmac, payload]);
   }
   verify(payload, key) {
     const headerEnd = MAGIC_SIGNED.length;
     const receivedHmac = payload.subarray(headerEnd, headerEnd + HMAC_LENGTH);
     const data = payload.subarray(headerEnd + HMAC_LENGTH);
-    const expectedHmac = createHmac("sha256", key).update(data).digest();
-    if (receivedHmac.length !== HMAC_LENGTH || !timingSafeEqual(receivedHmac, expectedHmac)) {
+    const expectedHmac = createHmac2("sha256", key).update(data).digest();
+    if (receivedHmac.length !== HMAC_LENGTH || !timingSafeEqual2(receivedHmac, expectedHmac)) {
       throw new PayloadProtectionError(
         "HMAC verification failed. The data may have been tampered with or the signingKey is incorrect."
       );
@@ -4597,6 +4829,7 @@ var PayloadProtectionError = class extends Error {
 
 // src/layers/DiskLayer.ts
 var FILE_SCAN_CONCURRENCY = 32;
+var DEFAULT_MAX_WRITE_QUEUE_DEPTH = 1e4;
 var DiskLayer = class {
   name;
   defaultTtl;
@@ -4605,8 +4838,10 @@ var DiskLayer = class {
   serializer;
   maxFiles;
   maxEntryBytes;
+  maxWriteQueueDepth;
   protection;
   writeQueue = Promise.resolve();
+  writeQueueDepth = 0;
   /**
    * Creates a disk-backed cache layer.
    */
@@ -4617,6 +4852,7 @@ var DiskLayer = class {
     this.serializer = options.serializer ?? new JsonSerializer();
     this.maxFiles = this.normalizeMaxFiles(options.maxFiles);
     this.maxEntryBytes = this.normalizeMaxEntryBytes(options.maxEntryBytes);
+    this.maxWriteQueueDepth = this.normalizeMaxWriteQueueDepth(options.maxWriteQueueDepth);
     this.protection = new PayloadProtection({
       encryptionKey: options.encryptionKey,
       signingKey: options.signingKey
@@ -4798,7 +5034,7 @@ var DiskLayer = class {
   async dispose() {
   }
   keyToPath(key) {
-    const hash = createHash2("sha256").update(key).digest("hex");
+    const hash = createHash3("sha256").update(key).digest("hex");
     return join(this.directory, `${hash}.lc`);
   }
   resolveDirectory(directory) {
@@ -4832,6 +5068,16 @@ var DiskLayer = class {
     }
     return normalized;
   }
+  normalizeMaxWriteQueueDepth(maxWriteQueueDepth) {
+    if (maxWriteQueueDepth === false) {
+      return false;
+    }
+    const normalized = maxWriteQueueDepth ?? DEFAULT_MAX_WRITE_QUEUE_DEPTH;
+    if (!Number.isInteger(normalized) || normalized <= 0) {
+      throw new Error("DiskLayer.maxWriteQueueDepth must be a positive integer or false.");
+    }
+    return normalized;
+  }
   async readEntryFile(filePath) {
     let handle;
     try {
@@ -4944,7 +5190,13 @@ var DiskLayer = class {
     }
   }
   enqueueWrite(operation) {
-    const next = this.writeQueue.then(operation, operation);
+    if (this.maxWriteQueueDepth !== false && this.writeQueueDepth >= this.maxWriteQueueDepth) {
+      return Promise.reject(new Error(`DiskLayer write queue limit (${this.maxWriteQueueDepth}) exceeded.`));
+    }
+    this.writeQueueDepth += 1;
+    const next = this.writeQueue.then(operation, operation).finally(() => {
+      this.writeQueueDepth -= 1;
+    });
     this.writeQueue = next.catch(() => void 0);
     return next;
   }
@@ -5297,6 +5549,7 @@ export {
   MemoryLayer,
   MsgpackSerializer,
   PatternMatcher,
+  RedisGenerationStore,
   RedisInvalidationBus,
   RedisLayer,
   RedisSingleFlightCoordinator,