@leejpsd/nextjs-cache-handler 0.3.3 → 0.4.0

package/AGENTS.md

@@ -0,0 +1,33 @@
+# @leejpsd/nextjs-cache-handler — notes for AI agents
+
+Redis cache handler for **self-hosted** Next.js 15/16. Ships BOTH interfaces:
+`cacheHandler` (ISR, Next 15+16) and `cacheHandlers` (`'use cache'`,
+Next >= 16.1.5). Not for Vercel-hosted apps.
+
+**Full agent guidance:** `skills/nextjs-redis-cache/SKILL.md` in this package
+(also installable via `npx skills add leejpsd/nextjs-cache-handler`).
+**Agent-executable setup:**
+https://raw.githubusercontent.com/leejpsd/nextjs-cache-handler/main/setup-instructions/setup.md
+
+## Rules that prevent the most common mistakes
+
+1. `revalidateTag(tag, "max")` is SOFT = stale-while-revalidate: instant
+   stale serve + background re-render, cross-instance convergence in ~1-2s.
+   Brief stale content is BY DESIGN — not a bug. `updateTag(tag)` is HARD =
+   delete + blocking regeneration. Requires version >= 0.3.3.
+2. `cacheMaxMemorySize: 0` in next.config is mandatory for multi-instance
+   correctness. Do not remove it.
+3. `DEPLOYMENT_VERSION` env must exist at RUNTIME (Docker runner stage).
+   Missing → cross-deploy cache bleed / static chunk 404s.
+4. Redis Cluster needs `hashTag: true`; TLS via `rediss://` URLs.
+5. Build-time `ECONNREFUSED` toward Redis is expected (build-phase gate) —
+   only investigate if the build fails.
+6. Redis outages degrade to a bounded in-memory fallback with automatic
+   reconnect (backoff 1s→30s). Do not wrap cache calls in extra try/catch.
+7. Wiring shape: two CJS wrapper files + `require.resolve` in next.config —
+   see README "Quick start" or the setup URL above.
+
+Entry points: `/incremental` (ISR), `/cache-components` ('use cache'),
+`/client/redis`, `/client/ioredis` (incl. cluster/sentinel), `/ops`
+(metric snapshot), `/otel` (OpenTelemetry emitter). API details: README.md
+and https://github.com/leejpsd/nextjs-cache-handler/blob/main/docs/api.md

package/CHANGELOG.md

@@ -1,5 +1,48 @@
 # Changelog
 
