layercache 2.1.0 → 3.0.0

package/dist/index.d.cts

@@ -1,8 +1,32 @@
-import { I as InvalidationBus, C as CacheLogger, a as InvalidationMessage, b as CacheTagIndex, c as CacheStack, d as CacheWrapOptions, e as CacheGetOptions, f as CacheLayer, g as CacheSerializer, h as CacheLayerSetManyEntry, i as CacheSingleFlightCoordinator, j as CacheSingleFlightExecutionOptions } from './edge-BCU8D-Yd.cjs';
-export { k as CacheAdaptiveTtlOptions, l as CacheCircuitBreakerOptions, m as CacheContextOptionsContext, n as CacheDegradationOptions, o as CacheEntryWriteKind, p as CacheEntryWriteOptions, q as CacheFetcher, r as CacheFetcherContext, s as CacheHealthCheckResult, t as CacheHitRateSnapshot, u as CacheInspectResult, v as CacheLayerLatency, w as CacheMGetEntry, x as CacheMSetEntry, y as CacheMetricsSnapshot, z as CacheMissError, A as CacheNamespace, B as CacheRateLimitOptions, D as CacheSnapshotEntry, E as CacheStackEvents, F as CacheStackOptions, G as CacheStatsSnapshot, H as CacheTtlPolicy, J as CacheTtlPolicyContext, K as CacheWarmEntry, L as CacheWarmOptions, M as CacheWarmProgress, N as CacheWriteBehindOptions, O as CacheWriteOptions, P as EvictionPolicy, Q as LayerTtlMap, R as MemoryLayer, S as MemoryLayerOptions, T as MemoryLayerSnapshotEntry, U as PatternMatcher, V as TagIndex, W as createHonoCacheMiddleware } from './edge-BCU8D-Yd.cjs';
+import { I as InvalidationBus, C as CacheLogger, a as InvalidationMessage, b as CacheTagIndex, c as CacheStack, d as CacheWrapOptions, e as CacheGetOptions, f as CacheLayer, g as CacheSerializer, h as CacheLayerSetManyEntry, i as CacheSingleFlightCoordinator, j as CacheSingleFlightExecutionOptions } from './edge-BDyuPmIq.cjs';
+export { k as CacheAdaptiveTtlOptions, l as CacheCircuitBreakerOptions, m as CacheContextOptionsContext, n as CacheDegradationOptions, o as CacheEntryWriteKind, p as CacheEntryWriteOptions, q as CacheFetcher, r as CacheFetcherContext, s as CacheHealthCheckResult, t as CacheHitRateSnapshot, u as CacheInspectResult, v as CacheLayerLatency, w as CacheMGetEntry, x as CacheMSetEntry, y as CacheMetricsSnapshot, z as CacheMissError, A as CacheNamespace, B as CacheRateLimitOptions, D as CacheSnapshotEntry, E as CacheStackEvents, F as CacheStackOptions, G as CacheStatsSnapshot, H as CacheTtlPolicy, J as CacheTtlPolicyContext, K as CacheWarmEntry, L as CacheWarmOptions, M as CacheWarmProgress, N as CacheWriteBehindOptions, O as CacheWriteOptions, P as EvictionPolicy, Q as LayerTtlMap, R as MemoryLayer, S as MemoryLayerOptions, T as MemoryLayerSnapshotEntry, U as PatternMatcher, V as TagIndex, W as createHonoCacheMiddleware } from './edge-BDyuPmIq.cjs';
 import Redis from 'ioredis';
 import 'node:events';
 
