Unverified Commit 2850659b authored by Hendrik Liebau's avatar Hendrik Liebau Committed by GitHub

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="https://github.com/github/gh-stack">GitHub Stacks CLI</a> • <a
href="https://gh.io/stacks-feedback">Give Feedback 💬</a></sub>
parent 5ffbe9c3
...@@ -20,6 +20,7 @@ import { ...@@ -20,6 +20,7 @@ import {
tagsManifest, tagsManifest,
type TagManifestEntry, type TagManifestEntry,
} from '../incremental-cache/tags-manifest.external' } from '../incremental-cache/tags-manifest.external'
import { MIN_PRERENDERABLE_EXPIRE } from '../../use-cache/constants'
type PrivateCacheEntry = { type PrivateCacheEntry = {
entry: CacheEntry entry: CacheEntry
...@@ -83,10 +84,30 @@ export function createDefaultCacheHandler(maxSize: number): CacheHandler { ...@@ -83,10 +84,30 @@ export function createDefaultCacheHandler(maxSize: number): CacheHandler {
const entry = privateEntry.entry const entry = privateEntry.entry
// A negative `expire` is an eviction sentinel: the tiered cache handler
// (dev-only) marks a front entry for deletion by overwriting it with a
// negative `expire`, since the cache-handler interface has no per-key
// delete. Treat it as missing here, independently of the minimum
// retention below (which would otherwise keep it alive). This is distinct
// from `revalidate = -1` below, which keeps serving the entry but forces
// a revalidation.
if (entry.expire < 0) {
debug?.('get', cacheKey, 'evicted')
return undefined
}
// The dev server serves stale entries until they expire (see the file // The dev server serves stale entries until they expire (see the file
// overview); production drops them once past the revalidate time. // overview); production drops them once past the revalidate time. In dev,
// an entry is retained for at least `MIN_PRERENDERABLE_EXPIRE` so that
// entries with a short `expire` (for example a `cacheLife({ expire: 0 })`
// client-only cache) still linger long enough that a reload hits the
// cache. That minimum is the same threshold below which the "use cache"
// wrapper treats an entry as dynamic, so it only extends the retention of
// entries that are dynamic anyway. It affects retention only; the
// returned entry keeps its real `expire`, so staging decisions are
// unchanged.
const maxAgeSeconds = process.env.__NEXT_DEV_SERVER const maxAgeSeconds = process.env.__NEXT_DEV_SERVER
? entry.expire ? Math.max(entry.expire, MIN_PRERENDERABLE_EXPIRE)
: entry.revalidate : entry.revalidate
if ( if (
......
...@@ -107,26 +107,25 @@ export function initializeCacheHandlers(cacheMaxMemorySize: number): boolean { ...@@ -107,26 +107,25 @@ export function initializeCacheHandlers(cacheMaxMemorySize: number): boolean {
// Create a set of the cache handlers. // Create a set of the cache handlers.
reference[handlersSetSymbol] = new Set(handlersMap.values()) reference[handlersSetSymbol] = new Set(handlersMap.values())
// In development we add dedicated built-in in-memory handlers so that warm // In development we add dedicated built-in in-memory handlers so that reloads
// reloads are fast. These are always built-in handlers, never a // are fast. These are always built-in handlers, never a user-configured one,
// user-configured one, and are gated on the dev server so production behaves // and are gated on the dev server so production behaves exactly as
// exactly as configured. // configured.
if (process.env.__NEXT_DEV_SERVER) { if (process.env.__NEXT_DEV_SERVER) {
reference[memoryCacheDisabledSymbol] = cacheMaxMemorySize === 0 reference[memoryCacheDisabledSymbol] = cacheMaxMemorySize === 0
// Private caches are persisted here so warm reloads are fast. Private // Private caches are persisted here so reloads are fast. Private entries
// entries can hold data specific to the incoming request (for example, // can hold data specific to the incoming request (for example, derived from
// derived from its cookies or headers), so this is never the // its cookies or headers), so this is never the user-configured `default`
// user-configured `default` alias. Sized so it still caches under // alias. Sized so it still caches under `cacheMaxMemorySize: 0` (otherwise
// `cacheMaxMemorySize: 0` (otherwise it would become the no-op stub and // it would become the no-op stub and private reloads would miss).
// private reloads would miss).
reference[privateHandlerSymbol] = createDefaultCacheHandler( reference[privateHandlerSymbol] = createDefaultCacheHandler(
DEV_MEMORY_CACHE_SIZE DEV_MEMORY_CACHE_SIZE
) )
// Built-in front handlers, one per custom kind, and the tiered handlers // Built-in front handlers, one per custom kind, and the tiered handlers
// that place a front in front of a (possibly slow or remote) backing // that place a front in front of a (possibly slow or remote) backing
// handler so warm reads resolve in a microtask, are both created per kind // handler so cache hits resolve in a microtask, are both created per kind
// in `setCacheHandler`. // in `setCacheHandler`.
reference[devFrontHandlersSymbol] = new Map() reference[devFrontHandlersSymbol] = new Map()
reference[devTieredHandlersSymbol] = new Map() reference[devTieredHandlersSymbol] = new Map()
...@@ -178,7 +177,7 @@ export function isMemoryCacheDisabled(): boolean { ...@@ -178,7 +177,7 @@ export function isMemoryCacheDisabled(): boolean {
* Whether `kind` is backed by a real user-configured handler rather than the * Whether `kind` is backed by a real user-configured handler rather than the
* built-in in-memory default. Such a handler may be slow or remote, so in * built-in in-memory default. Such a handler may be slow or remote, so in
* development a built-in front handler is placed in front of it (see * development a built-in front handler is placed in front of it (see
* `getDevTieredCacheHandler`) to keep warm reads microtask-fast. The presence * `getDevTieredCacheHandler`) to keep cache hits microtask-fast. The presence
* of a dev front handler is the signal, since front handlers are created * of a dev front handler is the signal, since front handlers are created
* exactly for user-registered kinds. Always `false` in production. * exactly for user-registered kinds. Always `false` in production.
*/ */
...@@ -193,7 +192,7 @@ export function isCustomCacheHandler(kind: string): boolean { ...@@ -193,7 +192,7 @@ export function isCustomCacheHandler(kind: string): boolean {
/** /**
* Get the dev-only tiered cache handler for a custom `kind`: a fast built-in * Get the dev-only tiered cache handler for a custom `kind`: a fast built-in
* in-memory front handler in front of the user-configured backing handler, so * in-memory front handler in front of the user-configured backing handler, so
* warm reads resolve in a microtask. Returns `undefined` if there is none (a * cache hits resolve in a microtask. Returns `undefined` if there is none (a
* built-in kind, or production). * built-in kind, or production).
*/ */
export function getDevTieredCacheHandler( export function getDevTieredCacheHandler(
...@@ -307,11 +306,14 @@ export function setCacheHandler( ...@@ -307,11 +306,14 @@ export function setCacheHandler(
reference[handlersSetSymbol].add(cacheHandler) reference[handlersSetSymbol].add(cacheHandler)
// A user-configured handler may be slow or remote. In development, give it a // A user-configured handler may be slow or remote. In development, give it a
// dedicated built-in in-memory front handler so warm reads resolve in a // dedicated built-in in-memory front handler so cache hits resolve in a
// microtask, and pair the two into a tiered handler the wrapper reads // microtask, and pair the two into a tiered handler the wrapper reads
// through. Both are created alongside registration so their lifecycle matches // through. Both are created alongside registration so their lifecycle matches
// the backing handler's, and the front handler's presence is the signal that // the backing handler's, and the front handler's presence is the signal that
// this kind is backed by a real handler (see `isCustomCacheHandler`). // this kind is backed by a real handler (see `isCustomCacheHandler`). Being a
// built-in default handler, the front inherits the dev minimum retention, so
// a short-`expire` value still hits the front instead of falling through to
// the slow backing on every read.
if (process.env.__NEXT_DEV_SERVER) { if (process.env.__NEXT_DEV_SERVER) {
const frontHandler = createDefaultCacheHandler(DEV_MEMORY_CACHE_SIZE) const frontHandler = createDefaultCacheHandler(DEV_MEMORY_CACHE_SIZE)
reference[devFrontHandlersSymbol]?.set(kind, frontHandler) reference[devFrontHandlersSymbol]?.set(kind, frontHandler)
......
...@@ -14,7 +14,7 @@ export type CacheReadWriteHandler = Pick<CacheHandler, 'get' | 'set'> ...@@ -14,7 +14,7 @@ export type CacheReadWriteHandler = Pick<CacheHandler, 'get' | 'set'>
/** /**
* Development-only. Puts a fast built-in in-memory `front` handler in front of * Development-only. Puts a fast built-in in-memory `front` handler in front of
* a slower or persistent user-configured `backing` handler. Its only job is to * a slower or persistent user-configured `backing` handler. Its only job is to
* guarantee that warm reads resolve in a microtask (so they aren't counted as * guarantee that cache hits resolve in a microtask (so they aren't counted as
* cache misses at a staged-render boundary, which would otherwise surface a * cache misses at a staged-render boundary, which would otherwise surface a
* cold cache indicator), while keeping the front in sync with the backing. * cold cache indicator), while keeping the front in sync with the backing.
* *
...@@ -76,9 +76,9 @@ export function createTieredCacheHandler( ...@@ -76,9 +76,9 @@ export function createTieredCacheHandler(
const frontEntry = await front.get(cacheKey, softTags) const frontEntry = await front.get(cacheKey, softTags)
if (frontEntry) { if (frontEntry) {
// Warm hit: serve immediately (in a microtask). A background reconcile // Cache hit: serve immediately (in a microtask). A background reconcile
// keeps the front in sync with the backing for the next read; // keeps the front in sync with the backing for the next read;
// reconciles for the same key are serialized, so concurrent warm reads // reconciles for the same key are serialized, so concurrent cache hits
// don't hit the backing in parallel. // don't hit the backing in parallel.
scheduleBackgroundSync(cacheKey, () => scheduleBackgroundSync(cacheKey, () =>
reconcileFrontFromBacking( reconcileFrontFromBacking(
...@@ -104,7 +104,7 @@ export function createTieredCacheHandler( ...@@ -104,7 +104,7 @@ export function createTieredCacheHandler(
} }
// Mirror this freshly read backing entry into the front so the next read // Mirror this freshly read backing entry into the front so the next read
// is warm. The mirror is serialized per key: if a sync is already // hits it. The mirror is serialized per key: if a sync is already
// running, this chains after it, so the front converges to this read even // running, this chains after it, so the front converges to this read even
// if the backing changed since that sync started. // if the backing changed since that sync started.
const [servedEntry, mirroredEntry] = cloneCacheEntry(backingEntry) const [servedEntry, mirroredEntry] = cloneCacheEntry(backingEntry)
...@@ -130,9 +130,9 @@ export function createTieredCacheHandler( ...@@ -130,9 +130,9 @@ export function createTieredCacheHandler(
} }
/** /**
* After serving a warm front hit, consult the backing and mirror a newer entry * After serving a cache hit from the front, consult the backing and mirror a
* into the front for the next read. Runs in the background; failures are * newer entry into the front for the next read. Runs in the background;
* non-fatal. * failures are non-fatal.
*/ */
async function reconcileFrontFromBacking( async function reconcileFrontFromBacking(
front: CacheHandler, front: CacheHandler,
...@@ -186,17 +186,18 @@ async function mirrorIntoFront( ...@@ -186,17 +186,18 @@ async function mirrorIntoFront(
/** /**
* Build an already-expired copy of an entry, used to evict it from the front * Build an already-expired copy of an entry, used to evict it from the front
* handler (which has no per-key delete) once the backing no longer has it. In * handler (which has no per-key delete) once the backing no longer has it. The
* dev the default handler treats an entry as missing once `now > timestamp + * default handler treats a negative `expire` as an eviction sentinel and
* expire * 1000`, so `expire: 0` against the original (past) timestamp makes * reports the entry as missing on the next read. A negative `expire` is used
* the next read a miss. The value is never read once the entry is expired, but * rather than `0` because the dev front handler enforces a minimum retention,
* it must carry at least one byte because the built-in LRU cache refuses to * so a `0` `expire` would be kept alive by that minimum instead of evicted. The
* store size-0 entries. * value is never read once the entry is evicted, but it must carry at least one
* byte because the built-in LRU cache refuses to store size-0 entries.
*/ */
function toExpiredEntry(entry: CacheEntry): CacheEntry { function toExpiredEntry(entry: CacheEntry): CacheEntry {
return { return {
...entry, ...entry,
expire: 0, expire: -1,
value: new ReadableStream({ value: new ReadableStream({
start(controller) { start(controller) {
controller.enqueue(new Uint8Array(1)) controller.enqueue(new Uint8Array(1))
......
...@@ -1092,12 +1092,17 @@ async function collectResult( ...@@ -1092,12 +1092,17 @@ async function collectResult(
// `MIN_PRERENDERABLE_EXPIRE` (5 minutes) caps how long an entry lingers in // `MIN_PRERENDERABLE_EXPIRE` (5 minutes) caps how long an entry lingers in
// the dedicated in-memory private handler. It is the shortest `expire` that // the dedicated in-memory private handler. It is the shortest `expire` that
// isn't treated as dynamic; a smaller `expire` would exclude the entry from // isn't treated as dynamic; a smaller `expire` would exclude the entry from
// prerenders. The size-0 case (`cacheMaxMemorySize: 0`) deliberately does NOT // prerenders. Two other cases deliberately do NOT force this and keep their
// force this: it keeps its resolved cache life so that the cache entry can be // resolved cache life, relying instead on the dev handler's minimum retention
// considered prerenderable instead of being misread as a dynamic hole, and a // and a dev revalidation (see the cache-hit path below) to keep reloads fast
// separate dev revalidation (see the cache-hit path below) keeps its reloads // and fresh. The size-0 case (`cacheMaxMemorySize: 0`) keeps its life so the
// showing a fresh value. Custom kinds keep their real cache life too, since // entry can be considered prerenderable instead of being misread as a dynamic
// their backing handler owns it. // hole. An explicit short-`expire` public cache (e.g. `cacheLife({ expire: 0
// })`) keeps its life so it stays correctly excluded from static prerenders
// via its real `expire` while a reload still hits the cache; forcing
// `revalidate: 0` here would instead corrupt the cache life propagated to an
// enclosing cache and trigger the nested-dynamic error. A cache backed by a
// custom handler keeps its real cache life too, since that handler owns it.
const forceDynamicCacheLifeInDev = isPrivateCacheInDev const forceDynamicCacheLifeInDev = isPrivateCacheInDev
// If cacheLife() was used to set an explicit revalidate/expire/stale time we // If cacheLife() was used to set an explicit revalidate/expire/stale time we
...@@ -1640,7 +1645,7 @@ export async function cache( ...@@ -1640,7 +1645,7 @@ export async function cache(
if (isPrivate) { if (isPrivate) {
// Private caches normally go to the Resume Data Cache (RDC), not a cache // Private caches normally go to the Resume Data Cache (RDC), not a cache
// handler. In development we additionally persist them in a dedicated // handler. In development we additionally persist them in a dedicated
// built-in in-memory handler so that warm reloads are fast. // built-in in-memory handler so that reloads are fast.
if (process.env.__NEXT_DEV_SERVER) { if (process.env.__NEXT_DEV_SERVER) {
cacheHandler = getPrivateCacheHandler() cacheHandler = getPrivateCacheHandler()
} }
...@@ -1652,7 +1657,7 @@ export async function cache( ...@@ -1652,7 +1657,7 @@ export async function cache(
// In development, a user-configured (custom) handler may be slow or // In development, a user-configured (custom) handler may be slow or
// remote, so we read through a tiered handler that puts a built-in // remote, so we read through a tiered handler that puts a built-in
// in-memory front in front of it to keep warm reads microtask-fast. // in-memory front in front of it to keep cache hits microtask-fast.
// Built-in handlers (the default handler, and its size-0 replacement) are // Built-in handlers (the default handler, and its size-0 replacement) are
// already in-memory and used directly. // already in-memory and used directly.
if (process.env.__NEXT_DEV_SERVER && isCustomCacheHandler(kind)) { if (process.env.__NEXT_DEV_SERVER && isCustomCacheHandler(kind)) {
...@@ -2188,7 +2193,7 @@ export async function cache( ...@@ -2188,7 +2193,7 @@ export async function cache(
let stream: undefined | ReadableStream = undefined let stream: undefined | ReadableStream = undefined
// Set when a short-lived warm hit ends its cache read up front (dev only) so // Set when a short-lived cache hit ends its cache read up front (dev only) so
// the static-shell boundary doesn't count it as a phantom miss. Once set, the // the static-shell boundary doesn't count it as a phantom miss. Once set, the
// cache signal read is balanced, so serving must use a plain stream and skip // cache signal read is balanced, so serving must use a plain stream and skip
// any trailing cacheSignal.endRead() call. // any trailing cacheSignal.endRead() call.
...@@ -2945,7 +2950,19 @@ export async function cache( ...@@ -2945,7 +2950,19 @@ export async function cache(
if ( if (
entry === undefined || entry === undefined ||
currentTime > entry.timestamp + entry.expire * 1000 || // In dev, the built-in default handler retains a short-`expire` entry
// for at least `MIN_PRERENDERABLE_EXPIRE`, both when used directly
// and when fronting a custom cache handler. Apply that same minimum
// here so the retained entry is served and re-warmed in the
// background (below), rather than blocking to regenerate it on every
// read. The entry's real `expire` is untouched, so staging still
// treats it as dynamic.
currentTime >
entry.timestamp +
(process.env.__NEXT_DEV_SERVER
? Math.max(entry.expire, MIN_PRERENDERABLE_EXPIRE)
: entry.expire) *
1000 ||
(workStore.isStaticGeneration && (workStore.isStaticGeneration &&
currentTime > entry.timestamp + entry.revalidate * 1000) currentTime > entry.timestamp + entry.revalidate * 1000)
) { ) {
...@@ -3134,19 +3151,24 @@ export async function cache( ...@@ -3134,19 +3151,24 @@ export async function cache(
// Trigger a background revalidation when the entry is stale (past its // Trigger a background revalidation when the entry is stale (past its
// `revalidate`), so the next read gets a fresh value without blocking // `revalidate`), so the next read gets a fresh value without blocking
// this one. In development with the in-memory cache disabled // this one. Development additionally re-warms on every dynamic
// (`cacheMaxMemorySize: 0`), built-in entries keep their resolved // request render in two cases where the dev in-memory entry would
// (potentially non-dynamic) cache life, so an entry read back from // otherwise read back as fresh, so a subsequent reload still shows a
// the dev in-memory cache is normally still fresh and wouldn't // fresh value. The first is with the in-memory cache disabled
// revalidate on its own; revalidate those on every dynamic request // (`cacheMaxMemorySize: 0`), where built-in entries keep their
// render too, so each reload still shows a fresh value. // resolved (potentially non-dynamic) cache life. The second is a
// short-`expire` entry (an explicit dynamic or client-only cache,
// e.g. `cacheLife({ expire: 0 })`), which is retained for at least
// `MIN_PRERENDERABLE_EXPIRE` so it is served from the cache; this
// also covers custom handlers, re-executing and writing through to
// the backing.
let shouldTriggerBackgroundRevalidation = let shouldTriggerBackgroundRevalidation =
currentTime > entry.timestamp + entry.revalidate * 1000 currentTime > entry.timestamp + entry.revalidate * 1000
if ( if (
!shouldTriggerBackgroundRevalidation && !shouldTriggerBackgroundRevalidation &&
process.env.__NEXT_DEV_SERVER && process.env.__NEXT_DEV_SERVER &&
isMemoryCacheDisabled() && (entry.expire < MIN_PRERENDERABLE_EXPIRE ||
!isCustomCacheHandler(kind) (isMemoryCacheDisabled() && !isCustomCacheHandler(kind)))
) { ) {
switch (workUnitStore.type) { switch (workUnitStore.type) {
case 'request': case 'request':
......
...@@ -14,6 +14,11 @@ export default function Page() { ...@@ -14,6 +14,11 @@ export default function Page() {
/use-cache-private-runtime-prefetch /use-cache-private-runtime-prefetch
</Link> </Link>
</li> </li>
<li>
<Link href="/use-cache-expire-zero/nav">
/use-cache-expire-zero/nav
</Link>
</li>
<li> <li>
<Link href="/partial-prefetching/session-data"> <Link href="/partial-prefetching/session-data">
/partial-prefetching/session-data /partial-prefetching/session-data
......
import { Suspense } from 'react'
import { setTimeout } from 'timers/promises'
import { cacheLife } from 'next/cache'
export const prefetch = 'allow-runtime'
// A distinct slug per test keys a separate cache entry (so the first request
// for each slug is a genuine cold miss), while both tests share this one
// runtime-prefetchable page. Declaring the slugs also keeps `params` statically
// known, so the page shell doesn't depend on dynamic params. In development
// this does not pre-fill the cache.
export function generateStaticParams() {
return [{ slug: 'nav' }, { slug: 'reload' }]
}
async function getExpireZeroValue(slug: string) {
'use cache'
// An explicit short `expire` opts this public cache into a dynamic,
// client-only life: excluded from the static shell, but included in the
// runtime prefetch. The slug keys the entry; the value itself is just a
// timestamp.
cacheLife({ expire: 0 })
await setTimeout(1500)
return new Date().toISOString()
}
async function ExpireZeroCached({ slug }: Promise<{ slug: string }>) {
const value = await getExpireZeroValue(slug)
return <p id="expire-zero">{value}</p>
}
export default function Page({
params,
}: {
params: Promise<{ slug: string }>
}) {
return (
<Suspense fallback={<p id="expire-zero-fallback">Loading...</p>}>
<ExpireZeroCached slug={params.then(({ slug }) => slug)} />
</Suspense>
)
}
...@@ -189,6 +189,91 @@ describe('cache-components-dev-streaming', () => { ...@@ -189,6 +189,91 @@ describe('cache-components-dev-streaming', () => {
}) })
}) })
it('shows the short-expire-cache fallback on a cold client navigation but not on a warm one', async () => {
// A public `'use cache'` with an explicit short `expire` (`cacheLife({
// expire: 0 })`) is a runtime-prefetch route here, so its cached content
// belongs to the runtime shell stage. On a warm navigation the dev minimum
// retention keeps the entry available, and the client defers revealing the
// response until the shell has flushed, so the content arrives with the
// shell and the fallback isn't shown - just like a private cache.
const browser = await next.browser('/')
// Cold navigation: the cache misses and fills in the background, so the
// fallback is shown until the content streams in.
await browser.elementByCss('a[href="/use-cache-expire-zero/nav"]').click()
expect(await browser.elementByCss('#expire-zero-fallback').text()).toBe(
'Loading...'
)
expect(await browser.elementByCss('#expire-zero').text()).toBeDateString()
// Wait for the background write to settle so the next navigation hits the
// warm entry instead of racing a pending write.
await waitFor(2000)
// Hard-reload home so the warm navigation below starts from a fresh page.
await browser.loadPage(new URL('/', next.url).href)
// Warm navigation: record whether the fallback ever enters the DOM. It
// shouldn't, since the retained entry is delivered with the shell. (The
// client-side reveal race that this delivery relies on is covered by the
// private-cache test above, so we don't repeat its stress loop here.)
const fallbackObserver = observeNodeAppearances(browser, [
'expire-zero-fallback',
])
await fallbackObserver.observe()
await browser.elementByCss('a[href="/use-cache-expire-zero/nav"]').click()
expect(await browser.elementByCss('#expire-zero').text()).toBeDateString()
const appearanceCounts = await fallbackObserver.getResult()
expect(appearanceCounts).toEqual({
'expire-zero-fallback': 0,
})
})
it('serves a short-expire cache warm on reload and converges to a fresh value', async () => {
const browser = await next.browser('/use-cache-expire-zero/reload', {
waitHydration: false,
// Do not wait for "load"; inspect the page as it streams in.
waitUntil: 'commit',
})
// Cold load: the cache misses, so the fallback streams first, and the
// generated value streams in once generation completes. The value is a
// dynamic hole (real `expire: 0`), so it streams in after the shell.
expect(
await browser
.elementByCss('#expire-zero-fallback', { waitUntil: false })
.text()
).toBe('Loading...')
const coldValue = await browser
.elementByCss('#expire-zero', { waitUntil: false })
.text()
expect(coldValue).toBeDateString()
// Warm reload: the dev minimum retention keeps the short-expire entry, so
// the reload serves the previously cached value fast instead of
// regenerating it. A background revalidation regenerates a fresh entry for
// the next reload (asserted below). We wait for the streamed-in element
// without waiting for "load", so no retry is needed.
await browser.refresh({ waitUntil: 'commit' })
expect(
await browser.elementByCss('#expire-zero', { waitUntil: false }).text()
).toBe(coldValue)
// That warm reload re-warmed a fresh entry in the background, so a later
// reload converges to the new value. Read after "load" here (a plain
// refresh) since we want the settled value, not the streaming inspection
// above.
await retry(async () => {
await browser.refresh()
expect(await browser.elementById('expire-zero').text()).not.toBe(
coldValue
)
})
})
// The following are smoke tests that Cache Components validation still // The following are smoke tests that Cache Components validation still
// surfaces errors for both cold-cache renders (validated via a separate // surfaces errors for both cold-cache renders (validated via a separate
// warm-cache render) and warm-cache renders (validated via the streamed // warm-cache render) and warm-cache renders (validated via the streamed
......
import { Suspense } from 'react'
import { setTimeout } from 'timers/promises'
import { cacheLife } from 'next/cache'
// A public `'use cache'` routed through the custom (slow) handler, with an
// explicit short `expire`. In dev the built-in front handler applies a minimum
// retention, so a cache hit still resolves from the front in a microtask
// instead of paying the backing's latency on every read.
async function getCachedValue() {
'use cache'
// `expire: 0` gives a short, dynamic (client-only) cache life, excluded from
// static prerenders. Reusing it across client navigations would require
// opting the route into runtime prefetching (`prefetch = 'allow-runtime'`) so
// Cached Navigations embeds it into the client router cache; this fixture
// doesn't, since the test only exercises the dev front handler serving it
// warm on reloads.
cacheLife({ expire: 0 })
await setTimeout(1000)
return new Date().toISOString()
}
async function CachedValue() {
const value = await getCachedValue()
return <p id="value">{value}</p>
}
export default function Page() {
return (
<main>
<Suspense fallback={<p id="loading">Loading...</p>}>
<CachedValue />
</Suspense>
</main>
)
}
...@@ -40,6 +40,38 @@ describe('use-cache-custom-handler-dev', () => { ...@@ -40,6 +40,38 @@ describe('use-cache-custom-handler-dev', () => {
expect(await browser.hasElementByCss('[data-cold-cache-badge]')).toBe(false) expect(await browser.hasElementByCss('[data-cold-cache-badge]')).toBe(false)
}) })
it('serves a short-expire value warm through a custom handler and re-warms it on each reload', async () => {
const browser = await next.browser('/expire-zero', {
waitHydration: false,
// Do not wait for "load"; inspect the page as it streams in.
waitUntil: 'commit',
})
// Cold load: the custom handler misses, the value generates and is written
// through to both the backing handler and the dev-only in-memory front. We
// wait for the streamed-in element without waiting for "load".
const coldValue = await browser
.elementByCss('#value', { waitUntil: false })
.text()
expect(coldValue).toBeDateString()
// Warm reload: served fast from the front, whose minimum retention keeps
// the short-`expire` entry. The custom handler's slow `get` isn't on the
// critical path, and the short `expire` no longer evicts the front entry on
// every read, so the same cached value shows.
await browser.refresh({ waitUntil: 'commit' })
expect(
await browser.elementByCss('#value', { waitUntil: false }).text()
).toBe(coldValue)
// Each warm reload re-executes the cache function and writes through to the
// backing, so reloads converge to a fresh value.
await retry(async () => {
await browser.refresh()
expect(await browser.elementById('value').text()).not.toBe(coldValue)
})
})
it('stops serving a front-cached entry after the backing cache is purged out-of-band', async () => { it('stops serving a front-cached entry after the backing cache is purged out-of-band', async () => {
const browser = await next.browser('/purged') const browser = await next.browser('/purged')
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment