@leejpsd/nextjs-cache-handler 0.1.1 → 0.2.0

package/CHANGELOG.md

@@ -6,6 +6,64 @@ 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

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,
@@ -171,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;
 }
@@ -233,6 +240,75 @@ Full reference: [`docs/api.md`](./docs/api.md) (auto-generated).
 
 ---
 
+## 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`
 
 Three deliberate departures, all rooted in lessons from production
@@ -274,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,