Skip to content

Commit 323a17c

Browse files
authored
[backport] Discard only cache entries that predate a tag revalidation, and reuse completed entries (#97314)
Backports #96726 ("Discard only cache entries that predate a tag revalidation") and #96727 ("Reuse completed cache entries for the rest of a request") to `next-16-3`. Calling `updateTag()` in a server action made every later read of a cache carrying that tag regenerate for the remainder of the request, including reads of an entry that had just been generated after the invalidation and therefore already reflected it. Two sequential reads of the same cache function during the re-render produced two different values within a single render, and each one repeated the work. `isRecentlyRevalidatedTag` only asked whether a tag appeared in `pendingRevalidatedTags`, and that array lives for the whole `WorkStore`, which spans a server action and the render that follows it. Each pending revalidated tag now records a `revalidatedAt` timestamp taken from the same clock as `CacheEntry.timestamp`, and the renamed `isRevalidatedAfter` reports an entry as stale only when the revalidation is newer than the entry. The second change fixes a `'use cache: private'` function executing its body twice when it is called twice in one request, which defeats the preload-then-read shape that motivates a preload in the first place. The intra-request dedupe map dropped an entry as soon as its fill completed, so it only ever covered concurrent invocations, and private caches have no cache handler in production to fall back to. Completed invocations now move into `completedCacheInvocations` on the work store instead of being dropped. The two are backported together because #96727 builds on the discard checks that #96726 restructures. They were stacked in this order on canary, and #96727 conflicts in `test/e2e/app-dir/use-cache/use-cache.test.ts` when applied alone. ### Verification on this branch Cherry-picked from `5da1c1ae03` and `1ff6a80358` in that order, with no conflicts. All source files are byte-identical to canary. Behavioral verification is left to CI on this branch; the changes carry the `action-dedupe`, `dedup-sequential` and `private-dedup-sequential` fixtures in the `use-cache` suite, and a handler-call count assertion in `use-cache-custom-handler`. <!-- NEXT_JS_LLM -->
1 parent 6d67f46 commit 323a17c

17 files changed

Lines changed: 493 additions & 42 deletions

File tree

‎packages/next/src/server/app-render/app-render.tsx‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -6339,6 +6339,7 @@ function buildDevValidationWorkStore(
63396339
cacheLifeProfiles: message.nextConfigSerializable.cacheLifeProfiles,
63406340
buildId: message.buildId,
63416341
deploymentId: message.deploymentId,
6342+
requestStartTime: message.request.requestStartTime,
63426343
previouslyRevalidatedTags: [],
63436344
refreshTagsByCacheKind: new Map(),
63446345
runInCleanSnapshot: createSnapshot(),
@@ -7914,6 +7915,7 @@ async function validateInstantConfigInBuildWithSample(
79147915
isStaticGeneration: false,
79157916
page: outerWorkStore.page,
79167917
route: outerWorkStore.route,
7918+
requestStartTime: outerWorkStore.requestStartTime,
79177919
incrementalCache: outerWorkStore.incrementalCache,
79187920
cacheLifeProfiles: outerWorkStore.cacheLifeProfiles,
79197921
useCacheTimeout: outerWorkStore.useCacheTimeout,

‎packages/next/src/server/app-render/dev-validation-worker-globals.ts‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -55,6 +55,7 @@ export interface DevValidationRequestSnapshot {
5555
isDraftMode: boolean
5656
isHmrRefresh: boolean
5757
hmrRefreshHash: string | undefined
58+
requestStartTime: number
5859
}
5960

6061
/**

‎packages/next/src/server/app-render/dev-validation-worker-snapshot.ts‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -75,6 +75,7 @@ export async function buildDevValidationSnapshot(
7575
isDraftMode: requestStore.draftMode.isEnabled,
7676
isHmrRefresh: requestStore.isHmrRefresh ?? false,
7777
hmrRefreshHash: requestStore.hmrRefreshHash,
78+
requestStartTime: ctx.workStore.requestStartTime,
7879
},
7980
interpolatedParams: ctx.interpolatedParams,
8081
requestFallbackRouteParams: ctx.fallbackRouteParams,

‎packages/next/src/server/app-render/work-async-storage.external.ts‎

Lines changed: 32 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -67,6 +67,14 @@ export interface WorkStore {
6767
pendingRevalidatedTags?: Array<{
6868
tag: string
6969
profile?: string | { stale?: number; revalidate?: number; expire?: number }
70+
/**
71+
* When the tag was revalidated, on the same clock as `CacheEntry.timestamp`
72+
* (`performance.timeOrigin + performance.now()`). A cache entry created
73+
* before this is stale; one created after it already reflects the
74+
* revalidation and can still be served. Re-revalidating a tag moves this
75+
* forward.
76+
*/
77+
revalidatedAt: number
7078
}>
7179

7280
/**
@@ -76,6 +84,15 @@ export interface WorkStore {
7684
*/
7785
readonly previouslyRevalidatedTags: readonly string[]
7886

87+
/**
88+
* When this request started, on the same clock as `CacheEntry.timestamp`.
89+
* `previouslyRevalidatedTags` carry no timestamp of their own, having been
90+
* revalidated by an earlier request, so they are treated as revalidated at
91+
* this instant: entries predating the request are discarded, while entries
92+
* generated during it are not.
93+
*/
94+
readonly requestStartTime: number
95+
7996
/**
8097
* This map contains lazy results so that we can evaluate them when the first
8198
* cache entry is read. It allows us to skip refreshing tags if no caches are
@@ -96,6 +113,21 @@ export interface WorkStore {
96113
*/
97114
pendingCacheInvocations?: Map<string, Promise<SharedCacheResult>>
98115

116+
/**
117+
* Invocations from this request that have already completed, keyed the same
118+
* way as `pendingCacheInvocations`. Entries move here when their fill
119+
* finishes rather than being dropped, so a later invocation of the same cache
120+
* function reuses the entry instead of repeating the cache handler lookup
121+
* and, on a miss, the work.
122+
*
123+
* Only populated for kinds where that saves something real: private caches,
124+
* which have no cache handler in production, and kinds whose handler was
125+
* supplied by the platform or by `cacheHandlers` config, whose reads may be
126+
* remote. A built-in handler read is a map lookup, so retaining its entries
127+
* would cost memory for nothing.
128+
*/
129+
completedCacheInvocations?: Map<string, Promise<SharedCacheResult>>
130+
99131
/**
100132
* Set by the dev-server's hang-detection probe worker (see
101133
* `use-cache-probe-worker.ts`) to switch `cache()` into a one-shot fill

‎packages/next/src/server/async-storage/work-store.ts‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -157,6 +157,7 @@ export function createWorkStore({
157157
cacheComponentsEnabled: renderOpts.cacheComponents,
158158
validationLevel: renderOpts.validationLevel,
159159
previouslyRevalidatedTags,
160+
requestStartTime: performance.timeOrigin + performance.now(),
160161
refreshTagsByCacheKind: createRefreshTagsByCacheKind(),
161162
runInCleanSnapshot: createSnapshot(),
162163
shouldTrackFetchMetrics,

‎packages/next/src/server/dev/use-cache-probe-worker.ts‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -208,6 +208,7 @@ function buildProbeWorkStore(msg: ProbeMessage): WorkStore {
208208
cacheLifeProfiles: msg.nextConfigSerializable.cacheLifeProfiles,
209209
buildId: msg.buildId,
210210
deploymentId: msg.deploymentId,
211+
requestStartTime: msg.request.requestStartTime,
211212
// Empty values for cache-handler / RDC bookkeeping. The `useCacheProbeMode`
212213
// branch in `cache()` returns before any code that reads or writes these
213214
// fields, so the values can never be observed.

‎packages/next/src/server/use-cache/handlers.ts‎

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -15,6 +15,7 @@ const handlersSymbol = Symbol.for('@next/cache-handlers')
1515
const handlersMapSymbol = Symbol.for('@next/cache-handlers-map')
1616
const handlersSetSymbol = Symbol.for('@next/cache-handlers-set')
1717
const privateHandlerSymbol = Symbol.for('@next/cache-handlers-private')
18+
const builtInHandlersSymbol = Symbol.for('@next/cache-handlers-built-in')
1819
const devFrontHandlersSymbol = Symbol.for('@next/cache-handlers-dev-fronts')
1920
const devTieredHandlersSymbol = Symbol.for('@next/cache-handlers-dev-tiered')
2021
const memoryCacheDisabledSymbol = Symbol.for(
@@ -41,6 +42,7 @@ const reference: typeof globalThis & {
4142
}
4243
[handlersMapSymbol]?: Map<string, CacheHandler>
4344
[handlersSetSymbol]?: Set<CacheHandler>
45+
[builtInHandlersSymbol]?: Set<CacheHandler>
4446
// DEV-only
4547
[privateHandlerSymbol]?: CacheHandler
4648
[devFrontHandlersSymbol]?: Map<string, CacheHandler>
@@ -64,6 +66,8 @@ export function initializeCacheHandlers(cacheMaxMemorySize: number): boolean {
6466
debug?.('initializing cache handlers')
6567
const handlersMap = new Map<string, CacheHandler>()
6668
reference[handlersMapSymbol] = handlersMap
69+
const builtInHandlers = new Set<CacheHandler>()
70+
reference[builtInHandlersSymbol] = builtInHandlers
6771

6872
// In development, `cacheMaxMemorySize: 0` would make the built-in default
6973
// handler a no-op, so every reload would miss. Use a real in-memory size
@@ -84,6 +88,7 @@ export function initializeCacheHandlers(cacheMaxMemorySize: number): boolean {
8488
} else {
8589
debug?.('setting "default" cache handler from default')
8690
fallback = createDefaultCacheHandler(builtInSize)
91+
builtInHandlers.add(fallback)
8792
}
8893

8994
handlersMap.set('default', fallback)
@@ -97,6 +102,7 @@ export function initializeCacheHandlers(cacheMaxMemorySize: number): boolean {
97102
}
98103
} else {
99104
const handler = createDefaultCacheHandler(builtInSize)
105+
builtInHandlers.add(handler)
100106

101107
debug?.('setting "default" cache handler from default')
102108
handlersMap.set('default', handler)
@@ -189,6 +195,27 @@ export function isCustomCacheHandler(kind: string): boolean {
189195
return reference[devFrontHandlersSymbol]?.has(kind) ?? false
190196
}
191197

198+
/**
199+
* Whether `kind` resolves to one of the in-memory handlers that
200+
* `initializeCacheHandlers` constructs itself, rather than one supplied by the
201+
* platform through the `@next/cache-handlers` global or by `cacheHandlers`
202+
* config. Reads from a built-in handler are map lookups, so repeating one
203+
* within a request costs nothing; reads from a supplied handler may be a
204+
* network round trip. Unlike `isCustomCacheHandler`, this holds in production.
205+
*
206+
* Tracking the instances rather than the kinds is what keeps aliasing correct:
207+
* self-hosted, `remote` resolves to the same handler as `default` and so
208+
* reports as built-in, while a platform-supplied `remote` does not.
209+
*/
210+
export function isBuiltInCacheHandler(kind: string): boolean {
211+
const handler = reference[handlersMapSymbol]?.get(kind)
212+
213+
return (
214+
handler !== undefined &&
215+
Boolean(reference[builtInHandlersSymbol]?.has(handler))
216+
)
217+
}
218+
192219
/**
193220
* Get the dev-only tiered cache handler for a custom `kind`: a fast built-in
194221
* in-memory front handler in front of the user-configured backing handler, so

‎packages/next/src/server/use-cache/use-cache-probe-globals.ts‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -25,6 +25,7 @@ export type UseCacheProbeRequestSnapshot = {
2525
isDraftMode: boolean
2626
isHmrRefresh: boolean
2727
hmrRefreshHash: string | undefined
28+
requestStartTime: number
2829
}
2930

3031
/**

‎packages/next/src/server/use-cache/use-cache-probe-scheduler.ts‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -116,6 +116,7 @@ export function setupProbeScheduler(
116116
isDraftMode: workStore.isDraftMode ?? false,
117117
isHmrRefresh: outerRequestStore.isHmrRefresh ?? false,
118118
hmrRefreshHash: outerRequestStore.hmrRefreshHash,
119+
requestStartTime: workStore.requestStartTime,
119120
},
120121
timeoutMs: probeInternalTimeoutMs,
121122
}).then(

0 commit comments

Comments
 (0)