@leejpsd/nextjs-cache-handler 0.1.0 → 0.2.0

package/CHANGELOG.md

@@ -6,6 +6,90 @@ this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.htm
 
 ## [Unreleased]
 
+## [0.2.0] - 2026-05-10
+
+First minor bump. Three differentiators land in this release.
+
+### Added
+
+- **Single-flight refresh lock** (`singleFlight: true`,
+  `singleFlightLockTtlSec: 10`). Opt-in stampede protection at the SWR
+  boundary. Uses the bundled `refresh-tag-lock.lua` script over a Redis
+  SETNX-style lock; only the leader's stale read triggers the
+  background refresh, all others fall through to the follower path.
+  Two new `MetricEvent` types (`cache.stale.refresh.leader`,
+  `cache.stale.refresh.follower`) appear in `onMetric` so operators can
+  verify leadership balance. Lock-acquisition failures are best-effort
+  and always degrade to the safe follower path; the stale entry is
+  served regardless.
+- **OpenTelemetry reference adapter** at
+  [`examples/opentelemetry/`](./examples/opentelemetry/). The library
+  itself stays dependency-free; the example shows the smallest viable
+  wiring of `onMetric` to OTel counters and histograms with bounded
+  cardinality (no cache keys or tag names emitted as attributes).
+- **Integration tests against real Redis 7** (21 scenarios) covering
+  both `redis@5` and `ioredis` adapters. Each adapter runs the same
+  test grid so a regression in either client library is pinpointed
+  immediately. New scripts: `npm run test:integration`,
+  `npm run test:integration:up` / `:down` for the docker-compose
+  fixture.
+- **CI integration job** runs the integration suite against an
+  ephemeral Redis 7 service container on every PR.
+- **GitHub Actions OIDC publish path** in `.github/workflows/release.yml`
+  with `id-token: write` and `NPM_CONFIG_PROVENANCE=true`. Currently
+  scoped to `workflow_dispatch` trigger so the first GHA-driven publish
+  can be observed; flip to `push: main` once the changesets cadence
+  stabilizes. Tarballs published from the workflow will land on npm
+  with verified provenance.
+
+### Changed
+
+- `MetricEventType` union grew three new entries:
+  `cache.stale.refresh.leader`, `cache.stale.refresh.follower`,
+  `cache.stale.refresh.skipped`. The legacy `cache.stale` event still
+  fires when `singleFlight` is off (default).
+- `HandlerState` now carries an `instanceId` (read from `HOSTNAME` /
+  `ECS_TASK_ID` / `pid-<pid>`) and embeds it in every refresh-lock
+  acquisition for operator-side observability.
+
+### Compatibility
+
+- No breaking changes. All existing 0.1.x configurations continue to
+  work; `singleFlight` defaults to `false`.
+
+### Verified
+
+- 72 unit tests (8 files) + 21 integration tests (1 file × 21 scenarios)
+  all green.
+- arethetypeswrong: 28/28 cells green.
+- publint: clean.
+
+## [0.1.1] - 2026-05-10
+
+Documentation-only patch released alongside the first round of external
+write-ups. No code changes.
+
+### Changed
+
+- **Compatibility matrix** now carries an explicit verification date and a
+  `nextjs-turbo-redis-cache` column, so readers can spot-check the comparison
+  against the upstream READMEs as both packages evolve. The previous
+  two-column shape didn't make it obvious which competitors are tracked.
+- **Production checklist** gains an explicit Redis Cluster row: cluster
+  deployments must set `hashTag: true` to avoid `CROSSSLOT` errors from
+  the multi-key Lua scripts. Also notes that cluster support is
+  unit-tested but not yet load-tested at scale.
+- **Compatibility table for Redis-protocol services** (ElastiCache,
+  Upstash, DragonflyDB, KeyDB, Vercel KV) added to the production
+  section, separating "validated" from "expected to work via the
+  standard Redis protocol".
+- **`docs/architecture.md`** now documents two memory-fallback caveats
+  that previously required reading the source: per-process isolation
+  (cross-instance correctness degrades during Redis outages) and the
+  32-bit `setTimeout` clamp (TTLs above ≈24.85 days fire the eviction
+  timer early, though `get()`'s lazy `expiresAt` check still honors the
+  configured expiration).
+
 ## [0.1.0] - 2026-05-10
 
 First stable release. Promoted from `0.1.0-rc.1` after a 24-hour live-traffic