+interface RedisGenerationClient {
+    get(key: string): Promise<string | null>;
+    set(key: string, value: string, mode?: 'NX'): Promise<unknown>;
+    incr(key: string): Promise<number>;
+}
+interface RedisGenerationStoreOptions {
+    /** Redis client used to persist and atomically bump the generation. */
+    client: RedisGenerationClient;
+    /** Redis key storing the active generation. Defaults to `layercache:generation`. */
+    key?: string;
+}
+declare class RedisGenerationStore {
+    private readonly client;
+    private readonly key;
+    constructor(options: RedisGenerationStoreOptions);
+    get(): Promise<number | undefined>;
+    getOrInitialize(initialGeneration?: number): Promise<number>;
+    set(generation: number): Promise<void>;
+    bump(): Promise<number>;
+    private parseGeneration;
+    private assertGeneration;
+    private isGeneration;
+}
+
 interface RedisInvalidationBusOptions {
     /** Redis client used to publish invalidation messages. */
     publisher: Redis;
@@ -10,6 +34,11 @@ interface RedisInvalidationBusOptions {
     subscriber?: Redis;
     /** Pub/sub channel name. Defaults to `layercache:invalidation`. */
     channel?: string;
+    /**
+     * Optional shared secret used to sign and verify invalidation messages.
+     * When configured, unsigned or invalidly signed messages are rejected.
+     */
+    signingSecret?: string | Buffer;
     /** Optional logger for invalid payloads or subscriber errors. */
     logger?: CacheLogger;
 }
@@ -25,6 +54,7 @@ declare class RedisInvalidationBus implements InvalidationBus {
     private readonly publisher;
     private readonly subscriber;
     private readonly logger?;
+    private readonly signingKey?;
     private readonly handlers;
     private sharedListener?;
     private subscribePromise;
@@ -39,6 +69,9 @@ declare class RedisInvalidationBus implements InvalidationBus {
     publish(message: InvalidationMessage): Promise<void>;
     private dispatchToHandlers;
     private isInvalidationMessage;
+    private signMessage;
+    private verifySignedEnvelope;
+    private createSignature;
     private reportError;
 }
 
@@ -51,12 +84,19 @@ interface RedisTagIndexOptions {
     scanCount?: number;
     /** Number of shards for known-key sets. Defaults to 16. */
     knownKeysShards?: number;
+    /** Optional logger for legacy index warnings. */
+    logger?: CacheLogger;
+}
+interface RedisTagIndexMigrationResult {
+    migratedKeys: number;
 }
 declare class RedisTagIndex implements CacheTagIndex {
     private readonly client;
     private readonly prefix;
     private readonly scanCount;
     private readonly knownKeysShards;
+    private readonly logger?;
+    private warnedLegacyKnownKeys;
     constructor(options: RedisTagIndexOptions);
     /**
      * Records a key as known without changing tag assignments.
@@ -102,9 +142,13 @@ declare class RedisTagIndex implements CacheTagIndex {
      * Clears all Redis tag-index state under this prefix.
      */
     clear(): Promise<void>;
+    migrateLegacyKnownKeys(): Promise<RedisTagIndexMigrationResult>;
     private scanIndexKeys;
     private knownKeysKeyFor;
+    private knownKeysKeysForRead;
     private knownKeysKeys;
+    private legacyKnownKeysKey;
+    private warnLegacyKnownKeys;
     private keyTagsKey;
     private tagKeysKey;
 }
@@ -746,4 +790,4 @@ declare function createPrometheusMetricsExporter(stacks: CacheStack | Array<{
     name: string;
 }>): () => string;
 
-export { CacheGetOptions, CacheLayer, CacheLayerSetManyEntry, CacheLogger, CacheSerializer, CacheSingleFlightCoordinator, CacheSingleFlightExecutionOptions, CacheStack, CacheTagIndex, CacheWrapOptions, DiskLayer, InvalidationBus, InvalidationMessage, JsonSerializer, type MemcachedClient, MemcachedLayer, MsgpackSerializer, RedisInvalidationBus, RedisLayer, RedisSingleFlightCoordinator, RedisTagIndex, StampedeGuard, cacheGraphqlResolver, createCacheStatsHandler, createCachedMethodDecorator, createExpressCacheMiddleware, createFastifyLayercachePlugin, createOpenTelemetryPlugin, createPrometheusMetricsExporter, createTrpcCacheMiddleware };
+export { CacheGetOptions, CacheLayer, CacheLayerSetManyEntry, CacheLogger, CacheSerializer, CacheSingleFlightCoordinator, CacheSingleFlightExecutionOptions, CacheStack, CacheTagIndex, CacheWrapOptions, DiskLayer, InvalidationBus, InvalidationMessage, JsonSerializer, type MemcachedClient, MemcachedLayer, MsgpackSerializer, RedisGenerationStore, RedisInvalidationBus, RedisLayer, RedisSingleFlightCoordinator, RedisTagIndex, StampedeGuard, cacheGraphqlResolver, createCacheStatsHandler, createCachedMethodDecorator, createExpressCacheMiddleware, createFastifyLayercachePlugin, createOpenTelemetryPlugin, createPrometheusMetricsExporter, createTrpcCacheMiddleware };

package/dist/index.d.ts

@@ -1,8 +1,32 @@
-import { I as InvalidationBus, C as CacheLogger, a as InvalidationMessage, b as CacheTagIndex, c as CacheStack, d as CacheWrapOptions, e as CacheGetOptions, f as CacheLayer, g as CacheSerializer, h as CacheLayerSetManyEntry, i as CacheSingleFlightCoordinator, j as CacheSingleFlightExecutionOptions } from './edge-BCU8D-Yd.js';
-export { k as CacheAdaptiveTtlOptions, l as CacheCircuitBreakerOptions, m as CacheContextOptionsContext, n as CacheDegradationOptions, o as CacheEntryWriteKind, p as CacheEntryWriteOptions, q as CacheFetcher, r as CacheFetcherContext, s as CacheHealthCheckResult, t as CacheHitRateSnapshot, u as CacheInspectResult, v as CacheLayerLatency, w as CacheMGetEntry, x as CacheMSetEntry, y as CacheMetricsSnapshot, z as CacheMissError, A as CacheNamespace, B as CacheRateLimitOptions, D as CacheSnapshotEntry, E as CacheStackEvents, F as CacheStackOptions, G as CacheStatsSnapshot, H as CacheTtlPolicy, J as CacheTtlPolicyContext, K as CacheWarmEntry, L as CacheWarmOptions, M as CacheWarmProgress, N as CacheWriteBehindOptions, O as CacheWriteOptions, P as EvictionPolicy, Q as LayerTtlMap, R as MemoryLayer, S as MemoryLayerOptions, T as MemoryLayerSnapshotEntry, U as PatternMatcher, V as TagIndex, W as createHonoCacheMiddleware } from './edge-BCU8D-Yd.js';
+import { I as InvalidationBus, C as CacheLogger, a as InvalidationMessage, b as CacheTagIndex, c as CacheStack, d as CacheWrapOptions, e as CacheGetOptions, f as CacheLayer, g as CacheSerializer, h as CacheLayerSetManyEntry, i as CacheSingleFlightCoordinator, j as CacheSingleFlightExecutionOptions } from './edge-BDyuPmIq.js';
+export { k as CacheAdaptiveTtlOptions, l as CacheCircuitBreakerOptions, m as CacheContextOptionsContext, n as CacheDegradationOptions, o as CacheEntryWriteKind, p as CacheEntryWriteOptions, q as CacheFetcher, r as CacheFetcherContext, s as CacheHealthCheckResult, t as CacheHitRateSnapshot, u as CacheInspectResult, v as CacheLayerLatency, w as CacheMGetEntry, x as CacheMSetEntry, y as CacheMetricsSnapshot, z as CacheMissError, A as CacheNamespace, B as CacheRateLimitOptions, D as CacheSnapshotEntry, E as CacheStackEvents, F as CacheStackOptions, G as CacheStatsSnapshot, H as CacheTtlPolicy, J as CacheTtlPolicyContext, K as CacheWarmEntry, L as CacheWarmOptions, M as CacheWarmProgress, N as CacheWriteBehindOptions, O as CacheWriteOptions, P as EvictionPolicy, Q as LayerTtlMap, R as MemoryLayer, S as MemoryLayerOptions, T as MemoryLayerSnapshotEntry, U as PatternMatcher, V as TagIndex, W as createHonoCacheMiddleware } from './edge-BDyuPmIq.js';
 import Redis from 'ioredis';
 import 'node:events';
 
+interface RedisGenerationClient {
+    get(key: string): Promise<string | null>;
+    set(key: string, value: string, mode?: 'NX'): Promise<unknown>;
+    incr(key: string): Promise<number>;
+}
+interface RedisGenerationStoreOptions {
+    /** Redis client used to persist and atomically bump the generation. */
+    client: RedisGenerationClient;
+    /** Redis key storing the active generation. Defaults to `layercache:generation`. */
+    key?: string;
+}
+declare class RedisGenerationStore {
+    private readonly client;
+    private readonly key;
+    constructor(options: RedisGenerationStoreOptions);
+    get(): Promise<number | undefined>;
+    getOrInitialize(initialGeneration?: number): Promise<number>;
+    set(generation: number): Promise<void>;
+    bump(): Promise<number>;
+    private parseGeneration;
+    private assertGeneration;
+    private isGeneration;
+}
+
 interface RedisInvalidationBusOptions {
     /** Redis client used to publish invalidation messages. */
     publisher: Redis;
@@ -10,6 +34,11 @@ interface RedisInvalidationBusOptions {
     subscriber?: Redis;
     /** Pub/sub channel name. Defaults to `layercache:invalidation`. */
     channel?: string;
+    /**
+     * Optional shared secret used to sign and verify invalidation messages.
+     * When configured, unsigned or invalidly signed messages are rejected.
+     */
+    signingSecret?: string | Buffer;
     /** Optional logger for invalid payloads or subscriber errors. */
     logger?: CacheLogger;
 }
@@ -25,6 +54,7 @@ declare class RedisInvalidationBus implements InvalidationBus {
     private readonly publisher;
     private readonly subscriber;
     private readonly logger?;
+    private readonly signingKey?;
     private readonly handlers;
     private sharedListener?;
     private subscribePromise;
@@ -39,6 +69,9 @@ declare class RedisInvalidationBus implements InvalidationBus {
     publish(message: InvalidationMessage): Promise<void>;
     private dispatchToHandlers;
     private isInvalidationMessage;
+    private signMessage;
+    private verifySignedEnvelope;
+    private createSignature;
     private reportError;
 }
 
@@ -51,12 +84,19 @@ interface RedisTagIndexOptions {
     scanCount?: number;
     /** Number of shards for known-key sets. Defaults to 16. */
     knownKeysShards?: number;
+    /** Optional logger for legacy index warnings. */
+    logger?: CacheLogger;
+}
+interface RedisTagIndexMigrationResult {
+    migratedKeys: number;
 }
 declare class RedisTagIndex implements CacheTagIndex {
     private readonly client;
     private readonly prefix;
     private readonly scanCount;
     private readonly knownKeysShards;
+    private readonly logger?;
+    private warnedLegacyKnownKeys;
     constructor(options: RedisTagIndexOptions);
     /**
      * Records a key as known without changing tag assignments.
@@ -102,9 +142,13 @@ declare class RedisTagIndex implements CacheTagIndex {
      * Clears all Redis tag-index state under this prefix.
      */
     clear(): Promise<void>;
+    migrateLegacyKnownKeys(): Promise<RedisTagIndexMigrationResult>;
     private scanIndexKeys;
     private knownKeysKeyFor;
+    private knownKeysKeysForRead;
     private knownKeysKeys;
+    private legacyKnownKeysKey;
+    private warnLegacyKnownKeys;
     private keyTagsKey;
     private tagKeysKey;
 }
@@ -746,4 +790,4 @@ declare function createPrometheusMetricsExporter(stacks: CacheStack | Array<{
     name: string;
 }>): () => string;
 
-export { CacheGetOptions, CacheLayer, CacheLayerSetManyEntry, CacheLogger, CacheSerializer, CacheSingleFlightCoordinator, CacheSingleFlightExecutionOptions, CacheStack, CacheTagIndex, CacheWrapOptions, DiskLayer, InvalidationBus, InvalidationMessage, JsonSerializer, type MemcachedClient, MemcachedLayer, MsgpackSerializer, RedisInvalidationBus, RedisLayer, RedisSingleFlightCoordinator, RedisTagIndex, StampedeGuard, cacheGraphqlResolver, createCacheStatsHandler, createCachedMethodDecorator, createExpressCacheMiddleware, createFastifyLayercachePlugin, createOpenTelemetryPlugin, createPrometheusMetricsExporter, createTrpcCacheMiddleware };
+export { CacheGetOptions, CacheLayer, CacheLayerSetManyEntry, CacheLogger, CacheSerializer, CacheSingleFlightCoordinator, CacheSingleFlightExecutionOptions, CacheStack, CacheTagIndex, CacheWrapOptions, DiskLayer, InvalidationBus, InvalidationMessage, JsonSerializer, type MemcachedClient, MemcachedLayer, MsgpackSerializer, RedisGenerationStore, RedisInvalidationBus, RedisLayer, RedisSingleFlightCoordinator, RedisTagIndex, StampedeGuard, cacheGraphqlResolver, createCacheStatsHandler, createCachedMethodDecorator, createExpressCacheMiddleware, createFastifyLayercachePlugin, createOpenTelemetryPlugin, createPrometheusMetricsExporter, createTrpcCacheMiddleware };

package/dist/index.js

@@ -12,12 +12,13 @@ import {
   validateTag,
   validateTags,
   validateTtlPolicy
-} from "./chunk-6X7NV5BG.js";
+} from "./chunk-NBMG7DHT.js";
 import {
   MemoryLayer,
   TagIndex,
-  createHonoCacheMiddleware
-} from "./chunk-IVX6ABFX.js";
+  createHonoCacheMiddleware,
+  normalizeHttpCacheUrl
+} from "./chunk-5CIBABDH.js";
 import {
   PatternMatcher,
   createStoredValueEnvelope,
@@ -913,7 +914,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 +975,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);
     }
   }
 };
