Skip to content

Commit 2850659

Browse files
authored
Cache short-expire 'use cache' values across dev reloads (#95362)
Development has recently gained several mechanisms that make `'use cache'` reloads fast under Cache Components: `'use cache: private'` entries are persisted in a dedicated in-memory handler, `cacheMaxMemorySize: 0` uses a real in-memory handler instead of the no-op stub, and custom handlers are fronted by a fast built-in handler through the tiered handler. One case was still missing. A value that opts into a dynamic, client-only life with an explicit short `expire` (for example `cacheLife({ expire: 0 })`, or the built-in `'seconds'` profile) was treated as a miss on every reload, for both the built-in default handler and custom handlers, so reloads re-ran the cache function and streamed slowly. The reason is that `expire` is the value's expiration bound, the longest it may still be served before it has to be treated as expired. That is its purpose in both dev and production; what differs is which threshold the built-in in-memory handler enforces. In `next dev` it serves stale entries up to `expire` to keep reloads fast, whereas in production it drops them earlier, once past `revalidate`. An `expire` of zero therefore leaves the dev handler no window in which a reload can be served from the cache, and the wrapper's serve-vs-regenerate check, which also keys on `expire`, regenerates instead. This change extends the same dev-only treatment to those values without altering their resolved cache life. The built-in default handler now retains an entry for at least `MIN_PRERENDERABLE_EXPIRE` in dev, a minimum the custom front handler inherits by being a built-in default handler, and the wrapper applies the same minimum when deciding whether to serve or regenerate. That affects the retain and serve decisions only; the entry keeps its real `expire`, so the staged dev render still resolves it at the appropriate stage rather than in the shell stage. A short-`expire` entry is also re-warmed in the background on every dynamic request render, so a reload serves the previously cached value immediately and the freshly recomputed one appears on the next reload. This is the same stale-while-revalidate trade-off already accepted for the private-cache and `cacheMaxMemorySize: 0` dev optimizations, which likewise favor a fast reload over serving a value these configurations would not otherwise cache at all. For custom handlers the re-warm re-executes the function and writes through to the backing. Unlike the private-cache case, we deliberately do not force a dynamic cache life here, because forcing `revalidate: 0` would leak into the cache life propagated to an enclosing `'use cache'` and trip the nested-dynamic error with the wrong message. And unlike the size-0 case, keeping the resolved life alone is not enough, because a short `expire` is exactly what makes the dev handler drop the entry, which is why the minimum retention is needed. Because the dev front handler now enforces that minimum, the tiered handler can no longer evict a stale front entry by writing `expire: 0` (the minimum would keep it alive), so `toExpiredEntry` now writes a negative `expire`, which the default handler recognizes as an eviction sentinel and reports as missing regardless of the retention minimum. This mirrors the existing `revalidate = -1` convention, though a negative `expire` means the entry is dropped rather than served-but-revalidated. Everything is gated on `process.env.__NEXT_DEV_SERVER`, so production behaves exactly as before: short-`expire` values keep their real cache life, and configured handlers are used directly. New development tests cover the built-in and custom-handler cases, asserting that a cache-miss navigation shows the Suspense fallback while a cache-hit one does not, and that a reload serves the cached value yet converges to a fresh one. --- <sub>Stack created with <a href="GitHub">https://github.com/github/gh-stack">GitHub Stacks CLI</a> • <a href="Give" rel="nofollow">https://gh.io/stacks-feedback">Give Feedback 💬</a></sub>
1 parent 5ffbe9c commit 2850659

9 files changed

Lines changed: 296 additions & 49 deletions

File tree

‎packages/next/src/server/lib/cache-handlers/default.ts‎

Lines changed: 23 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -20,6 +20,7 @@ import {
2020
tagsManifest,
2121
type TagManifestEntry,
2222
} from '../incremental-cache/tags-manifest.external'
23+
import { MIN_PRERENDERABLE_EXPIRE } from '../../use-cache/constants'
2324

2425
type PrivateCacheEntry = {
2526
entry: CacheEntry
@@ -83,10 +84,30 @@ export function createDefaultCacheHandler(maxSize: number): CacheHandler {
8384

8485
const entry = privateEntry.entry
8586

87+
// A negative `expire` is an eviction sentinel: the tiered cache handler
88+
// (dev-only) marks a front entry for deletion by overwriting it with a
89+
// negative `expire`, since the cache-handler interface has no per-key
90+
// delete. Treat it as missing here, independently of the minimum
91+
// retention below (which would otherwise keep it alive). This is distinct
92+
// from `revalidate = -1` below, which keeps serving the entry but forces
93+
// a revalidation.
94+
if (entry.expire < 0) {
95+
debug?.('get', cacheKey, 'evicted')
96+
return undefined
97+
}
98+
8699
// The dev server serves stale entries until they expire (see the file
87-
// overview); production drops them once past the revalidate time.
100+
// overview); production drops them once past the revalidate time. In dev,
101+
// an entry is retained for at least `MIN_PRERENDERABLE_EXPIRE` so that
102+
// entries with a short `expire` (for example a `cacheLife({ expire: 0 })`
103+
// client-only cache) still linger long enough that a reload hits the
104+
// cache. That minimum is the same threshold below which the "use cache"
105+
// wrapper treats an entry as dynamic, so it only extends the retention of
106+
// entries that are dynamic anyway. It affects retention only; the
107+
// returned entry keeps its real `expire`, so staging decisions are
108+
// unchanged.
88109
const maxAgeSeconds = process.env.__NEXT_DEV_SERVER
89-
? entry.expire
110+
? Math.max(entry.expire, MIN_PRERENDERABLE_EXPIRE)
90111
: entry.revalidate
91112

92113
if (

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

Lines changed: 17 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -107,26 +107,25 @@ export function initializeCacheHandlers(cacheMaxMemorySize: number): boolean {
107107
// Create a set of the cache handlers.
108108
reference[handlersSetSymbol] = new Set(handlersMap.values())
109109

110-
// In development we add dedicated built-in in-memory handlers so that warm
111-
// reloads are fast. These are always built-in handlers, never a
112-
// user-configured one, and are gated on the dev server so production behaves
113-
// exactly as configured.
110+
// In development we add dedicated built-in in-memory handlers so that reloads
111+
// are fast. These are always built-in handlers, never a user-configured one,
112+
// and are gated on the dev server so production behaves exactly as
113+
// configured.
114114
if (process.env.__NEXT_DEV_SERVER) {
115115
reference[memoryCacheDisabledSymbol] = cacheMaxMemorySize === 0
116116

117-
// Private caches are persisted here so warm reloads are fast. Private
118-
// entries can hold data specific to the incoming request (for example,
119-
// derived from its cookies or headers), so this is never the
120-
// user-configured `default` alias. Sized so it still caches under
121-
// `cacheMaxMemorySize: 0` (otherwise it would become the no-op stub and
122-
// private reloads would miss).
117+
// Private caches are persisted here so reloads are fast. Private entries
118+
// can hold data specific to the incoming request (for example, derived from
119+
// its cookies or headers), so this is never the user-configured `default`
120+
// alias. Sized so it still caches under `cacheMaxMemorySize: 0` (otherwise
121+
// it would become the no-op stub and private reloads would miss).
123122
reference[privateHandlerSymbol] = createDefaultCacheHandler(
124123
DEV_MEMORY_CACHE_SIZE
125124
)
126125

127126
// Built-in front handlers, one per custom kind, and the tiered handlers
128127
// that place a front in front of a (possibly slow or remote) backing
129-
// handler so warm reads resolve in a microtask, are both created per kind
128+
// handler so cache hits resolve in a microtask, are both created per kind
130129
// in `setCacheHandler`.
131130
reference[devFrontHandlersSymbol] = new Map()
132131
reference[devTieredHandlersSymbol] = new Map()
@@ -178,7 +177,7 @@ export function isMemoryCacheDisabled(): boolean {
178177
* Whether `kind` is backed by a real user-configured handler rather than the
179178
* built-in in-memory default. Such a handler may be slow or remote, so in
180179
* development a built-in front handler is placed in front of it (see
181-
* `getDevTieredCacheHandler`) to keep warm reads microtask-fast. The presence
180+
* `getDevTieredCacheHandler`) to keep cache hits microtask-fast. The presence
182181
* of a dev front handler is the signal, since front handlers are created
183182
* exactly for user-registered kinds. Always `false` in production.
184183
*/
@@ -193,7 +192,7 @@ export function isCustomCacheHandler(kind: string): boolean {
193192
/**
194193
* Get the dev-only tiered cache handler for a custom `kind`: a fast built-in
195194
* in-memory front handler in front of the user-configured backing handler, so
196-
* warm reads resolve in a microtask. Returns `undefined` if there is none (a
195+
* cache hits resolve in a microtask. Returns `undefined` if there is none (a
197196
* built-in kind, or production).
198197
*/
199198
export function getDevTieredCacheHandler(
@@ -307,11 +306,14 @@ export function setCacheHandler(
307306
reference[handlersSetSymbol].add(cacheHandler)
308307

309308
// A user-configured handler may be slow or remote. In development, give it a
310-
// dedicated built-in in-memory front handler so warm reads resolve in a
309+
// dedicated built-in in-memory front handler so cache hits resolve in a
311310
// microtask, and pair the two into a tiered handler the wrapper reads
312311
// through. Both are created alongside registration so their lifecycle matches
313312
// the backing handler's, and the front handler's presence is the signal that
314-
// this kind is backed by a real handler (see `isCustomCacheHandler`).
313+
// this kind is backed by a real handler (see `isCustomCacheHandler`). Being a
314+
// built-in default handler, the front inherits the dev minimum retention, so
315+
// a short-`expire` value still hits the front instead of falling through to
316+
// the slow backing on every read.
315317
if (process.env.__NEXT_DEV_SERVER) {
316318
const frontHandler = createDefaultCacheHandler(DEV_MEMORY_CACHE_SIZE)
317319
reference[devFrontHandlersSymbol]?.set(kind, frontHandler)

‎packages/next/src/server/use-cache/tiered-cache-handler.ts‎

Lines changed: 15 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -14,7 +14,7 @@ export type CacheReadWriteHandler = Pick<CacheHandler, 'get' | 'set'>
1414
/**
1515
* Development-only. Puts a fast built-in in-memory `front` handler in front of
1616
* a slower or persistent user-configured `backing` handler. Its only job is to
17-
* guarantee that warm reads resolve in a microtask (so they aren't counted as
17+
* guarantee that cache hits resolve in a microtask (so they aren't counted as
1818
* cache misses at a staged-render boundary, which would otherwise surface a
1919
* cold cache indicator), while keeping the front in sync with the backing.
2020
*
@@ -76,9 +76,9 @@ export function createTieredCacheHandler(
7676
const frontEntry = await front.get(cacheKey, softTags)
7777

7878
if (frontEntry) {
79-
// Warm hit: serve immediately (in a microtask). A background reconcile
79+
// Cache hit: serve immediately (in a microtask). A background reconcile
8080
// keeps the front in sync with the backing for the next read;
81-
// reconciles for the same key are serialized, so concurrent warm reads
81+
// reconciles for the same key are serialized, so concurrent cache hits
8282
// don't hit the backing in parallel.
8383
scheduleBackgroundSync(cacheKey, () =>
8484
reconcileFrontFromBacking(
@@ -104,7 +104,7 @@ export function createTieredCacheHandler(
104104
}
105105

106106
// Mirror this freshly read backing entry into the front so the next read
107-
// is warm. The mirror is serialized per key: if a sync is already
107+
// hits it. The mirror is serialized per key: if a sync is already
108108
// running, this chains after it, so the front converges to this read even
109109
// if the backing changed since that sync started.
110110
const [servedEntry, mirroredEntry] = cloneCacheEntry(backingEntry)
@@ -130,9 +130,9 @@ export function createTieredCacheHandler(
130130
}
131131

132132
/**
133-
* After serving a warm front hit, consult the backing and mirror a newer entry
134-
* into the front for the next read. Runs in the background; failures are
135-
* non-fatal.
133+
* After serving a cache hit from the front, consult the backing and mirror a
134+
* newer entry into the front for the next read. Runs in the background;
135+
* failures are non-fatal.
136136
*/
137137
async function reconcileFrontFromBacking(
138138
front: CacheHandler,
@@ -186,17 +186,18 @@ async function mirrorIntoFront(
186186

187187
/**
188188
* Build an already-expired copy of an entry, used to evict it from the front
189-
* handler (which has no per-key delete) once the backing no longer has it. In
190-
* dev the default handler treats an entry as missing once `now > timestamp +
191-
* expire * 1000`, so `expire: 0` against the original (past) timestamp makes
192-
* the next read a miss. The value is never read once the entry is expired, but
193-
* it must carry at least one byte because the built-in LRU cache refuses to
194-
* store size-0 entries.
189+
* handler (which has no per-key delete) once the backing no longer has it. The
190+
* default handler treats a negative `expire` as an eviction sentinel and
191+
* reports the entry as missing on the next read. A negative `expire` is used
192+
* rather than `0` because the dev front handler enforces a minimum retention,
193+
* so a `0` `expire` would be kept alive by that minimum instead of evicted. The
194+
* value is never read once the entry is evicted, but it must carry at least one
195+
* byte because the built-in LRU cache refuses to store size-0 entries.
195196
*/
196197
function toExpiredEntry(entry: CacheEntry): CacheEntry {
197198
return {
198199
...entry,
199-
expire: 0,
200+
expire: -1,
200201
value: new ReadableStream({
201202
start(controller) {
202203
controller.enqueue(new Uint8Array(1))

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

Lines changed: 40 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -1092,12 +1092,17 @@ async function collectResult(
10921092
// `MIN_PRERENDERABLE_EXPIRE` (5 minutes) caps how long an entry lingers in
10931093
// the dedicated in-memory private handler. It is the shortest `expire` that
10941094
// isn't treated as dynamic; a smaller `expire` would exclude the entry from
1095-
// prerenders. The size-0 case (`cacheMaxMemorySize: 0`) deliberately does NOT
1096-
// force this: it keeps its resolved cache life so that the cache entry can be
1097-
// considered prerenderable instead of being misread as a dynamic hole, and a
1098-
// separate dev revalidation (see the cache-hit path below) keeps its reloads
1099-
// showing a fresh value. Custom kinds keep their real cache life too, since
1100-
// their backing handler owns it.
1095+
// prerenders. Two other cases deliberately do NOT force this and keep their
1096+
// resolved cache life, relying instead on the dev handler's minimum retention
1097+
// and a dev revalidation (see the cache-hit path below) to keep reloads fast
1098+
// and fresh. The size-0 case (`cacheMaxMemorySize: 0`) keeps its life so the
1099+
// entry can be considered prerenderable instead of being misread as a dynamic
1100+
// hole. An explicit short-`expire` public cache (e.g. `cacheLife({ expire: 0
1101+
// })`) keeps its life so it stays correctly excluded from static prerenders
1102+
// via its real `expire` while a reload still hits the cache; forcing
1103+
// `revalidate: 0` here would instead corrupt the cache life propagated to an
1104+
// enclosing cache and trigger the nested-dynamic error. A cache backed by a
1105+
// custom handler keeps its real cache life too, since that handler owns it.
11011106
const forceDynamicCacheLifeInDev = isPrivateCacheInDev
11021107

11031108
// If cacheLife() was used to set an explicit revalidate/expire/stale time we
@@ -1640,7 +1645,7 @@ export async function cache(
16401645
if (isPrivate) {
16411646
// Private caches normally go to the Resume Data Cache (RDC), not a cache
16421647
// handler. In development we additionally persist them in a dedicated
1643-
// built-in in-memory handler so that warm reloads are fast.
1648+
// built-in in-memory handler so that reloads are fast.
16441649
if (process.env.__NEXT_DEV_SERVER) {
16451650
cacheHandler = getPrivateCacheHandler()
16461651
}
@@ -1652,7 +1657,7 @@ export async function cache(
16521657

16531658
// In development, a user-configured (custom) handler may be slow or
16541659
// remote, so we read through a tiered handler that puts a built-in
1655-
// in-memory front in front of it to keep warm reads microtask-fast.
1660+
// in-memory front in front of it to keep cache hits microtask-fast.
16561661
// Built-in handlers (the default handler, and its size-0 replacement) are
16571662
// already in-memory and used directly.
16581663
if (process.env.__NEXT_DEV_SERVER && isCustomCacheHandler(kind)) {
@@ -2188,7 +2193,7 @@ export async function cache(
21882193

21892194
let stream: undefined | ReadableStream = undefined
21902195

2191-
// Set when a short-lived warm hit ends its cache read up front (dev only) so
2196+
// Set when a short-lived cache hit ends its cache read up front (dev only) so
21922197
// the static-shell boundary doesn't count it as a phantom miss. Once set, the
21932198
// cache signal read is balanced, so serving must use a plain stream and skip
21942199
// any trailing cacheSignal.endRead() call.
@@ -2945,7 +2950,19 @@ export async function cache(
29452950

29462951
if (
29472952
entry === undefined ||
2948-
currentTime > entry.timestamp + entry.expire * 1000 ||
2953+
// In dev, the built-in default handler retains a short-`expire` entry
2954+
// for at least `MIN_PRERENDERABLE_EXPIRE`, both when used directly
2955+
// and when fronting a custom cache handler. Apply that same minimum
2956+
// here so the retained entry is served and re-warmed in the
2957+
// background (below), rather than blocking to regenerate it on every
2958+
// read. The entry's real `expire` is untouched, so staging still
2959+
// treats it as dynamic.
2960+
currentTime >
2961+
entry.timestamp +
2962+
(process.env.__NEXT_DEV_SERVER
2963+
? Math.max(entry.expire, MIN_PRERENDERABLE_EXPIRE)
2964+
: entry.expire) *
2965+
1000 ||
29492966
(workStore.isStaticGeneration &&
29502967
currentTime > entry.timestamp + entry.revalidate * 1000)
29512968
) {
@@ -3134,19 +3151,24 @@ export async function cache(
31343151

31353152
// Trigger a background revalidation when the entry is stale (past its
31363153
// `revalidate`), so the next read gets a fresh value without blocking
3137-
// this one. In development with the in-memory cache disabled
3138-
// (`cacheMaxMemorySize: 0`), built-in entries keep their resolved
3139-
// (potentially non-dynamic) cache life, so an entry read back from
3140-
// the dev in-memory cache is normally still fresh and wouldn't
3141-
// revalidate on its own; revalidate those on every dynamic request
3142-
// render too, so each reload still shows a fresh value.
3154+
// this one. Development additionally re-warms on every dynamic
3155+
// request render in two cases where the dev in-memory entry would
3156+
// otherwise read back as fresh, so a subsequent reload still shows a
3157+
// fresh value. The first is with the in-memory cache disabled
3158+
// (`cacheMaxMemorySize: 0`), where built-in entries keep their
3159+
// resolved (potentially non-dynamic) cache life. The second is a
3160+
// short-`expire` entry (an explicit dynamic or client-only cache,
3161+
// e.g. `cacheLife({ expire: 0 })`), which is retained for at least
3162+
// `MIN_PRERENDERABLE_EXPIRE` so it is served from the cache; this
3163+
// also covers custom handlers, re-executing and writing through to
3164+
// the backing.
31433165
let shouldTriggerBackgroundRevalidation =
31443166
currentTime > entry.timestamp + entry.revalidate * 1000
31453167
if (
31463168
!shouldTriggerBackgroundRevalidation &&
31473169
process.env.__NEXT_DEV_SERVER &&
3148-
isMemoryCacheDisabled() &&
3149-
!isCustomCacheHandler(kind)
3170+
(entry.expire < MIN_PRERENDERABLE_EXPIRE ||
3171+
(isMemoryCacheDisabled() && !isCustomCacheHandler(kind)))
31503172
) {
31513173
switch (workUnitStore.type) {
31523174
case 'request':

‎test/development/app-dir/cache-components-dev-streaming/app/page.tsx‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -14,6 +14,11 @@ export default function Page() {
1414
/use-cache-private-runtime-prefetch
1515
</Link>
1616
</li>
17+
<li>
18+
<Link href="/use-cache-expire-zero/nav">
19+
/use-cache-expire-zero/nav
20+
</Link>
21+
</li>
1722
<li>
1823
<Link href="/partial-prefetching/session-data">
1924
/partial-prefetching/session-data
Lines changed: 43 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,43 @@
1+
import { Suspense } from 'react'
2+
import { setTimeout } from 'timers/promises'
3+
import { cacheLife } from 'next/cache'
4+
5+
export const prefetch = 'allow-runtime'
6+
7+
// A distinct slug per test keys a separate cache entry (so the first request
8+
// for each slug is a genuine cold miss), while both tests share this one
9+
// runtime-prefetchable page. Declaring the slugs also keeps `params` statically
10+
// known, so the page shell doesn't depend on dynamic params. In development
11+
// this does not pre-fill the cache.
12+
export function generateStaticParams() {
13+
return [{ slug: 'nav' }, { slug: 'reload' }]
14+
}
15+
16+
async function getExpireZeroValue(slug: string) {
17+
'use cache'
18+
// An explicit short `expire` opts this public cache into a dynamic,
19+
// client-only life: excluded from the static shell, but included in the
20+
// runtime prefetch. The slug keys the entry; the value itself is just a
21+
// timestamp.
22+
cacheLife({ expire: 0 })
23+
await setTimeout(1500)
24+
return new Date().toISOString()
25+
}
26+
27+
async function ExpireZeroCached({ slug }: Promise<{ slug: string }>) {
28+
const value = await getExpireZeroValue(slug)
29+
30+
return <p id="expire-zero">{value}</p>
31+
}
32+
33+
export default function Page({
34+
params,
35+
}: {
36+
params: Promise<{ slug: string }>
37+
}) {
38+
return (
39+
<Suspense fallback={<p id="expire-zero-fallback">Loading...</p>}>
40+
<ExpireZeroCached slug={params.then(({ slug }) => slug)} />
41+
</Suspense>
42+
)
43+
}

0 commit comments

Comments
 (0)