+## 0.4.0
+
+### Minor Changes
+
+- [#7](https://github.com/leejpsd/nextjs-cache-handler/pull/7) [`bf047c9`](https://github.com/leejpsd/nextjs-cache-handler/commit/bf047c937985dafabed7c60ab1972a749a8f3b9f) Thanks [@leejpsd](https://github.com/leejpsd)! - Build-output cache seeding: `seedBuildOutput()` (new `/seed` entry point) and
+  `npx nextjs-cache-handler seed` walk `.next/` after a build and insert
+  prerendered App Router routes (including PPR segment data), Pages Router
+  routes, and fetch-cache entries into Redis in the handler's own record
+  format — with NX semantics so entries already written by live instances are
+  never overwritten. A fresh deployment's first requests are cache HITs
+  instead of a regeneration stampede (verified on a real Next 16 app: cold
+  server + seeded Redis → first request `x-nextjs-cache: HIT`). The
+  `RedisClientLike.set` contract gains an optional `NX` flag.
+
+- [#7](https://github.com/leejpsd/nextjs-cache-handler/pull/7) [`1e57e03`](https://github.com/leejpsd/nextjs-cache-handler/commit/1e57e03020926933f524796645b279d004dddf2a) Thanks [@leejpsd](https://github.com/leejpsd)! - New `nextjs-cache-handler` CLI (zero-dependency): `init` detects the Next.js
+  version and Redis client, generates the handler wrapper shims, shows the
+  next.config keys to add (never edits it), appends env templates, and injects
+  the agent rules block into CLAUDE.md/AGENTS.md idempotently (`--yes` to
+  apply, `--skills` to install the agent skill locally). `doctor` verifies
+  Redis connectivity, inspects cache key namespaces, and runs a write/read
+  round-trip — the first command an agent should reach for when debugging.
+
+- [#7](https://github.com/leejpsd/nextjs-cache-handler/pull/7) [`6cd5901`](https://github.com/leejpsd/nextjs-cache-handler/commit/6cd59010d30b55e8a5f9b99db8ec53b0e64e03ce) Thanks [@leejpsd](https://github.com/leejpsd)! - Opt-in push-based tag propagation (`tagPubSub: true`, plural handler):
+  `updateTags()` publishes invalidations on a namespaced channel and every
+  instance maintains a subscription on a dedicated duplicate connection,
+  updating its local tag mirror in ~3 ms (measured cross-instance over real
+  Redis with both redis@5 and ioredis) instead of waiting for the next
+  `refreshTags()` scan (~seconds). The scan keeps running as the consistency
+  safety net, so a dropped subscription degrades to the previous behavior —
+  never to staleness. Cluster clients fall back to polling with a one-time
+  warning. `RedisClientLike` gains optional `publish`/`subscribe`.
+
+## 0.3.4
+
+### Patch Changes
+
+- [`79e112b`](https://github.com/leejpsd/nextjs-cache-handler/commit/79e112bc03249e6e042da717c4558de733cc62f0) Thanks [@leejpsd](https://github.com/leejpsd)! - Ship agent-native assets in the package: `AGENTS.md` (agent guidance
+  discovered via node_modules scans), an agent skill
+  (`skills/nextjs-redis-cache/SKILL.md` — decision tables, invalidation
+  semantics, troubleshooting playbook), agent-executable setup instructions
+  (`setup-instructions/setup.md`), a project rules block (`rules/`), and
+  `llms.txt`. README gains a "For AI agents" section. No runtime code changes.
+
 ## 0.3.3
 
 ### Patch Changes

package/README.md

@@ -16,6 +16,23 @@
 > Sentinel** support, a built-in **OpenTelemetry emitter** at `/otel`, and an
 > LRU-bounded memory fallback.
 
+## 🤖 For AI agents
+
+Working with Claude Code / Codex / Cursor? Give your agent this URL and it
+will install and wire everything (version detection, wrapper files,
+next.config patch, verification):
+
+```
+https://raw.githubusercontent.com/leejpsd/nextjs-cache-handler/main/setup-instructions/setup.md
+```
+
+An agent skill with decision tables, invalidation semantics, and a
+troubleshooting playbook ships in the package (`AGENTS.md`,
+`skills/nextjs-redis-cache/SKILL.md`) and via
+`npx skills add leejpsd/nextjs-cache-handler`.
+
+---
+
 The Redis cache handler for **Next.js 15/16** that ships **both** `cacheHandler`
 (ISR / Pages Router) **and** `cacheHandlers` (`'use cache'` directive,
 `cacheComponents: true`) — the area where
@@ -228,8 +245,10 @@ Full reference: [`docs/api.md`](./docs/api.md).
       on the same hash slot. Without `hashTag`, cluster deployments will hit
       `CROSSSLOT Keys in request don't hash to the same slot`. The flag wraps
       the namespace in `{}` so every key for a given deploy hashes together.
-      Cluster support is implemented but **not yet load-tested at production
-      scale**; PRs welcome.
+      Cluster support is validated by a dedicated e2e suite against a real
+      3-master cluster (`npm run test:cluster`, also in CI) — covering the
+      multi-key Lua scripts, per-master SCAN propagation, and both handlers.
+      Not yet load-tested at production scale.
 - [ ] **Redis `maxmemory-policy: allkeys-lru` or `noeviction`** — if you need
       bounded memory, choose `allkeys-lru`. Otherwise `noeviction` keeps
       tag indices intact.
@@ -244,7 +263,7 @@ Full reference: [`docs/api.md`](./docs/api.md).
 | Service | How to use | Tested? |
 |---|---|---|
 | **Self-hosted Redis 7+** | `{ type: "redis", url }` or `{ type: "ioredis", url }` | ✅ AWS ElastiCache 24h soak |
-| **Redis Cluster** | `{ type: "cluster", nodes }` + `hashTag: true` | unit-tested, not yet load-tested at scale |
+| **Redis Cluster** | `{ type: "cluster", nodes }` + `hashTag: true` | ✅ e2e-tested against a real 3-master cluster (CI); not yet load-tested at scale |
 | **Upstash Redis** | `{ type: "redis", url: "rediss://..." }` (TLS auto-detected) | not yet validated, expected to work via the standard Redis protocol |
 | **AWS ElastiCache (replication group)** | `{ type: "redis", url: "rediss://..." }` | ✅ reference deployment (re-verified 2026-08-01, Seoul) |
 | **Redis Sentinel** | `{ type: "sentinel", sentinels, name }` | ✅ local master/replica failover drill |

package/bin/cli.cjs

@@ -0,0 +1,10 @@
+#!/usr/bin/env node
+// Thin launcher for the built CLI (keeps the tsup build shebang-free).
+const { main } = require("../dist/cli/index.cjs");
+main().then(
+  (code) => process.exit(code),
+  (err) => {
+    console.error("[error]", err && err.message ? err.message : err);
+    process.exit(1);
+  }
+);

package/dist/cache-components/index.cjs

@@ -53,7 +53,40 @@ __export(adapter_redis_exports, {
   createRedisV5Client: () => createRedisV5Client
 });
 function adaptRedisV5(client) {
-  return client;
+  const like = client;
+  like.dispose = () => {
+    try {
+      client.destroy();
+    } catch {
+    }
+  };
+  like.subscribe = async (channel, onMessage, onDown) => {
+    const sub = client.duplicate();
+    const teardown = () => {
+      try {
+        sub.destroy();
+      } catch {
+      }
+    };
+    let down = false;
+    const markDown = () => {
+      if (down) return;
+      down = true;
+      teardown();
+      onDown?.();
+    };
+    sub.on("error", markDown);
+    sub.on("end", markDown);
+    try {
+      await sub.connect();
+      await sub.subscribe(channel, (message) => onMessage(message));
+    } catch (err) {
+      teardown();
+      throw err;
+    }
+    return async () => teardown();
+  };
+  return like;
 }
 function createRedisV5Client(config) {
   const { createClient } = nodeRequire("redis");
@@ -96,7 +129,12 @@ function adapt(client, isClusterClient = false) {
       }
     },
     get: (k) => client.get(k),
-    set: (k, v, opts) => opts?.EX !== void 0 ? client.set(k, v, "EX", opts.EX) : client.set(k, v),
+    set: (k, v, opts) => {
+      const args = [];
+      if (opts?.EX !== void 0) args.push("EX", opts.EX);
+      if (opts?.NX) args.push("NX");
+      return client.set(k, v, ...args);
+    },
     del: async (keys) => {
       const arr = Array.isArray(keys) ? keys : [keys];
       if (arr.length === 0) return 0;
@@ -167,6 +205,40 @@ function adapt(client, isClusterClient = false) {
       client.on(event, listener);
       return client;
     },
+    publish: (channel, message) => client.publish(channel, message),
+    ...isClusterClient ? {} : {
+      subscribe: async (channel, onMessage, onDown) => {
+        const sub = client.duplicate();
+        let down = false;
+        const markDown = () => {
+          if (down) return;
+          down = true;
+          try {
+            sub.disconnect();
+          } catch {
+          }
+          onDown?.();
+        };
+        sub.on("error", markDown);
+        sub.on("end", markDown);
+        try {
+          if (sub.status !== "ready" && sub.status !== "connecting") {
+            await sub.connect();
+          }
+          await sub.subscribe(channel);
+        } catch (err) {
+          markDown();
+          throw err;
+        }
+        sub.on("message", (ch, message) => {
+          if (ch === channel) onMessage(message);
+        });
+        return async () => {
+          down = true;
+          sub.disconnect();
+        };
+      }
+    },
     dispose: () => {
       client.disconnect();
     }
@@ -817,6 +889,7 @@ function init(opts) {
       hashTag: opts.hashTag ?? false,
       keyPrefix: opts.keyPrefix ?? DEFAULT_KEY_PREFIX,
       singleFlight: opts.singleFlight ?? false,
+      tagPubSub: opts.tagPubSub ?? false,
       singleFlightLockTtlSec: opts.singleFlightLockTtlSec ?? DEFAULT_LOCK_TTL_SEC,
       rest: opts
     },
@@ -827,6 +900,7 @@ function init(opts) {
     memTags: new MemorySetStore(opts.memoryMaxEntries),
     memTagExp: /* @__PURE__ */ new Map(),
     localTagTimestamps: /* @__PURE__ */ new Map(),
+    pubsub: { active: false, disabled: false, attempting: false, lastAttempt: 0 },
     resolveNs: () => resolveBuildNamespace(opts.buildNamespace),
     instanceId: process.env.HOSTNAME || process.env.ECS_TASK_ID || `pid-${process.pid}`
   };
@@ -904,6 +978,7 @@ function resolveTtlSeconds(entry) {
 async function getImpl(state, cacheKey, softTags) {
   const start = Date.now();
   const useRedis = gateRedis(state);
+  if (useRedis) void ensureTagSubscription(state);
   if (!useRedis && state.opts.fallback === "never") {
     state.emit({ type: "cache.miss", meta: { reason: "no-redis" } });
     return void 0;
@@ -980,8 +1055,11 @@ async function getImpl(state, cacheKey, softTags) {
   if (freshnessTags.length > 0) {
     let mostRecent = 0;
     for (const t of freshnessTags) {
-      const ts = state.localTagTimestamps.get(t);
-      if (ts !== void 0 && ts > mostRecent) mostRecent = ts;
+      const ts = Math.max(
+        state.localTagTimestamps.get(t) ?? 0,
+        state.memTagExp.get(t) ?? 0
+      );
+      if (ts > mostRecent) mostRecent = ts;
     }
     if (mostRecent > envelope.timestamp) {
       if (state.opts.staleWhileRevalidate && partition.freshness !== "expired") {
@@ -1114,10 +1192,68 @@ async function luaSetWithTags(client, state, eKey, payload, ttl, tags) {
     [payload, String(ttl), String(ttl), String(tags.length)]
   );
 }
+function invalChannel(state) {
+  const ns = state.opts.hashTag ? `{${state.resolveNs()}}` : state.resolveNs();
+  return `${state.opts.keyPrefix}inval:${ns}`;
+}
+var SUBSCRIBE_RETRY_MS = 5e3;
+async function ensureTagSubscription(state) {
+  if (!state.opts.tagPubSub || state.pubsub.active || state.pubsub.disabled || state.pubsub.attempting) {
+    return;
+  }
+  const now = Date.now();
+  if (now - state.pubsub.lastAttempt < SUBSCRIBE_RETRY_MS) return;
+  state.pubsub.lastAttempt = now;
+  state.pubsub.attempting = true;
+  try {
+    const client = await state.conn.getOrConnect();
+    if (!client) return;
+    if (typeof client.subscribe !== "function") {
+      state.pubsub.disabled = true;
+      state.logger.warn(
+        "tagPubSub unavailable on this client (no subscribe support, e.g. Cluster) \u2014 falling back to scan-based propagation"
+      );
+      return;
+    }
+    const stop = await client.subscribe(
+      invalChannel(state),
+      (message) => {
+        try {
+          const parsed = JSON.parse(message);
+          if (!Array.isArray(parsed.t) || typeof parsed.ts !== "number") return;
+          for (const tag of parsed.t) {
+            const prev = state.localTagTimestamps.get(tag) ?? 0;
+            if (parsed.ts > prev) state.localTagTimestamps.set(tag, parsed.ts);
+            const prevMem = state.memTagExp.get(tag) ?? 0;
+            if (parsed.ts > prevMem) state.memTagExp.set(tag, parsed.ts);
+          }
+          pruneOldestByTimestamp(state.localTagTimestamps, MAX_LOCAL_TAG_ENTRIES);
+          pruneOldestByTimestamp(state.memTagExp, MAX_LOCAL_TAG_ENTRIES);
+        } catch {
+        }
+      },
+      () => {
+        state.pubsub.active = false;
+      }
+    );
+    state.pubsub.active = true;
+    state.pubsub.stop = async () => {
+      state.pubsub.active = false;
+      await stop();
+    };
+  } catch (err) {
+    state.logger.warn("tagPubSub subscribe failed \u2014 will retry", {
+      message: err.message
+    });
+  } finally {
+    state.pubsub.attempting = false;
+  }
+}
 async function refreshTagsImpl(state) {
   if (!gateRedis(state)) {
     return;
   }
+  void ensureTagSubscription(state);
   try {
     await withAbortSignal(
       "cacheHandlers.refreshTags",
@@ -1275,6 +1411,16 @@ async function updateTagsImpl(state, tags, durations) {
       type: isHardExpire ? "tag.invalidate.hard" : "tag.invalidate.soft",
       meta: { count: tags.length, backend: "redis" }
     });
+    if (state.opts.tagPubSub) {
+      try {
+        const client = await state.conn.getOrConnect();
+        await client?.publish?.(
+          invalChannel(state),
+          JSON.stringify({ t: tags, ts: now })
+        );
+      } catch {
+      }
+    }
   } catch (err) {
     if (err instanceof CacheTimeoutError) {
       state.emit({ type: "redis.timeout", meta: { op: "updateTags" } });