@@ -1109,22 +1115,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()) {
@@ -1248,7 +1260,15 @@ var CacheStackReader = class {
       }
       await this.options.sleep(pollIntervalMs);
     }
-    return this.fetchAndPopulate(key, fetcher, options, expectedClearEpoch, expectedKeyEpoch, fetcherContext);
+    if (!this.options.singleFlightCoordinator) {
+      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)
+    );
   }
   async fetchAndPopulate(key, fetcher, options, expectedClearEpoch, expectedKeyEpoch, fetcherContext = {
     key,
@@ -2163,6 +2183,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 +2273,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);
     }
   }
 };
@@ -3112,6 +3133,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.
@@ -3669,12 +3696,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 +3763,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 +3803,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 +3814,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 +3843,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 +3879,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 +3985,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 +4001,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 +4018,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 +4586,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 +4604,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 +4680,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."
       );
@@ -4798,7 +4913,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) {
@@ -5297,6 +5412,7 @@ export {
   MemoryLayer,
   MsgpackSerializer,
   PatternMatcher,
+  RedisGenerationStore,
   RedisInvalidationBus,
   RedisLayer,
   RedisSingleFlightCoordinator,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "layercache",
-  "version": "2.1.0",
+  "version": "3.0.0",
   "description": "Production-ready multi-layer caching for Node.js. Stack memory + Redis + disk behind one API with stampede prevention, tag invalidation, stale serving, and full observability.",
   "keywords": [
     "cache",