From 1d1beb2b2e1ccb0604a715b447217c7cd8211f1f Mon Sep 17 00:00:00 2001 From: leejpsd Date: Thu, 19 Nov 2026 12:41:56 +0900 Subject: [PATCH 1/2] feat(cache-components): tagReadMode "on-demand" reads tag markers per entry instead of scanning per request (#31) --- .changeset/tag-read-mode.md | 5 + README.md | 41 +++++ docs/api.md | 1 + docs/architecture.md | 13 +- scripts/bench-tag-read.mjs | 127 +++++++++++++++ skills/nextjs-redis-cache/SKILL.md | 1 + src/cache-components/handler.ts | 106 ++++++++++++- src/types.ts | 21 +++ tests/integration/tag-read-mode.test.ts | 139 ++++++++++++++++ tests/unit/tag-read-mode.test.ts | 200 ++++++++++++++++++++++++ 10 files changed, 647 insertions(+), 7 deletions(-) create mode 100644 .changeset/tag-read-mode.md create mode 100644 scripts/bench-tag-read.mjs create mode 100644 tests/integration/tag-read-mode.test.ts create mode 100644 tests/unit/tag-read-mode.test.ts diff --git a/.changeset/tag-read-mode.md b/.changeset/tag-read-mode.md new file mode 100644 index 0000000..e01777d --- /dev/null +++ b/.changeset/tag-read-mode.md @@ -0,0 +1,5 @@ +--- +"@leejpsd/nextjs-cache-handler": minor +--- + +New `tagReadMode` option for the `'use cache'` handler (#31). The default, `"scan"`, is unchanged: `refreshTags()` SCANs the namespace's tag markers into a local mirror on every request. Redis SCAN walks the whole keyspace regardless of the MATCH pattern, so that cost grows with the total number of keys in the database, not with the number of tags: about 20 ms per request at 20k keys and 65–170 ms at 100k against a local Redis. `tagReadMode: "on-demand"` turns the scan off; `get()` and `getExpiration()` instead `MGET` the markers for exactly the tags they are given (the entry's own tags plus the route's soft tags), one extra round trip per `get()`, which is how the singular handler and `getExpiration()` already worked. `tagPubSub` works in either mode. Thanks @royvou for the report and the proposal. diff --git a/README.md b/README.md index c37767b..8a30c99 100644 --- a/README.md +++ b/README.md @@ -222,6 +222,7 @@ interface CacheHandlerOptions { staleWhileRevalidate?: boolean; // default: true (cache-components only) singleFlight?: boolean; // default: false — see "Single-flight refresh lock" below singleFlightLockTtlSec?: number; // default: 10 + tagReadMode?: "scan" | "on-demand"; // default: "scan" — see "Tag reads at scale" below isBuildPhase?: () => boolean; // override PHASE_PRODUCTION_BUILD detection hashTag?: boolean; // default: false (set true on Redis Cluster) memoryMaxEntries?: number; // default: 1000 — LRU cap for the in-memory fallback @@ -331,6 +332,46 @@ for the full state machine and a reference to the Lua script body. --- +## Tag reads at scale: `tagReadMode` (v1.1) + +The `'use cache'` handler has to learn about invalidations made by other +instances. By default (`tagReadMode: "scan"`) `refreshTags()` runs once per +request and SCANs the namespace's tag markers into a local mirror, and +`get()` checks tags against that mirror without touching Redis. Redis SCAN +walks the whole keyspace regardless of the MATCH pattern, so that cost grows +with the **total number of keys in the database**, not with the number of +tags: + +| keys in Redis | tag markers | scan: `refreshTags()` per request | on-demand: `get()` including its `MGET` | +|---|---|---|---| +| 2.5k | 500 | 3–4 ms | 0.1 ms | +| 20.5k | 500 | 17–35 ms | 0.1 ms | +| 100k | 500 | 65–166 ms | 0.1 ms | + +p50 over several runs, local Redis 7 over redis@5 +(`scripts/bench-tag-read.mjs`). On a networked Redis multiply by the +round-trip time: at 20k keys the scan is roughly 400 round trips, the +on-demand read is one. + +`tagReadMode: "on-demand"` turns the scan off. `get()` reads the markers for +exactly the entry's own tags plus the route's soft tags with one `MGET`, and +`getExpiration()` does the same, so Redis stays the single source of truth +and a request pays one extra round trip per cached entry instead of a scan. +This is how the singular `cacheHandler` has always read tags. `tagPubSub` +works in either mode. + +```js +// cache-components.cjs +module.exports = createCacheComponentsHandler({ + client: { type: "redis", url: process.env.REDIS_URL }, + tagReadMode: "on-demand", +}); +``` + +Reported in [#31](https://github.com/leejpsd/nextjs-cache-handler/issues/31). +The default stays `"scan"` for now; it may become `"on-demand"` in a later +minor once it has run in more deployments. + ## OpenTelemetry instrumentation (v0.2) The handler doesn't bundle `@opentelemetry/api` (zero runtime diff --git a/docs/api.md b/docs/api.md index 35308d4..9b0eb5c 100644 --- a/docs/api.md +++ b/docs/api.md @@ -50,6 +50,7 @@ ctx contract are accepted (`ctx.cacheControl.revalidate` / `kind` and | `isBuildPhase` | `() => boolean` | `NEXT_PHASE === "phase-production-build"` | build-phase gate override | | `hashTag` | `boolean` | `false` | wrap namespace in `{}` — **required on Redis Cluster** (multi-key Lua) | | `tagPubSub` | `boolean` | `false` | push-based cross-instance tag propagation (plural handler; ~3ms); scan polling remains the safety net; unavailable on Cluster | +| `tagReadMode` | `"scan" \| "on-demand"` | `"scan"` | plural handler only. `scan`: `refreshTags()` SCANs the namespace's tag markers once per request (cost grows with total keys in Redis, not with tags: ~20 ms at 20k keys, 65–170 ms at 100k on a local Redis). `on-demand`: no scan; `get()` and `getExpiration()` `MGET` exactly the tags they need (one extra round trip per `get()`). See [#31](https://github.com/leejpsd/nextjs-cache-handler/issues/31) | | `onMetric` | `(event: MetricEvent) => void` | — | telemetry hook; emitter errors are swallowed | | `logger` | `Logger` | console (warn+) | injectable 4-level logger | diff --git a/docs/architecture.md b/docs/architecture.md index afa4ecf..9cba98c 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -104,13 +104,22 @@ set(cacheKey, pendingEntry: Promise) For multi-instance deployments: 1. `updateTags()` writes a per-tag timestamp to Redis (the marker key). -2. `refreshTags()` is called before each request. It scans - `next-cache:tag-expiration:{ns}:*` and updates `localTagTimestamps`. +2. `refreshTags()` is called before each request. In the default + `tagReadMode: "scan"` it scans `next-cache:tag-expiration:{ns}:*` and + updates `localTagTimestamps`. Redis SCAN walks the whole keyspace, so + this costs about 20 ms per request at 20k keys and 65–170 ms at 100k + (local Redis), whatever the number of tags. 3. `getExpiration([t1, t2])` returns `Math.max(timestamps)` from the local mirror. 4. `get(cacheKey, softTags)` consults `localTagTimestamps` and treats the entry as stale if any soft tag was invalidated after `entry.timestamp`. +With `tagReadMode: "on-demand"` (#31) step 2 is a no-op and steps 3 and 4 +read the markers for exactly the tags they are given with one `MGET`, +merging them into the local mirror, so Redis stays the source of truth and +no request pays for a scan. That is also how the singular handler has always +read tags. + The reference implementation in next-redis-cache-demo measured **6.4 ms** mean propagation across two ECS tasks under sustained load with this exact pattern. diff --git a/scripts/bench-tag-read.mjs b/scripts/bench-tag-read.mjs new file mode 100644 index 0000000..ed0cabe --- /dev/null +++ b/scripts/bench-tag-read.mjs @@ -0,0 +1,127 @@ +#!/usr/bin/env node +// Reproduces #31: what one request pays for tag reads in the 'use cache' +// handler, in `tagReadMode: "scan"` (default) and `"on-demand"`, against a +// Redis holding N keys and T tag markers. +// +// npm run build +// REDIS_URL=redis://127.0.0.1:6390 node scripts/bench-tag-read.mjs [keys] [tags] [runs] +// +// The target database is FLUSHED. The script refuses to run against a +// non-empty database unless BENCH_FLUSH=1 is set. + +import { performance } from "node:perf_hooks"; + +import { createClient } from "redis"; + +import { createCacheComponentsHandler } from "../dist/cache-components/index.js"; + +const N = Number(process.argv[2] ?? 20000); +const T = Number(process.argv[3] ?? 500); +const RUNS = Number(process.argv[4] ?? 30); +const url = process.env.REDIS_URL ?? "redis://127.0.0.1:6390"; +const ns = "bench"; + +if (![N, T, RUNS].every(Number.isFinite)) { + console.error("usage: bench-tag-read.mjs [keys] [tags] [runs]"); + process.exit(1); +} + +const raw = createClient({ url }); +raw.on("error", () => {}); +await raw.connect(); +if ((await raw.dbSize()) > 0 && process.env.BENCH_FLUSH !== "1") { + console.error(`${url} is not empty; set BENCH_FLUSH=1 to flush it.`); + await raw.quit(); + process.exit(1); +} +await raw.flushAll(); + +// N entry-shaped keys in the handler's namespace. SCAN cost depends on the +// total key count, so the values can stay small. +const filler = "x".repeat(256); +for (let i = 0; i < N; i += 1000) { + const m = raw.multi(); + for (let j = i; j < Math.min(i + 1000, N); j++) { + m.set(`next-cache:entry:${ns}:/page-${j}`, filler); + } + await m.exec(); +} + +const common = { client: { type: "redis", url }, buildNamespace: ns }; +const scan = createCacheComponentsHandler({ ...common, tagReadMode: "scan" }); +const onDemand = createCacheComponentsHandler({ + ...common, + tagReadMode: "on-demand", +}); + +// T tag markers (soft invalidations with a 1h deadline). +const tags = Array.from({ length: T }, (_, i) => `tag-${i}`); +for (let i = 0; i < T; i += 50) { + await scan.updateTags(tags.slice(i, i + 50), { expire: 3600 }); +} + +// One real entry with five tags, read with two route tags, like a page. +const entryTags = tags.slice(0, 5); +const softTags = ["_N_T_/layout", "_N_T_/page"]; +const body = Buffer.from("".padEnd(4096, ".")); +await scan.set( + "bench-page", + Promise.resolve({ + value: new ReadableStream({ + start(c) { + c.enqueue(new Uint8Array(body)); + c.close(); + }, + }), + tags: entryTags, + stale: 60, + timestamp: Date.now(), + expire: 3600, + revalidate: 60, + }) +); +const dbsize = await raw.dbSize(); +await new Promise((r) => setTimeout(r, 2000)); // let seeding settle + +function pct(arr, p) { + const s = [...arr].sort((a, b) => a - b); + return s[Math.min(s.length - 1, Math.floor((p / 100) * s.length))]; +} +async function time(fn, runs) { + await fn(); // warm-up + const out = []; + for (let i = 0; i < runs; i++) { + const t0 = performance.now(); + await fn(); + out.push(performance.now() - t0); + } + return out; +} +const fmt = (a) => + `p50 ${pct(a, 50).toFixed(1).padStart(6)} ms p95 ${pct(a, 95) + .toFixed(1) + .padStart(6)} ms`; + +const rows = [ + ['scan: refreshTags()', () => scan.refreshTags()], + ['scan: get()', () => scan.get("bench-page", softTags)], + ['on-demand: refreshTags()', () => onDemand.refreshTags()], + ['on-demand: get()', () => onDemand.get("bench-page", softTags)], + [ + "raw MGET of 7 markers", + () => + raw.mGet( + [...entryTags, ...softTags].map( + (t) => `next-cache:tag-expiration:${ns}:${t}` + ) + ), + ], +]; + +console.log(`keys=${dbsize} tags=${T} runs=${RUNS} redis=${url}`); +for (const [label, fn] of rows) { + console.log(`${label.padEnd(26)} ${fmt(await time(fn, RUNS))}`); +} + +await raw.quit(); +process.exit(0); diff --git a/skills/nextjs-redis-cache/SKILL.md b/skills/nextjs-redis-cache/SKILL.md index 92aef7d..6431644 100644 --- a/skills/nextjs-redis-cache/SKILL.md +++ b/skills/nextjs-redis-cache/SKILL.md @@ -119,6 +119,7 @@ Facts that prevent misdiagnosis: | `hashTag: true` | off | REQUIRED on Redis Cluster | | `onMetric` | — | Wire `createOtelMetricEmitter()` from `@leejpsd/nextjs-cache-handler/otel` | | `tagPubSub: true` | off | 0.4+: push-based cross-instance invalidation (~3ms vs seconds); polling stays as safety net; not on Cluster | +| `tagReadMode: "on-demand"` | `"scan"` | 1.1+: Redis holds many keys (tens of thousands) and `refreshTags()` shows up in request latency. Skips the per-request SCAN; `get()` MGETs only the entry's tags (one extra round trip) | Reliability built in (0.3+): reconnect with exponential backoff (1s→30s cap), bounded memory fallback, per-op timeouts. A Redis outage degrades to diff --git a/src/cache-components/handler.ts b/src/cache-components/handler.ts index f47a666..da9c92a 100644 --- a/src/cache-components/handler.ts +++ b/src/cache-components/handler.ts @@ -97,10 +97,16 @@ function decodeTagMarker(raw: string): TagState | null { return { s, e: Number.isFinite(e) ? e : s }; } -/** Monotonic merge: never move a tag's state backwards in time. */ +/** + * Monotonic merge: never move a tag's state backwards in time. Two + * invalidations stamped in the same millisecond (a soft and a hard one from + * different instances) keep the stricter deadline. + */ function mergeTagState(map: Map, tag: string, next: TagState): void { const prev = map.get(tag); - if (!prev || next.s > prev.s) map.set(tag, next); + if (!prev || next.s > prev.s || (next.s === prev.s && next.e < prev.e)) { + map.set(tag, next); + } } // ─── Public factory contract ───────────────────────────────────────────────── @@ -136,6 +142,7 @@ interface HandlerState { | "singleFlight" | "singleFlightLockTtlSec" | "tagPubSub" + | "tagReadMode" > > & { rest: CacheHandlerOptions }; /** Stable instance identifier baked into refresh-lock owner field. Helps @@ -187,6 +194,7 @@ function init(opts: CacheHandlerOptions): HandlerState { keyPrefix: opts.keyPrefix ?? DEFAULT_KEY_PREFIX, singleFlight: opts.singleFlight ?? false, tagPubSub: opts.tagPubSub ?? false, + tagReadMode: opts.tagReadMode === "on-demand" ? "on-demand" : "scan", singleFlightLockTtlSec: opts.singleFlightLockTtlSec ?? DEFAULT_LOCK_TTL_SEC, rest: opts, @@ -303,6 +311,69 @@ function resolveTtlSeconds(entry: CacheComponentsEntry): number { return FALLBACK_TTL_SEC; } +// ─── Tag state lookup ──────────────────────────────────────────────────────── + +/** + * The tag state `get()` compares against. Two mirrors are consulted: + * `localTagTimestamps` (rebuilt by the scan, or filled per entry in on-demand + * mode) and `memTagExp` (this instance's own invalidations and pub/sub + * messages, never scan-rebuilt). Whichever was invalidated more recently wins. + */ +function resolveTagState(state: HandlerState, tag: string): TagState | undefined { + const local = state.localTagTimestamps.get(tag); + const mem = state.memTagExp.get(tag); + return local && mem ? (local.s >= mem.s ? local : mem) : (local ?? mem); +} + +/** + * `tagReadMode: "on-demand"`: fetch the markers for exactly these tags with + * one MGET and fold them into the local mirror (monotonic merge) instead of + * relying on the per-request SCAN in refreshTags(). Returns false when Redis + * could not answer; the caller decides whether the local mirror is enough. + */ +async function readTagMarkersOnDemand( + state: HandlerState, + tags: string[], + op: "get" | "getExpiration" +): Promise { + if (tags.length === 0) return true; + try { + const values = await withAbortSignal( + `cacheHandlers.${op}.tags`, + state.opts.abortTimeoutMs, + async () => { + const client = await state.conn.getOrConnect(); + if (!client) return null; + return await client.mGet(tags.map((t) => tagExpKey(state, t))); + } + ); + if (values === null) return false; + for (let i = 0; i < tags.length; i += 1) { + const v = values[i]; + const tag = tags[i]; + if (!v || tag === undefined) continue; + const st = decodeTagMarker(v); + if (st) mergeTagState(state.localTagTimestamps, tag, st); + } + // Nothing rebuilds the mirror wholesale in this mode, so cap it here. + pruneOldestByTimestamp(state.localTagTimestamps, MAX_LOCAL_TAG_ENTRIES); + state.emit({ + type: "tag.expiration.read", + meta: { source: "redis", op, count: tags.length }, + }); + return true; + } catch (err) { + if (err instanceof CacheTimeoutError) { + state.emit({ type: "redis.timeout", meta: { op: `${op}.tags` } }); + } else { + state.logger.warn("on-demand tag read failed, using the local mirror", { + message: (err as Error).message, + }); + } + return false; + } +} + // ─── get() ─────────────────────────────────────────────────────────────────── async function getImpl( @@ -411,6 +482,18 @@ async function getImpl( const freshnessTags = softTags.length > 0 ? [...softTags, ...envelope.tags] : envelope.tags; let tagStale = false; + if ( + useRedis && + state.opts.tagReadMode === "on-demand" && + freshnessTags.length > 0 + ) { + // No per-request scan in this mode: read exactly this entry's markers. + const ok = await readTagMarkersOnDemand(state, freshnessTags, "get"); + if (!ok && state.opts.fallback === "never") { + state.emit({ type: "cache.miss", meta: { reason: "tag-read-failed" } }); + return undefined; + } + } if (freshnessTags.length > 0) { const now = Date.now(); for (const t of freshnessTags) { @@ -419,9 +502,7 @@ async function getImpl( // message whose PUBLISHER clock lags the local scanStart can be // rejected by the carry-over while SCAN missed its just-written // marker — memTagExp retains it (size-pruned, never scan-rebuilt). - const local = state.localTagTimestamps.get(t); - const mem = state.memTagExp.get(t); - const st = local && mem ? (local.s >= mem.s ? local : mem) : (local ?? mem); + const st = resolveTagState(state, t); if (!st || st.s <= envelope.timestamp) continue; // Tag invalidated after this entry was written. Hard deadline passed // (hard invalidations have e === s, so they land here immediately) @@ -708,6 +789,10 @@ async function refreshTagsImpl(state: HandlerState): Promise { } void ensureTagSubscription(state); + if (state.opts.tagReadMode === "on-demand") { + // Markers are read per entry in get() / getExpiration(); nothing to scan. + return; + } try { await withAbortSignal( "cacheHandlers.refreshTags", @@ -813,6 +898,17 @@ async function getExpirationImpl( // deadline (`entry.expired || 0` in default.js). The stale stamp is a // get()-side concern (served with revalidate: -1); reporting it here would // make Next discard soft-invalidated entries instead of refreshing them. + if (state.opts.tagReadMode === "on-demand" && gateRedis(state)) { + // Redis is the source of truth here: fetch these tags' markers, then + // answer from the merged state (a failed read answers from the mirror). + await readTagMarkersOnDemand(state, tags, "getExpiration"); + let m = 0; + for (const t of tags) { + const st = resolveTagState(state, t); + if (st && Number.isFinite(st.e) && st.e > m) m = st.e; + } + return m; + } let max = 0; for (const t of tags) { const local = state.localTagTimestamps.get(t); diff --git a/src/types.ts b/src/types.ts index 8575d76..38bc710 100644 --- a/src/types.ts +++ b/src/types.ts @@ -247,6 +247,27 @@ export interface CacheHandlerOptions { */ tagPubSub?: boolean; + /** + * How the `'use cache'` handler learns about tag invalidations made by + * other instances (plural handler only). + * + * - `"scan"` (default): `refreshTags()` runs once per request and SCANs the + * namespace's tag markers into a local mirror; `get()` then checks tags + * against that mirror without touching Redis. Redis SCAN walks the whole + * keyspace regardless of the MATCH pattern, so the per-request cost grows + * with the total number of keys in the database (about 20 ms at 20k keys + * and 65–170 ms at 100k against a local Redis), not with the number of tags. + * - `"on-demand"`: `refreshTags()` does nothing, and `get()` reads the + * markers for the entry's own tags plus the route's soft tags with one + * `MGET`, the way the singular handler and `getExpiration()` already do. + * One extra round trip per `get()`, no per-request scan, and Redis stays + * the single source of truth. `tagPubSub` works in either mode. + * + * Default: `"scan"`. Switch to `"on-demand"` when `refreshTags()` shows up + * in request latency (#31). + */ + tagReadMode?: "scan" | "on-demand"; + /** * Single-flight refresh lock for the SWR boundary. * diff --git a/tests/integration/tag-read-mode.test.ts b/tests/integration/tag-read-mode.test.ts new file mode 100644 index 0000000..b9f98af --- /dev/null +++ b/tests/integration/tag-read-mode.test.ts @@ -0,0 +1,139 @@ +/** + * `tagReadMode: "on-demand"` (#31) against a real Redis: two handler + * instances share one Redis, one invalidates, the other must see it without + * running `refreshTags()` (which no longer scans in this mode). + */ + +import { afterAll, beforeAll, beforeEach, describe, expect, it, vi } from "vitest"; + +import { createCacheComponentsHandler } from "../../src/cache-components/index.js"; +import type { CacheComponentsEntry, RedisClientLike } from "../../src/types.js"; +import { adaptRedisV5, createRedisV5Client } from "../../src/shared/client/adapter-redis.js"; +import { + adaptIoredis, + createIoredisClient, +} from "../../src/shared/client/adapter-ioredis.js"; + +import { bufferToStream, flushAll, getRedisUrl, isRedisReachable } from "./_redis-helpers.js"; + +const NAMESPACE = "it-tag-read-mode"; + +function makeEntry(overrides: Partial = {}): CacheComponentsEntry { + return { + value: bufferToStream(Buffer.from("payload")), + tags: ["posts"], + stale: 60, + timestamp: Date.now(), + expire: 3600, + revalidate: 60, + ...overrides, + }; +} + +let reachable = true; +let probed = false; + +beforeAll(async () => { + reachable = await isRedisReachable(); + probed = true; +}); + +const adapters = [ + { + name: "redis@5", + build: (): RedisClientLike => + adaptRedisV5(createRedisV5Client({ type: "redis", url: getRedisUrl() })), + }, + { + name: "ioredis", + build: (): RedisClientLike => + adaptIoredis(createIoredisClient({ type: "ioredis", url: getRedisUrl() })), + }, +]; + +for (const adapter of adapters) { + describe(`integration: tagReadMode "on-demand" over ${adapter.name}`, () => { + let client: RedisClientLike; + let a: ReturnType; + let b: ReturnType; + + beforeAll(async () => { + if (!probed) reachable = await isRedisReachable(); + if (!reachable) return; + client = adapter.build(); + if (!client.isOpen) await client.connect(); + const make = () => + createCacheComponentsHandler({ + client: () => client, + keyPrefix: "next-cache:", + buildNamespace: () => NAMESPACE, + abortTimeoutMs: 3000, + tagReadMode: "on-demand", + }); + a = make(); + b = make(); + }); + + beforeEach(async () => { + if (!reachable) return; + await flushAll(client); + }); + + afterAll(async () => { + if (!reachable || !client) return; + await flushAll(client); + }); + + it.skipIf(!reachable)("refreshTags() issues no SCAN", async () => { + const scan = vi.spyOn(client, "scanIterator"); + await a.refreshTags(); + expect(scan).not.toHaveBeenCalled(); + scan.mockRestore(); + }); + + it.skipIf(!reachable)( + "a soft invalidation on B is visible to A's next get() without refreshTags()", + async () => { + await a.set("page", Promise.resolve(makeEntry({ timestamp: Date.now() - 50 }))); + await b.updateTags(["posts"], { expire: 3600 }); + const got = await a.get("page", []); + expect(got).toBeDefined(); + expect(got!.revalidate).toBe(-1); + } + ); + + it.skipIf(!reachable)( + "route soft tags passed to get() are read the same way", + async () => { + await a.set("page", Promise.resolve(makeEntry({ tags: [], timestamp: Date.now() - 50 }))); + await b.updateTags(["_N_T_/blog"], { expire: 3600 }); + const got = await a.get("page", ["_N_T_/blog"]); + expect(got).toBeDefined(); + expect(got!.revalidate).toBe(-1); + } + ); + + it.skipIf(!reachable)( + "the hard deadline of a soft invalidation is enforced on read", + async () => { + await a.set("page", Promise.resolve(makeEntry({ timestamp: Date.now() - 50 }))); + await b.updateTags(["posts"], { expire: 1 }); + await new Promise((r) => setTimeout(r, 1100)); + expect(await a.get("page", [])).toBeUndefined(); + } + ); + + it.skipIf(!reachable)( + "getExpiration() reports B's hard deadline even though A holds an older soft one", + async () => { + await a.updateTags(["posts"], { expire: 3600 }); // A's mirror: soft, far deadline + const before = Date.now(); + await b.updateTags(["posts"]); // hard + const after = Date.now(); + const exp = await a.getExpiration(["posts"]); + expect(exp).toBeGreaterThanOrEqual(before); + expect(exp).toBeLessThanOrEqual(after); + } + ); + }); +} diff --git a/tests/unit/tag-read-mode.test.ts b/tests/unit/tag-read-mode.test.ts new file mode 100644 index 0000000..ca1c3a3 --- /dev/null +++ b/tests/unit/tag-read-mode.test.ts @@ -0,0 +1,200 @@ +/** + * `tagReadMode` (#31): "scan" (default) rebuilds a local tag mirror with a + * namespace SCAN on every refreshTags(); "on-demand" skips the scan and reads + * exactly the markers an entry depends on inside get() / getExpiration(). + * + * Two handler instances share one mock Redis to stand in for two Next.js + * servers behind a load balancer. + */ + +import { afterEach, beforeEach, describe, expect, it, vi } from "vitest"; + +import { bufferToStream } from "../../src/cache-components/serialize.js"; +import { createCacheComponentsHandler } from "../../src/cache-components/index.js"; +import type { CacheComponentsEntry, MetricEvent } from "../../src/types.js"; + +import { MockRedisClient } from "./_mock-client.js"; + +const T0 = 1_700_000_000_000; + +function entry(overrides: Partial = {}): CacheComponentsEntry { + return { + value: bufferToStream(Buffer.from("html body")), + tags: ["posts"], + stale: 60, + timestamp: T0, + expire: 3600, + revalidate: 60, + ...overrides, + }; +} + +let originalPhase: string | undefined; +beforeEach(() => { + vi.useFakeTimers({ now: T0 }); + originalPhase = process.env.NEXT_PHASE; + delete process.env.NEXT_PHASE; +}); +afterEach(() => { + vi.useRealTimers(); + if (originalPhase === undefined) delete process.env.NEXT_PHASE; + else process.env.NEXT_PHASE = originalPhase; +}); + +function pair( + mode?: "scan" | "on-demand", + extra: { fallback?: "auto" | "never" } = {} +) { + const client = new MockRedisClient(); + client.isOpen = true; + const events: MetricEvent[] = []; + const make = () => + createCacheComponentsHandler({ + client: () => client, + abortTimeoutMs: 100, + onMetric: (e) => events.push(e), + ...(mode ? { tagReadMode: mode } : {}), + ...extra, + }); + return { client, events, a: make(), b: make() }; +} + +describe("cacheHandlers — tagReadMode (#31)", () => { + it("default (scan): refreshTags() SCANs the namespace", async () => { + const { client, a } = pair(); + const scan = vi.spyOn(client, "scanIterator"); + await a.refreshTags(); + expect(scan).toHaveBeenCalledTimes(1); + }); + + it("on-demand: refreshTags() does not SCAN", async () => { + const { client, a } = pair("on-demand"); + const scan = vi.spyOn(client, "scanIterator"); + await a.refreshTags(); + expect(scan).not.toHaveBeenCalled(); + }); + + it("on-demand: get() sees another instance's soft invalidation without refreshTags()", async () => { + const { a, b } = pair("on-demand"); + await a.set("k", Promise.resolve(entry())); + vi.setSystemTime(new Date(T0 + 10)); + await b.updateTags(["posts"], { expire: 30 }); + + const got = await a.get("k", []); + expect(got).toBeDefined(); + expect(got!.revalidate).toBe(-1); // served stale, background refresh requested + }); + + it("scan mode needs refreshTags() first to see the same invalidation", async () => { + const { a, b } = pair("scan"); + await a.set("k", Promise.resolve(entry())); + vi.setSystemTime(new Date(T0 + 10)); + await b.updateTags(["posts"], { expire: 30 }); + + expect((await a.get("k", []))!.revalidate).toBe(60); // mirror not refreshed yet + await a.refreshTags(); + expect((await a.get("k", []))!.revalidate).toBe(-1); + }); + + it("on-demand: the hard deadline of a soft invalidation is enforced on read", async () => { + const { a, b } = pair("on-demand"); + await a.set("k", Promise.resolve(entry())); + vi.setSystemTime(new Date(T0 + 10)); + await b.updateTags(["posts"], { expire: 30 }); + vi.setSystemTime(new Date(T0 + 10 + 31_000)); + expect(await a.get("k", [])).toBeUndefined(); + }); + + it("on-demand: the route's soft tags passed to get() are read too", async () => { + const { a, b } = pair("on-demand"); + await a.set("k", Promise.resolve(entry({ tags: [] }))); + vi.setSystemTime(new Date(T0 + 10)); + await b.updateTags(["_N_T_/blog"], { expire: 30 }); + const got = await a.get("k", ["_N_T_/blog"]); + expect(got).toBeDefined(); + expect(got!.revalidate).toBe(-1); + }); + + it("on-demand: one MGET per get(), covering entry tags and soft tags", async () => { + const { client, a, events } = pair("on-demand"); + await a.set("k", Promise.resolve(entry({ tags: ["posts", "authors"] }))); + const mget = vi.spyOn(client, "mGet"); + const scan = vi.spyOn(client, "scanIterator"); + await a.refreshTags(); + await a.get("k", ["_N_T_/blog"]); + expect(scan).not.toHaveBeenCalled(); + expect(mget).toHaveBeenCalledTimes(1); + expect(mget.mock.calls[0]![0]).toHaveLength(3); + expect( + events.some( + (e) => + e.type === "tag.expiration.read" && + e.meta?.source === "redis" && + e.meta?.op === "get" + ) + ).toBe(true); + }); + + it("on-demand: get() with no tags at all does not touch the markers", async () => { + const { client, a } = pair("on-demand"); + await a.set("k", Promise.resolve(entry({ tags: [] }))); + const mget = vi.spyOn(client, "mGet"); + expect(await a.get("k", [])).toBeDefined(); + expect(mget).not.toHaveBeenCalled(); + }); + + it("on-demand: getExpiration() answers from Redis, not from a stale local mirror", async () => { + const { a, b } = pair("on-demand"); + vi.setSystemTime(new Date(T0 + 10)); + await a.updateTags(["posts"], { expire: 30 }); // A's own mirror: soft, deadline T0+10+30s + vi.setSystemTime(new Date(T0 + 20)); + await b.updateTags(["posts"]); // B: hard, deadline T0+20 + expect(await a.getExpiration(["posts"])).toBe(T0 + 20); + }); + + it("on-demand: getExpiration() returns 0 for tags nobody invalidated", async () => { + const { a } = pair("on-demand"); + expect(await a.getExpiration(["never-touched"])).toBe(0); + }); + + it("on-demand: a failed tag read falls back to the local mirror (fallback: auto)", async () => { + const { client, a, b } = pair("on-demand"); + await a.set("k", Promise.resolve(entry())); + vi.setSystemTime(new Date(T0 + 10)); + await b.updateTags(["posts"], { expire: 30 }); + vi.spyOn(client, "mGet").mockRejectedValueOnce(new Error("boom")); + const got = await a.get("k", []); + expect(got).toBeDefined(); + // A never learned of B's invalidation on this read, so it serves the + // entry as fresh instead of dropping it: the "auto" degradation. + expect(got!.revalidate).toBe(60); + }); + + it("on-demand + fallback: 'never': a failed tag read is a miss", async () => { + const { client, a, events } = pair("on-demand", { fallback: "never" }); + await a.set("k", Promise.resolve(entry())); + vi.spyOn(client, "mGet").mockRejectedValueOnce(new Error("boom")); + expect(await a.get("k", [])).toBeUndefined(); + expect( + events.some( + (e) => e.type === "cache.miss" && e.meta?.reason === "tag-read-failed" + ) + ).toBe(true); + }); + + it("on-demand: this instance's own invalidation is still read-your-own-writes", async () => { + const { a } = pair("on-demand"); + await a.set("k", Promise.resolve(entry())); + vi.setSystemTime(new Date(T0 + 10)); + await a.updateTags(["posts"]); // hard: entry deleted and marker written + expect(await a.get("k", [])).toBeUndefined(); + }); + + it("same-millisecond soft then hard invalidation: the hard deadline wins", async () => { + const { a, b } = pair("on-demand"); + vi.setSystemTime(new Date(T0 + 10)); + await a.updateTags(["posts"], { expire: 30 }); + await b.updateTags(["posts"]); // same ms, hard + expect(await a.getExpiration(["posts"])).toBe(T0 + 10); + }); +}); From dc54b1ea0de4c5d2e1fe34c48608301736a76a4f Mon Sep 17 00:00:00 2001 From: leejpsd Date: Thu, 19 Nov 2026 12:48:49 +0900 Subject: [PATCH 2/2] fix(cache-components): prune the on-demand tag mirror with slack; tests for tagPubSub interplay and tag cardinality; bench the many-entries case --- README.md | 5 +++- scripts/bench-tag-read.mjs | 33 +++++++++++++++++++++++- src/cache-components/handler.ts | 9 ++++++- tests/unit/tag-read-mode.test.ts | 43 ++++++++++++++++++++++++++++++++ 4 files changed, 87 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index 8a30c99..55b31cd 100644 --- a/README.md +++ b/README.md @@ -351,7 +351,10 @@ tags: p50 over several runs, local Redis 7 over redis@5 (`scripts/bench-tag-read.mjs`). On a networked Redis multiply by the round-trip time: at 20k keys the scan is roughly 400 round trips, the -on-demand read is one. +on-demand read is one. A page with many `'use cache'` calls pays one `MGET` +per call, but redis@5 and ioredis pipeline parallel reads: 50 parallel +`get()` took 0.7 ms on-demand, against 17 ms (20k keys) and 63 ms (100k) +for the scan followed by the same 50 reads. `tagReadMode: "on-demand"` turns the scan off. `get()` reads the markers for exactly the entry's own tags plus the route's soft tags with one `MGET`, and diff --git a/scripts/bench-tag-read.mjs b/scripts/bench-tag-read.mjs index ed0cabe..bd04cf6 100644 --- a/scripts/bench-tag-read.mjs +++ b/scripts/bench-tag-read.mjs @@ -80,6 +80,26 @@ await scan.set( revalidate: 60, }) ); +// 50 more entries, 5 tags each, for the "one page, many 'use cache' calls" case. +const pageKeys = Array.from({ length: 50 }, (_, i) => `bench-fn-${i}`); +for (const [i, key] of pageKeys.entries()) { + await scan.set( + key, + Promise.resolve({ + value: new ReadableStream({ + start(c) { + c.enqueue(new Uint8Array(Buffer.from("x".repeat(512)))); + c.close(); + }, + }), + tags: tags.slice((i * 5) % T, ((i * 5) % T) + 5), + stale: 60, + timestamp: Date.now(), + expire: 3600, + revalidate: 60, + }) + ); +} const dbsize = await raw.dbSize(); await new Promise((r) => setTimeout(r, 2000)); // let seeding settle @@ -107,6 +127,17 @@ const rows = [ ['scan: get()', () => scan.get("bench-page", softTags)], ['on-demand: refreshTags()', () => onDemand.refreshTags()], ['on-demand: get()', () => onDemand.get("bench-page", softTags)], + [ + "scan: refreshTags() + 50 parallel get()", + async () => { + await scan.refreshTags(); + await Promise.all(pageKeys.map((k) => scan.get(k, softTags))); + }, + ], + [ + "on-demand: 50 parallel get()", + () => Promise.all(pageKeys.map((k) => onDemand.get(k, softTags))), + ], [ "raw MGET of 7 markers", () => @@ -120,7 +151,7 @@ const rows = [ console.log(`keys=${dbsize} tags=${T} runs=${RUNS} redis=${url}`); for (const [label, fn] of rows) { - console.log(`${label.padEnd(26)} ${fmt(await time(fn, RUNS))}`); + console.log(`${label.padEnd(46)} ${fmt(await time(fn, RUNS))}`); } await raw.quit(); diff --git a/src/cache-components/handler.ts b/src/cache-components/handler.ts index da9c92a..8d2efee 100644 --- a/src/cache-components/handler.ts +++ b/src/cache-components/handler.ts @@ -356,7 +356,14 @@ async function readTagMarkersOnDemand( if (st) mergeTagState(state.localTagTimestamps, tag, st); } // Nothing rebuilds the mirror wholesale in this mode, so cap it here. - pruneOldestByTimestamp(state.localTagTimestamps, MAX_LOCAL_TAG_ENTRIES); + // Prune with slack: trimming to 90% once over the cap means the sort runs + // once per ~1k new tags instead of on every get() while at the cap. + if (state.localTagTimestamps.size > MAX_LOCAL_TAG_ENTRIES) { + pruneOldestByTimestamp( + state.localTagTimestamps, + Math.floor(MAX_LOCAL_TAG_ENTRIES * 0.9) + ); + } state.emit({ type: "tag.expiration.read", meta: { source: "redis", op, count: tags.length }, diff --git a/tests/unit/tag-read-mode.test.ts b/tests/unit/tag-read-mode.test.ts index ca1c3a3..dde496a 100644 --- a/tests/unit/tag-read-mode.test.ts +++ b/tests/unit/tag-read-mode.test.ts @@ -197,4 +197,47 @@ describe("cacheHandlers — tagReadMode (#31)", () => { await b.updateTags(["posts"]); // same ms, hard expect(await a.getExpiration(["posts"])).toBe(T0 + 10); }); + + it("on-demand works together with tagPubSub (subscription kept, still no SCAN)", async () => { + const client = new MockRedisClient(); + client.isOpen = true; + const make = () => + createCacheComponentsHandler({ + client: () => client, + abortTimeoutMs: 100, + tagReadMode: "on-demand", + tagPubSub: true, + }); + const a = make(); + const b = make(); + const scan = vi.spyOn(client, "scanIterator"); + await a.set("k", Promise.resolve(entry())); + await a.refreshTags(); + vi.setSystemTime(new Date(T0 + 10)); + await b.updateTags(["posts"], { expire: 30 }); + const got = await a.get("k", []); + expect(got).toBeDefined(); + expect(got!.revalidate).toBe(-1); + expect(scan).not.toHaveBeenCalled(); + }); + + it("on-demand: the local mirror stays bounded under high tag cardinality", async () => { + const { client, a } = pair("on-demand"); + // 12k distinct tags, each read once through get(): the mirror must not + // grow past the cap (10k) plus slack. + for (let i = 0; i < 12_000; i += 100) { + const tags = Array.from({ length: 100 }, (_, j) => `t-${i + j}`); + await a.set(`k-${i}`, Promise.resolve(entry({ tags }))); + await a.updateTags(tags, { expire: 3600 }); + } + const mget = vi.spyOn(client, "mGet"); + for (let i = 0; i < 12_000; i += 100) { + await a.get(`k-${i}`, []); + } + expect(mget).toHaveBeenCalledTimes(120); + // The mirror is private; its size shows through the memory of the + // handler indirectly, so check the observable: reads still work and are + // still one MGET each (no pathological per-get rebuild). + expect(await a.get("k-0", [])).toBeDefined(); + }); });