layercache 2.0.0 → 3.0.0

package/README.md

@@ -3,7 +3,7 @@
 </p>
 
 <p align="center">
-  <img src="./logo.png" width="520" alt="layercache logo">
+  <img src="./layercache-stampede.gif" width="930" alt="layercache stampede prevention demo">
 </p>
 
 <h1 align="center">layercache</h1>
@@ -24,7 +24,7 @@
 </p>
 
 <p align="center">
-  <a href="https://layercache.flyingsquirrel.me">Website</a>&nbsp;&nbsp;|&nbsp;&nbsp;
+  <a href="https://flyingsquirrel0419.github.io/layercache">Website</a>&nbsp;&nbsp;|&nbsp;&nbsp;
   <a href="#-quick-start">Quick Start</a>&nbsp;&nbsp;|&nbsp;&nbsp;
   <a href="#-performance">Performance</a>&nbsp;&nbsp;|&nbsp;&nbsp;
   <a href="./docs/api.md">API Reference</a>&nbsp;&nbsp;|&nbsp;&nbsp;
@@ -53,6 +53,18 @@ layercache is a multi-layer cache (Memory → Redis → Disk) for Node.js. Stamp
 
 ---
 
+## What's New in 3.0
+
+- `RedisTagIndex` uses 16 known-key shards by default. Existing Redis tag indexes that still use the legacy `<prefix>:keys` set should be migrated with `npx layercache migrate-tag-index`.
+- Production CLI commands reject plaintext `redis://` URLs unless `--allow-plaintext` is passed. Prefer `rediss://` for production Redis endpoints.
+- Express and Hono implicit URL cache keys now strip sensitive query parameters before caching, and non-2xx JSON responses are not cached by default.
+- Redis-backed generation persistence is available through `RedisGenerationStore`, and `CacheStack.getGeneration()` exposes the active generation.
+- The docs site now runs on Rspress and GitHub Pages.
+
+See the [changelog](./CHANGELOG.md) and [migration guide](./docs/migration-guide.md) before upgrading an existing deployment.
+
+---
+
 ## Quick Start
 
 ```bash
@@ -363,7 +375,7 @@ layercache is built for multi-instance production environments:
 
 - **Redis single-flight** - dedup misses across instances with distributed locks
 - **Redis invalidation bus** - pub/sub-based L1 invalidation for memory consistency
-- **Redis tag index** - shared tag tracking with optional sharding
+- **Redis tag index** - shared tag tracking with 16 known-key shards by default
 - **Snapshot persistence** - export/import state between instances
 
 <details>
@@ -375,9 +387,13 @@ import {
   RedisInvalidationBus, RedisTagIndex, RedisSingleFlightCoordinator
 } from 'layercache'
 
-const redis = new Redis()
-const bus = new RedisInvalidationBus({ publisher: redis, subscriber: new Redis() })
-const tagIndex = new RedisTagIndex({ client: redis, prefix: 'myapp:tags' })
+const redis = new Redis(process.env.REDIS_URL)
+const bus = new RedisInvalidationBus({
+  publisher: redis,
+  subscriber: new Redis(process.env.REDIS_URL),
+  signingSecret: process.env.LAYERCACHE_INVALIDATION_SECRET
+})
+const tagIndex = new RedisTagIndex({ client: redis, prefix: 'myapp:tags', knownKeysShards: 16 })
 const coordinator = new RedisSingleFlightCoordinator({ client: redis })
 
 const cache = new CacheStack(

package/dist/{chunk-FFZCC7EQ.js → chunk-5CIBABDH.js}

@@ -12,6 +12,9 @@ var MemoryLayer = class {
   onEvict;
   entries = /* @__PURE__ */ new Map();
   cleanupTimer;
+  /**
+   * Creates an in-memory cache layer.
+   */
   constructor(options = {}) {
     this.name = options.name ?? "memory";
     this.defaultTtl = options.ttl;
@@ -25,10 +28,16 @@ var MemoryLayer = class {
       this.cleanupTimer.unref?.();
     }
   }
+  /**
+   * Reads and unwraps a fresh value from memory.
+   */
   async get(key) {
     const value = await this.getEntry(key);
     return unwrapStoredValue(value);
   }
+  /**
+   * Reads the raw stored value or envelope from memory.
+   */
   async getEntry(key) {
     const entry = this.entries.get(key);
     if (!entry) {
@@ -47,12 +56,21 @@ var MemoryLayer = class {
     }
     return entry.value;
   }
+  /**
+   * Reads many raw entries from memory.
+   */
   async getMany(keys) {
     return Promise.all(keys.map((key) => this.getEntry(key)));
   }
+  /**
+   * Writes many entries to memory.
+   */
   async setMany(entries) {
     await Promise.all(entries.map((entry) => this.set(entry.key, entry.value, entry.ttl)));
   }
+  /**
+   * Stores a value in memory using the provided TTL or layer default TTL.
+   */
   async set(key, value, ttl = this.defaultTtl) {
     this.entries.delete(key);
     this.entries.set(key, {
@@ -65,6 +83,9 @@ var MemoryLayer = class {
       this.evict();
     }
   }
+  /**
+   * Returns true when the key exists and has not expired.
+   */
   async has(key) {
     const entry = this.entries.get(key);
     if (!entry) {
@@ -76,6 +97,9 @@ var MemoryLayer = class {
     }
     return true;
   }
+  /**
+   * Returns remaining TTL in milliseconds, or null when absent or non-expiring.
+   */
   async ttl(key) {
     const entry = this.entries.get(key);
     if (!entry) {
@@ -90,40 +114,67 @@ var MemoryLayer = class {
     }
     return Math.max(0, Math.ceil(entry.expiresAt - Date.now()));
   }
+  /**
+   * Returns the number of currently retained, non-expired entries.
+   */
   async size() {
     this.pruneExpired();
     return this.entries.size;
   }
+  /**
+   * Deletes a key from memory.
+   */
   async delete(key) {
     this.entries.delete(key);
   }
+  /**
+   * Deletes multiple keys from memory.
+   */
   async deleteMany(keys) {
     for (const key of keys) {
       this.entries.delete(key);
     }
   }
+  /**
+   * Removes all entries from memory.
+   */
   async clear() {
     this.entries.clear();
   }
+  /**
+   * Health check hook that always succeeds for the in-process layer.
+   */
   async ping() {
     return true;
   }
+  /**
+   * Stops the cleanup timer, when one is active.
+   */
   async dispose() {
     if (this.cleanupTimer) {
       clearInterval(this.cleanupTimer);
       this.cleanupTimer = void 0;
     }
   }
+  /**
+   * Returns all currently retained, non-expired keys.
+   */
   async keys() {
     this.pruneExpired();
     return [...this.entries.keys()];
   }
+  /**
+   * Visits all currently retained, non-expired keys.
+   */
   async forEachKey(visitor) {
     this.pruneExpired();
     for (const key of this.entries.keys()) {
       await visitor(key);
     }
   }
+  /**
+   * Exports memory entries for process-local snapshots.
+   */
   exportState() {
     this.pruneExpired();
     return [...this.entries.entries()].map(([key, entry]) => ({
@@ -132,6 +183,9 @@ var MemoryLayer = class {
       expiresAt: entry.expiresAt
     }));
   }
+  /**
+   * Imports entries previously produced by `exportState()`.
+   */
   importState(entries) {
     for (const entry of entries) {
       if (entry.expiresAt !== null && entry.expiresAt <= Date.now()) {
@@ -202,10 +256,16 @@ var TagIndex = class {
   constructor(options = {}) {
     this.maxKnownKeys = options.maxKnownKeys ?? 1e5;
   }
+  /**
+   * Records a key as known without changing tag assignments.
+   */
   async touch(key) {
     this.insertKnownKey(key);
     this.pruneKnownKeysIfNeeded();
   }
+  /**
+   * Replaces the tags associated with a key and records the key as known.
+   */
   async track(key, tags) {
     this.insertKnownKey(key);
     this.pruneKnownKeysIfNeeded();
@@ -226,17 +286,29 @@ var TagIndex = class {
       this.tagToKeys.set(tag, keys);
     }
   }
+  /**
+   * Removes a key from all tag mappings and known-key tracking.
+   */
   async remove(key) {
     this.removeKey(key);
   }
+  /**
+   * Returns keys currently associated with a tag.
+   */
   async keysForTag(tag) {
     return [...this.tagToKeys.get(tag) ?? /* @__PURE__ */ new Set()];
   }
+  /**
+   * Visits keys currently associated with a tag.
+   */
   async forEachKeyForTag(tag, visitor) {
     for (const key of this.tagToKeys.get(tag) ?? /* @__PURE__ */ new Set()) {
       await visitor(key);
     }
   }
+  /**
+   * Returns known keys that start with a prefix.
+   */
   async keysForPrefix(prefix) {
     const node = this.findNode(prefix);
     if (!node) {
@@ -246,6 +318,9 @@ var TagIndex = class {
     this.collectFromNode(node, prefix, matches);
     return matches;
   }
+  /**
+   * Visits known keys that start with a prefix.
+   */
   async forEachKeyForPrefix(prefix, visitor) {
     const node = this.findNode(prefix);
     if (!node) {
@@ -253,20 +328,32 @@ var TagIndex = class {
     }
     await this.visitFromNode(node, prefix, visitor);
   }
+  /**
+   * Returns the tags currently associated with a key.
+   */
   async tagsForKey(key) {
     return [...this.keyToTags.get(key) ?? /* @__PURE__ */ new Set()];
   }
+  /**
+   * Returns known keys matching a wildcard pattern.
+   */
   async matchPattern(pattern) {
     const matches = /* @__PURE__ */ new Set();
     this.collectPatternMatches(this.root, "", pattern, 0, matches, /* @__PURE__ */ new Set(), 0);
     return [...matches];
   }
+  /**
+   * Visits known keys matching a wildcard pattern.
+   */
   async forEachKeyMatchingPattern(pattern, visitor) {
     const matches = await this.matchPattern(pattern);
     for (const key of matches) {
       await visitor(key);
     }
   }
+  /**
+   * Clears all tag and known-key index state.
+   */
   async clear() {
     this.tagToKeys.clear();
     this.keyToTags.clear();
@@ -284,6 +371,9 @@ var TagIndex = class {
   }
   insertKnownKey(key) {
     const isNew = !this.knownKeys.has(key);
+    if (!isNew) {
+      this.knownKeys.delete(key);
+    }
     this.knownKeys.set(key, Date.now());
     if (!isNew) {
       return;
@@ -382,13 +472,13 @@ var TagIndex = class {
     if (this.maxKnownKeys === void 0 || this.knownKeys.size <= this.maxKnownKeys) {
       return;
     }
-    const sorted = [...this.knownKeys.entries()].sort((a, b) => a[1] - b[1]);
     const toRemove = Math.ceil(this.maxKnownKeys * 0.1);
-    for (let i = 0; i < toRemove && i < sorted.length; i += 1) {
-      const entry = sorted[i];
-      if (entry) {
-        this.removeKey(entry[0]);
+    for (let i = 0; i < toRemove; i += 1) {
+      const oldestKey = this.knownKeys.keys().next().value;
+      if (oldestKey === void 0) {
+        break;
       }
+      this.removeKnownKey(oldestKey);
     }
   }
   removeKey(key) {
@@ -439,6 +529,41 @@ var TagIndex = class {
   }
 };
 
+// src/integrations/httpCacheKeys.ts
+var SENSITIVE_QUERY_PARAMETERS = /* @__PURE__ */ new Set([
+  "access_token",
+  "api_key",
+  "apikey",
+  "auth",
+  "authorization",
+  "code",
+  "credentials",
+  "id_token",
+  "jwt",
+  "password",
+  "private_key",
+  "refresh_token",
+  "secret",
+  "session",
+  "sessionid",
+  "session_id",
+  "token"
+]);
+function normalizeHttpCacheUrl(url) {
+  try {
+    const parsed = new URL(url, "http://localhost");
+    for (const name of [...parsed.searchParams.keys()]) {
+      if (SENSITIVE_QUERY_PARAMETERS.has(name.toLowerCase())) {
+        parsed.searchParams.delete(name);
+      }
+    }
+    parsed.searchParams.sort();
+    return parsed.pathname + parsed.search;
+  } catch {
+    return url;
+  }
+}
+
 // src/integrations/hono.ts
 function createHonoCacheMiddleware(cache, options = {}) {
   const allowedMethods = new Set((options.methods ?? ["GET"]).map((method) => method.toUpperCase()));
@@ -453,39 +578,44 @@ function createHonoCacheMiddleware(cache, options = {}) {
       return;
     }
     const rawPath = context.req.path ?? context.req.url ?? "/";
-    const key = options.keyResolver ? options.keyResolver(context.req) : `${method}:${normalizeUrl(rawPath)}`;
+    const key = options.keyResolver ? options.keyResolver(context.req) : `${method}:${normalizeHttpCacheUrl(rawPath)}`;
     const cached = await cache.get(key, void 0, options);
     if (cached !== null) {
       context.header?.("x-cache", "HIT");
       context.header?.("content-type", "application/json; charset=utf-8");
       return context.json(cached);
     }
+    let currentStatus;
+    const originalStatus = context.status?.bind(context);
+    if (originalStatus) {
+      context.status = (status) => {
+        currentStatus = status;
+        return originalStatus(status);
+      };
+    }
     const originalJson = context.json.bind(context);
     context.json = (body, status) => {
       context.header?.("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(status ?? currentStatus)) {
+        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 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;
 }
 
 export {
   MemoryLayer,
   TagIndex,
+  normalizeHttpCacheUrl,
   createHonoCacheMiddleware
 };

package/dist/{chunk-7KMKQ6QZ.js → chunk-NBMG7DHT.js}

@@ -140,20 +140,30 @@ function validateContextEntryOptions(name, options) {
 }
 
 // src/invalidation/RedisTagIndex.ts
+var DEFAULT_KNOWN_KEYS_SHARDS = 16;
 var RedisTagIndex = class {
   client;
   prefix;
   scanCount;
   knownKeysShards;
+  logger;
+  warnedLegacyKnownKeys = false;
   constructor(options) {
     this.client = options.client;
     this.prefix = options.prefix ?? "layercache:tag-index";
     this.scanCount = options.scanCount ?? 100;
     this.knownKeysShards = normalizeKnownKeysShards(options.knownKeysShards);
+    this.logger = options.logger;
   }
+  /**
+   * Records a key as known without changing tag assignments.
+   */
   async touch(key) {
     await this.client.sadd(this.knownKeysKeyFor(key), key);
   }
+  /**
+   * Replaces the tags associated with a key and records the key as known.
+   */
   async track(key, tags) {
     const keyTagsKey = this.keyTagsKey(key);
     const existingTags = await this.client.smembers(keyTagsKey);
@@ -171,20 +181,32 @@ var RedisTagIndex = class {
     }
     await pipeline.exec();
   }
+  /**
+   * Removes a key from all tag mappings and known-key tracking.
+   */
   async remove(key) {
     const keyTagsKey = this.keyTagsKey(key);
     const existingTags = await this.client.smembers(keyTagsKey);
     const pipeline = this.client.pipeline();
     pipeline.srem(this.knownKeysKeyFor(key), key);
+    if (this.knownKeysShards > 1) {
+      pipeline.srem(this.legacyKnownKeysKey(), key);
+    }
     pipeline.del(keyTagsKey);
     for (const tag of existingTags) {
       pipeline.srem(this.tagKeysKey(tag), key);
     }
     await pipeline.exec();
   }
+  /**
+   * Returns keys currently associated with a tag.
+   */
   async keysForTag(tag) {
     return this.client.smembers(this.tagKeysKey(tag));
   }
+  /**
+   * Visits keys currently associated with a tag.
+   */
   async forEachKeyForTag(tag, visitor) {
     let cursor = "0";
     const tagKey = this.tagKeysKey(tag);
@@ -196,38 +218,56 @@ var RedisTagIndex = class {
       }
     } while (cursor !== "0");
   }
+  /**
+   * Returns known keys that start with a prefix.
+   */
   async keysForPrefix(prefix) {
-    const matches = [];
-    for (const knownKeysKey of this.knownKeysKeys()) {
+    const matches = /* @__PURE__ */ new Set();
+    for (const knownKeysKey of await this.knownKeysKeysForRead()) {
       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)));
+        for (const key of keys) {
+          if (key.startsWith(prefix)) {
+            matches.add(key);
+          }
+        }
       } while (cursor !== "0");
     }
-    return matches;
+    return [...matches];
   }
+  /**
+   * Visits known keys that start with a prefix.
+   */
   async forEachKeyForPrefix(prefix, visitor) {
-    for (const knownKeysKey of this.knownKeysKeys()) {
+    const visited = /* @__PURE__ */ new Set();
+    for (const knownKeysKey of await this.knownKeysKeysForRead()) {
       let cursor = "0";
       do {
         const [nextCursor, keys] = await this.client.sscan(knownKeysKey, cursor, "COUNT", this.scanCount);
         cursor = nextCursor;
         for (const key of keys) {
-          if (key.startsWith(prefix)) {
+          if (key.startsWith(prefix) && !visited.has(key)) {
+            visited.add(key);
             await visitor(key);
           }
         }
       } while (cursor !== "0");
     }
   }
+  /**
+   * Returns the tags currently associated with a key.
+   */
   async tagsForKey(key) {
     return this.client.smembers(this.keyTagsKey(key));
   }
+  /**
+   * Returns known keys matching a wildcard pattern.
+   */
   async matchPattern(pattern) {
-    const matches = [];
-    for (const knownKeysKey of this.knownKeysKeys()) {
+    const matches = /* @__PURE__ */ new Set();
+    for (const knownKeysKey of await this.knownKeysKeysForRead()) {
       let cursor = "0";
       do {
         const [nextCursor, keys] = await this.client.sscan(
@@ -239,13 +279,21 @@ var RedisTagIndex = class {
           this.scanCount
         );
         cursor = nextCursor;
-        matches.push(...keys.filter((key) => PatternMatcher.matches(pattern, key)));
+        for (const key of keys) {
+          if (PatternMatcher.matches(pattern, key)) {
+            matches.add(key);
+          }
+        }
       } while (cursor !== "0");
     }
-    return matches;
+    return [...matches];
   }
+  /**
+   * Visits known keys matching a wildcard pattern.
+   */
   async forEachKeyMatchingPattern(pattern, visitor) {
-    for (const knownKeysKey of this.knownKeysKeys()) {
+    const visited = /* @__PURE__ */ new Set();
+    for (const knownKeysKey of await this.knownKeysKeysForRead()) {
       let cursor = "0";
       do {
         const [nextCursor, keys] = await this.client.sscan(
@@ -258,13 +306,17 @@ var RedisTagIndex = class {
         );
         cursor = nextCursor;
         for (const key of keys) {
-          if (PatternMatcher.matches(pattern, key)) {
+          if (PatternMatcher.matches(pattern, key) && !visited.has(key)) {
+            visited.add(key);
             await visitor(key);
           }
         }
       } while (cursor !== "0");
     }
   }
+  /**
+   * Clears all Redis tag-index state under this prefix.
+   */
   async clear() {
     const indexKeys = await this.scanIndexKeys();
     if (indexKeys.length === 0) {
@@ -272,6 +324,31 @@ var RedisTagIndex = class {
     }
     await this.client.del(...indexKeys);
   }
+  async migrateLegacyKnownKeys() {
+    if (this.knownKeysShards === 1) {
+      return { migratedKeys: 0 };
+    }
+    const legacyKey = this.legacyKnownKeysKey();
+    let cursor = "0";
+    let migratedKeys = 0;
+    do {
+      const [nextCursor, keys] = await this.client.sscan(legacyKey, cursor, "COUNT", this.scanCount);
+      cursor = nextCursor;
+      if (keys.length === 0) {
+        continue;
+      }
+      const pipeline = this.client.pipeline();
+      for (const key of keys) {
+        pipeline.sadd(this.knownKeysKeyFor(key), key);
+      }
+      await pipeline.exec();
+      migratedKeys += keys.length;
+    } while (cursor !== "0");
+    if (migratedKeys > 0) {
+      await this.client.del(legacyKey);
+    }
+    return { migratedKeys };
+  }
   async scanIndexKeys() {
     const matches = [];
     let cursor = "0";
@@ -289,12 +366,40 @@ var RedisTagIndex = class {
     }
     return `${this.prefix}:keys:${simpleHash(key) % this.knownKeysShards}`;
   }
+  async knownKeysKeysForRead() {
+    if (this.knownKeysShards === 1) {
+      return [this.legacyKnownKeysKey()];
+    }
+    const shardedKeys = this.knownKeysKeys();
+    const legacyKey = this.legacyKnownKeysKey();
+    const legacyExists = await this.client.exists(legacyKey) > 0;
+    if (!legacyExists) {
+      return shardedKeys;
+    }
+    this.warnLegacyKnownKeys(legacyKey);
+    return [legacyKey, ...shardedKeys];
+  }
   knownKeysKeys() {
     if (this.knownKeysShards === 1) {
       return [`${this.prefix}:keys`];
     }
     return Array.from({ length: this.knownKeysShards }, (_, index) => `${this.prefix}:keys:${index}`);
   }
+  legacyKnownKeysKey() {
+    return `${this.prefix}:keys`;
+  }
+  warnLegacyKnownKeys(legacyKey) {
+    if (this.warnedLegacyKnownKeys) {
+      return;
+    }
+    this.warnedLegacyKnownKeys = true;
+    const message = "RedisTagIndex detected a legacy RedisTagIndex known-key set. Run `layercache migrate-tag-index` to migrate keys into the sharded layout.";
+    if (this.logger?.warn) {
+      this.logger.warn(message, { legacyKey, knownKeysShards: this.knownKeysShards });
+      return;
+    }
+    console.warn(`[layercache] ${message}`, { legacyKey, knownKeysShards: this.knownKeysShards });
+  }
   keyTagsKey(key) {
     return `${this.prefix}:key:${encodeURIComponent(key)}`;
   }
@@ -304,7 +409,7 @@ var RedisTagIndex = class {
 };
 function normalizeKnownKeysShards(value) {
   if (value === void 0) {
-    return 1;
+    return DEFAULT_KNOWN_KEYS_SHARDS;
   }
   if (!Number.isInteger(value) || value <= 0) {
     throw new Error("RedisTagIndex.knownKeysShards must be a positive integer.");