@leejpsd/nextjs-cache-handler 0.3.4 → 0.4.1

package/CHANGELOG.md

@@ -1,5 +1,47 @@
 # Changelog
 
+## 0.4.1
+
+### Patch Changes
+
+- [`8555fbe`](https://github.com/leejpsd/nextjs-cache-handler/commit/8555fbeb10c8681f101f13157a078b0a1e3fcea5) Thanks [@leejpsd](https://github.com/leejpsd)! - Fix ISR record serialization writing Buffers as JSON byte arrays instead of base64.
+
+  `Buffer.prototype.toJSON` runs before a `JSON.stringify` replacer sees the value, so the base64 envelope branch was unreachable and every Buffer field (rendered HTML, RSC payloads, PPR segment data) was stored as `{ type: "Buffer", data: [...] }` — roughly 2.8x larger than base64. The replacer now reads the pre-`toJSON` original via `this[key]`.
+
+  No migration needed: the reviver has always accepted both shapes, so records written by either version deserialize correctly in both directions.
+
+## 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

package/README.md

@@ -31,6 +31,11 @@ troubleshooting playbook ships in the package (`AGENTS.md`,
 `skills/nextjs-redis-cache/SKILL.md`) and via
 `npx skills add leejpsd/nextjs-cache-handler`.
 
+For cache operations from your agent (health, tag state, safe invalidation),
+the companion MCP server is on the official registry as
+`io.github.leejpsd/nextjs-cache-handler-mcp` — or one command:
+`npx nextjs-cache-handler init --yes` wires handlers, rules, and `.mcp.json` together.
+
 ---
 
 The Redis cache handler for **Next.js 15/16** that ships **both** `cacheHandler`
@@ -245,8 +250,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.
@@ -261,7 +268,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" } });