layercache 2.1.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-IVX6ABFX.js → chunk-5CIBABDH.js}

@@ -371,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;
@@ -469,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) {
@@ -526,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()));
@@ -540,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-6X7NV5BG.js → chunk-NBMG7DHT.js}

@@ -140,16 +140,20 @@ 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.
@@ -185,6 +189,9 @@ var RedisTagIndex = class {
     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);
@@ -215,28 +222,34 @@ var RedisTagIndex = class {
    * 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);
           }
         }
@@ -253,8 +266,8 @@ var RedisTagIndex = class {
    * 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(
@@ -266,16 +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(
@@ -288,7 +306,8 @@ 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);
           }
         }
@@ -305,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";
@@ -322,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)}`;
   }
@@ -337,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.");