package/README.md

@@ -3,10 +3,15 @@
 [![npm](https://img.shields.io/npm/v/@leejpsd/nextjs-cache-handler.svg)](https://www.npmjs.com/package/@leejpsd/nextjs-cache-handler)
 [![license](https://img.shields.io/npm/l/@leejpsd/nextjs-cache-handler.svg)](./LICENSE)
 
-> **Stable `v0.1.0`** — install with
+> **`v0.2.0`** — install with
 > `npm install @leejpsd/nextjs-cache-handler`. Production-validated against
 > AWS ECS Fargate with multi-instance Redis (24h live-traffic soak: 0
 > errors, 0 leaks, 2ms Redis ping, namespace isolation working).
+>
+> v0.2 adds: optional **single-flight refresh lock** for cache-stampede
+> protection at the SWR boundary, a reference **OpenTelemetry** wrapper,
+> and **integration tests** (21 scenarios) running against real Redis 7
+> over both `redis@5` and `ioredis` adapters.
 
 The Redis cache handler for **Next.js 16** that ships **both** `cacheHandler`
 (ISR / Pages Router) **and** `cacheHandlers` (`'use cache'` directive,
@@ -49,21 +54,29 @@ As of 2026-05, the leading OSS Redis handler `@fortedigital/nextjs-cache-handler
 declares `peerDependencies.next: ">=16.1.5"` but the README marks the new
 plural interface as ❌ **"Not yet supported - Help needed"**:
 
-| Next 16 feature | @fortedigital | this |
-|---|---|---|
-| `cacheHandlers` config (plural) | ❌ Help needed | ✅ |
-| `'use cache'` directive | ❌ Help needed | ✅ |
-| `'use cache: remote'` | ❌ Help needed | ✅ |
-| `'use cache: private'` | n/a (uncustomizable) | n/a |
-| `cacheComponents: true` | ❌ Help needed | ✅ |
-| Build-phase skip (`PHASE_PRODUCTION_BUILD`) | ✅ | ✅ |
-| Auto deploy isolation (`BUILD_NAMESPACE`) | manual | ✅ auto |
-| Lua-atomic SET+tag | partial (MULTI) | ✅ |
-| AbortSignal timeout | ✅ | ✅ |
-| Redis Cluster | ✅ | ✅ |
-| ioredis support | ✅ | ✅ |
-| In-memory fallback (TTL-aware) | partial | ✅ |
-| OpenTelemetry hook | ❌ | ✅ (`onMetric`) |
+> 📅 **Compatibility matrix verified 2026-05-10.** The OSS Next.js cache
+> handler ecosystem moves quickly — please verify
+> [`@fortedigital`](https://github.com/fortedigital/nextjs-cache-handler#compatibility)
+> and
+> [`nextjs-turbo-redis-cache`](https://github.com/trieb-work/nextjs-turbo-redis-cache#features)
+> directly before relying on this comparison.
+
+| Next 16 feature | this | @fortedigital 3.2.0 | nextjs-turbo-redis-cache 1.13 |
+|---|---|---|---|
+| `cacheHandlers` config (plural) | ✅ | ❌ Help needed | ✅ since 1.11 |
+| `'use cache'` directive | ✅ | ❌ Help needed | ✅ since 1.11 |
+| `'use cache: remote'` | ✅ | ❌ Help needed | partial |
+| `'use cache: private'` | n/a (uncustomizable) | n/a | n/a |
+| `cacheComponents: true` | ✅ | ❌ Help needed | ✅ |
+| Build-phase skip (`PHASE_PRODUCTION_BUILD`) | ✅ | ✅ (singular only) | ✅ |
+| Auto deploy isolation | ✅ `BUILD_NAMESPACE` env-resolved | manual | ✅ `BUILD_ID` since 1.13 |
+| Lua-atomic SET+tag | ✅ Lua scripts | partial (MULTI) | partial |
+| AbortSignal timeout | ✅ per-op | ✅ Proxy-wrapped | ❌ |
+| Redis Cluster | ✅ (cluster adapter, see Production checklist) | ✅ | ✅ |
+| ioredis support | ✅ | ✅ | ✅ |
+| In-memory fallback (TTL-aware) | ✅ | partial | ✅ L1 + Redis L2 |
+| OpenTelemetry hook | ✅ `onMetric` | ❌ | ❌ |
+| Live-traffic dogfood (24h+) | ✅ AWS ECS Fargate | not published | not published |
 
 PR [#207](https://github.com/fortedigital/nextjs-cache-handler/pull/207) on
 `@fortedigital` has been stalled for 3+ months on the same issue: the
@@ -163,13 +176,15 @@ export default async function Page() {
 ```ts
 interface CacheHandlerOptions {
   client: RedisClientFactory | RedisClientConfig;
-  keyPrefix?: string;            // default: "next-cache:" / "next-incremental:"
+  keyPrefix?: string;             // default: "next-cache:" / "next-incremental:"
   buildNamespace?: string | (() => string);  // default: env DEPLOYMENT_VERSION || GIT_HASH || "unversioned"
-  abortTimeoutMs?: number;       // default: 1500
+  abortTimeoutMs?: number;        // default: 1500
   fallback?: "auto" | "always" | "never";    // default: "auto"
   staleWhileRevalidate?: boolean; // default: true (cache-components only)
-  isBuildPhase?: () => boolean;  // override PHASE_PRODUCTION_BUILD detection
-  hashTag?: boolean;             // default: false (set true on Redis Cluster)
+  singleFlight?: boolean;         // default: false — see "Single-flight refresh lock" below
+  singleFlightLockTtlSec?: number; // default: 10
+  isBuildPhase?: () => boolean;   // override PHASE_PRODUCTION_BUILD detection
+  hashTag?: boolean;              // default: false (set true on Redis Cluster)
   onMetric?: (event: MetricEvent) => void;
   logger?: Logger;
 }
@@ -196,6 +211,13 @@ Full reference: [`docs/api.md`](./docs/api.md) (auto-generated).
       to avoid static-chunk-404 issues during a deploy.
 - [ ] **`abortTimeoutMs: 1500`** (default) — protects against a stuck Redis
       connection from hanging the request thread.
+- [ ] **Redis Cluster: set `hashTag: true`** — multi-key Lua scripts
+      (`set-with-tags.lua`, `revalidate-hard.lua`) require all KEYS to land
+      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.
 - [ ] **Redis `maxmemory-policy: allkeys-lru` or `noeviction`** — if you need
       bounded memory, choose `allkeys-lru`. Otherwise `noeviction` keeps
       tag indices intact.
@@ -205,6 +227,86 @@ Full reference: [`docs/api.md`](./docs/api.md) (auto-generated).
       (separate from the handler) so a Redis outage surfaces in your
       monitoring without inducing 5xx in user requests.
 
+### Compatibility with Redis-protocol services
+
+| 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 |
+| **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 |
+| **Vercel KV** | not yet supported — `@vercel/kv` adapter ships in v0.3 | — |
+| **DragonflyDB / KeyDB** | Redis-protocol compatible — `{ type: "redis", url }` should work | not validated |
+
+---
+
+## Single-flight refresh lock (v0.2)
+
+The `cacheHandlers` (plural) interface returns stale entries inside the
+SWR window so users get an instant response while the background
+refresh completes. With many instances, the moment an entry crosses the
+`revalidate` boundary, every instance independently triggers its own
+refresh — N parallel re-renders for the same key, each hitting your
+origin once.
+
+`singleFlight: true` adds an opt-in Redis lock (`refresh-tag-lock.lua`,
+default TTL 10s) at the SWR boundary. The first instance to acquire it
+becomes the **leader** and runs the refresh; the rest become
+**followers**, keep serving the same stale entry, and wait for the
+leader's write to land. The lock is observability-only at the handler
+layer — Next.js still drives the actual refresh; we just suppress the
+stampede.
+
+```js
+createCacheComponentsHandler({
+  client: { type: "redis", url: process.env.REDIS_URL },
+  singleFlight: true,         // default false
+  singleFlightLockTtlSec: 10, // default 10
+});
+```
+
+Two new `MetricEvent` types appear on `onMetric`:
+
+| event type | meaning |
+|---|---|
+| `cache.stale.refresh.leader` | this instance just acquired the lock and is the designated refresher |
+| `cache.stale.refresh.follower` | another instance holds the lock; we serve stale and skip the refresh |
+
+If lock acquisition fails (Redis hiccup, TTL race), the handler
+defaults to the follower path — the stale entry is always served, never
+dropped. This is intentional: the lock is an optimization, not a
+correctness-critical primitive.
+
+When **not** to enable single-flight: small fleets (1–2 instances) where
+Next's per-process serialization already covers the stampede risk.
+Adding a Redis round-trip per stale read isn't free.
+
+See [`docs/architecture.md`](./docs/architecture.md#single-flight-refresh-lock-v02-)
+for the full state machine and a reference to the Lua script body.
+
+---
+
+## OpenTelemetry instrumentation (v0.2)
+
+The handler doesn't bundle `@opentelemetry/api` (zero runtime
+dependencies stays a goal). Instead, the `onMetric(event)` hook gives
+strictly-typed events you can pipe into whatever observability stack
+you already run.
+
+[`examples/opentelemetry/`](./examples/opentelemetry/) is a copy-paste
+reference wrapper that:
+
+- exposes a `nextjs_cache.events_total` counter dimensioned on
+  `type` / `freshness` / `backend` / `reason` / `op`
+- exposes a `nextjs_cache.op_latency_ms` histogram for events that
+  carry an `ms` field
+- keeps cardinality bounded — cache keys and tag names are never
+  emitted as attributes
+
+See [`examples/opentelemetry/README.md`](./examples/opentelemetry/README.md)
+for setup and three suggested dashboards (hit rate, single-flight
+leadership distribution, op latency tails).
+
 ---
 
 ## How it differs from `@fortedigital/nextjs-cache-handler`
@@ -248,14 +350,17 @@ ESM and CJS dual-published, full TypeScript types, validated via
 
 ## Roadmap
 
-- **v0.1.0** *(target: 2026-05)* — Both handlers, SWR, Lua atomicity,
-  build-phase skip, `redis@5` + `ioredis` adapters, AbortSignal,
-  in-memory fallback with TTL, soft-tag freshness check
-- **v0.2.0** — Single-flight refresh lock (Lua SETNX), OpenTelemetry
-  forwarder example
+- **v0.1.0** *(2026-05)* — Both handlers, SWR, Lua atomicity, build-phase
+  skip, `redis@5` + `ioredis` adapters, AbortSignal, in-memory fallback
+  with TTL, soft-tag freshness check ✅
+- **v0.2.0** *(2026-05)* — Single-flight refresh lock with leader/follower
+  metrics, OpenTelemetry reference adapter, integration tests against
+  real Redis 7 (21 scenarios over `redis@5` + `ioredis`), GitHub Actions
+  OIDC publish path with provenance attestation ✅
 - **v0.3.0** — Vercel KV / Upstash Redis adapter, `'use cache: remote'`
-  multi-tier setup
-- **v0.4.0** — Cache stampede protection, request-scoped memoization
+  multi-tier setup, Redis Cluster load testing
+- **v0.4.0** — Cache stampede protection beyond single-flight,
+  request-scoped memoization
 
 ---
 

package/dist/cache-components/index.cjs

@@ -632,7 +632,9 @@ var DEFAULT_KEY_PREFIX = "next-cache:";
 var ENTRY_SUFFIX = "entry:";
 var TAG_SUFFIX = "tag:";
 var TAG_EXP_SUFFIX = "tag-expiration:";
+var LOCK_SUFFIX = "lock:";
 var DEFAULT_ABORT_MS = 1500;
+var DEFAULT_LOCK_TTL_SEC = 10;
 var ONE_YEAR_SEC = 60 * 60 * 24 * 365;
 var FALLBACK_TTL_SEC = 3600;
 var TAG_EXP_MARKER_TTL_SEC = 60 * 60 * 24 * 7;
@@ -655,6 +657,8 @@ function init(opts) {
       staleWhileRevalidate: opts.staleWhileRevalidate ?? true,
       hashTag: opts.hashTag ?? false,
       keyPrefix: opts.keyPrefix ?? DEFAULT_KEY_PREFIX,
+      singleFlight: opts.singleFlight ?? false,
+      singleFlightLockTtlSec: opts.singleFlightLockTtlSec ?? DEFAULT_LOCK_TTL_SEC,
       rest: opts
     },
     logger,
@@ -664,7 +668,8 @@ function init(opts) {
     memTags: new MemorySetStore(),
     memTagExp: /* @__PURE__ */ new Map(),
     localTagTimestamps: /* @__PURE__ */ new Map(),
-    resolveNs: () => resolveBuildNamespace(opts.buildNamespace)
+    resolveNs: () => resolveBuildNamespace(opts.buildNamespace),
+    instanceId: process.env.HOSTNAME || process.env.ECS_TASK_ID || `pid-${process.pid}`
   };
 }
 function entryKey(state, cacheKey) {
@@ -691,6 +696,40 @@ function tagExpKey(state, tag) {
     state.opts.hashTag
   );
 }
+function lockKey(state, cacheKey) {
+  return buildKey(
+    `${state.opts.keyPrefix}${LOCK_SUFFIX}`,
+    state.resolveNs(),
+    cacheKey,
+    state.opts.hashTag
+  );
+}
+async function tryAcquireRefreshLock(state, cacheKey) {
+  if (!state.opts.singleFlight) return false;
+  if (!gateRedis(state)) return false;
+  try {
+    return await withAbortSignal(
+      "cacheHandlers.singleFlight.lock",
+      state.opts.abortTimeoutMs,
+      async () => {
+        const client = await state.conn.getOrConnect();
+        if (!client) return false;
+        const result = await execLuaScript(
+          client,
+          "refreshTagLock",
+          [lockKey(state, cacheKey)],
+          [
+            state.instanceId,
+            String(state.opts.singleFlightLockTtlSec)
+          ]
+        );
+        return result === 1;
+      }
+    );
+  } catch {
+    return false;
+  }
+}
 function resolveTtlSeconds(entry) {
   if (Number.isFinite(entry.expire) && entry.expire > 0) {
     return Math.max(60, Math.ceil(entry.expire));
@@ -785,11 +824,28 @@ async function getImpl(state, cacheKey, softTags) {
       return void 0;
     }
   }
-  state.emit({
-    type: partition.freshness === "stale" ? "cache.stale" : "cache.hit",
-    ms: Date.now() - start,
-    meta: { freshness: partition.freshness }
-  });
+  if (partition.freshness === "stale") {
+    if (state.opts.singleFlight) {
+      const isLeader = await tryAcquireRefreshLock(state, cacheKey);
+      state.emit({
+        type: isLeader ? "cache.stale.refresh.leader" : "cache.stale.refresh.follower",
+        ms: Date.now() - start,
+        meta: { freshness: partition.freshness }
+      });
+    } else {
+      state.emit({
+        type: "cache.stale",
+        ms: Date.now() - start,
+        meta: { freshness: partition.freshness }
+      });
+    }
+  } else {
+    state.emit({
+      type: "cache.hit",
+      ms: Date.now() - start,
+      meta: { freshness: partition.freshness }
+    });
+  }
   return {
     value: bufferToStream(Buffer.from(envelope.value, "base64")),
     tags: envelope.tags,