Unverified Commit 96e9a8e2 authored by Hendrik Liebau's avatar Hendrik Liebau Committed by GitHub

Make `cacheMaxMemorySize: 0` and custom cache handlers fast in dev (#94784)

When Cache Components is enabled, `next dev` treats a `'use cache'`
value as a miss and renders as if the cache were empty whenever the read
does not resolve right away. Two development configurations triggered
that even for values that were already cached, so warm reloads streamed
slowly instead of serving the cached value: `cacheMaxMemorySize: 0`
replaced the built-in default handler with a no-op stub, so nothing was
cached at all, and custom cache handlers with a slow or remote `get` did
not return in time.

For the size-0 case, development now uses a real in-memory handler
instead of the no-op stub, and the `'use cache'` wrapper forces a
dynamic cache life (`revalidate: 0`, a 5-minute `expire`) for it, the
same treatment private caches already receive, so every read serves the
stale entry and re-warms a fresh one in the background. This also fixes
the dev private handler, which was sized from `cacheMaxMemorySize` and
so degraded to the no-op stub whenever `cacheMaxMemorySize: 0` was set.

Custom cache handlers keep their configured cache life, since their
backing owns it. Instead we put a fast built-in in-memory front handler
in front of the configured one through the new `TieredCacheHandler`,
which serves warm reads from the front, writes through to both tiers,
and reconciles the front against the backing in the background, evicting
the front entry when the backing no longer has it (the handler interface
has no per-key delete, so it overwrites the entry with an
already-expired copy). These dev-only handlers are kept out of the
registered handler set and merged in only where tag operations iterate,
so `revalidateTag` still reaches them.

Everything is gated on `process.env.__NEXT_DEV_SERVER`, so production is
unchanged: `cacheMaxMemorySize: 0` still caches nothing, private entries
are still never persisted, and configured handlers are used directly.
New development test suites cover the size-0 and custom-handler
behavior.
parent 13460abb
...@@ -1362,5 +1362,6 @@ ...@@ -1362,5 +1362,6 @@
"1361": "`catchError` can only be used in Client Components.", "1361": "`catchError` can only be used in Client Components.",
"1362": "A <Link prefetch={true}> navigated to \"%s\", but Partial Prefetching is not enabled for that route, so its dynamic data was included in the prefetch. Enable Partial Prefetching app-wide by setting \\`partialPrefetching: true\\` in next.config, or per-route by exporting \\`const prefetch = 'partial'\\` from the page or layout.", "1362": "A <Link prefetch={true}> navigated to \"%s\", but Partial Prefetching is not enabled for that route, so its dynamic data was included in the prefetch. Enable Partial Prefetching app-wide by setting \\`partialPrefetching: true\\` in next.config, or per-route by exporting \\`const prefetch = 'partial'\\` from the page or layout.",
"1363": "\\`experimental.turbopackRustReactCompiler\\` is only supported with Turbopack. Please remove the option or run Next.js with Turbopack in %s.", "1363": "\\`experimental.turbopackRustReactCompiler\\` is only supported with Turbopack. Please remove the option or run Next.js with Turbopack in %s.",
"1364": "\\`experimental.turbopackRustReactCompiler\\` requires \\`reactCompiler\\` to be enabled. Please add \\`reactCompiler: true\\` in %s." "1364": "\\`experimental.turbopackRustReactCompiler\\` requires \\`reactCompiler\\` to be enabled. Please add \\`reactCompiler: true\\` in %s.",
"1365": "Expected a dev tiered cache handler for kind \"%s\"."
} }
import type { CacheEntry } from '../lib/cache-handlers/types'
/**
* Tees a cache entry's single-use value stream into two independent entries.
* The original entry is mutated to hold one branch of the tee, and a clone is
* returned holding the other, so both can be consumed independently.
*/
export function cloneCacheEntry(entry: CacheEntry): [CacheEntry, CacheEntry] {
const [streamA, streamB] = entry.value.tee()
entry.value = streamA
const clonedEntry: CacheEntry = {
value: streamB,
timestamp: entry.timestamp,
revalidate: entry.revalidate,
expire: entry.expire,
stale: entry.stale,
tags: entry.tags,
}
return [entry, clonedEntry]
}
import type { CacheEntry, CacheHandler } from '../lib/cache-handlers/types'
import { workAsyncStorage } from '../app-render/work-async-storage.external'
import { cloneCacheEntry } from './clone-cache-entry'
/**
* The subset of the cache-handler interface used on the per-invocation
* read/write path in the "use cache" wrapper. Tag operations are intentionally
* excluded: they are applied to the front and backing handlers individually by
* the registry iterators (`getCacheHandlers` / `getCacheHandlerEntries`), never
* through this composite, so the composite is never registered.
*/
export type CacheReadWriteHandler = Pick<CacheHandler, 'get' | 'set'>
/**
* 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
* guarantee that warm reads resolve in a microtask (so they aren't counted as
* cache misses at a staged-render boundary, which would otherwise surface a
* cold cache indicator), while keeping the front in sync with the backing.
*
* It implements only `get` and `set` because that is all the wrapper calls on
* its handler. Regeneration is never done here; this only reads, mirrors, and
* writes through.
*
* The handler is a per-kind singleton (the front and backing are both shared),
* so its in-flight map can serialize background front syncs for a key across
* concurrent reads, running them one at a time instead of in parallel.
*/
export function createTieredCacheHandler(
front: CacheHandler,
backing: CacheHandler
): CacheReadWriteHandler {
// Holds the in-flight (or chained) background sync per key, so a sync for a
// key runs after any earlier one for that key rather than in parallel.
const inFlightSyncs = new Map<string, Promise<void>>()
function scheduleBackgroundSync(
cacheKey: string,
sync: () => Promise<void>
): void {
// Serialize syncs per key: chain this one after any in-flight sync rather
// than running a second in parallel. The trailing sync still re-reads the
// backing, so the front converges to the latest state; a later read is
// never dropped in favor of an earlier, possibly stale, in-flight read.
const previous = inFlightSyncs.get(cacheKey)
let pending: Promise<void>
if (previous) {
pending = previous.then(sync)
} else {
pending = sync()
}
pending = pending.finally(() => {
if (inFlightSyncs.get(cacheKey) === pending) {
inFlightSyncs.delete(cacheKey)
}
})
inFlightSyncs.set(cacheKey, pending)
// Register the sync on the current request's revalidation writes so it is
// awaited rather than left untracked. Reading the work store here (rather
// than capturing it at construction) is what lets the handler be a shared
// singleton; `get` always runs within the request's async context, so the
// store is present.
const workStore = workAsyncStorage.getStore()
if (workStore) {
workStore.pendingRevalidateWrites ??= []
workStore.pendingRevalidateWrites.push(pending)
}
}
return {
async get(cacheKey, softTags) {
const frontEntry = await front.get(cacheKey, softTags)
if (frontEntry) {
// Warm hit: serve immediately (in a microtask). A background reconcile
// keeps the front in sync with the backing for the next read;
// reconciles for the same key are serialized, so concurrent warm reads
// don't hit the backing in parallel.
scheduleBackgroundSync(cacheKey, () =>
reconcileFrontFromBacking(
front,
backing,
cacheKey,
softTags,
frontEntry
)
)
return frontEntry
}
// Cold or evicted front entry: we pay the backing latency here (this is a
// read that may legitimately surface a cold cache indicator). A miss
// returns undefined and the "use cache" wrapper generates the entry and
// writes it through both tiers via `set`.
const backingEntry = await backing.get(cacheKey, softTags)
if (!backingEntry) {
return undefined
}
// 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
// running, this chains after it, so the front converges to this read even
// if the backing changed since that sync started.
const [servedEntry, mirroredEntry] = cloneCacheEntry(backingEntry)
scheduleBackgroundSync(cacheKey, () =>
mirrorIntoFront(front, cacheKey, mirroredEntry)
)
return servedEntry
},
async set(cacheKey, pendingEntry) {
// Write through to both tiers. The entry's value stream is single-use, so
// tee it into one entry per tier.
const entry = await pendingEntry
const [frontEntry, backingEntry] = cloneCacheEntry(entry)
await Promise.all([
front.set(cacheKey, Promise.resolve(frontEntry)),
backing.set(cacheKey, Promise.resolve(backingEntry)),
])
},
}
}
/**
* After serving a warm front hit, consult the backing and mirror a newer entry
* into the front for the next read. Runs in the background; failures are
* non-fatal.
*/
async function reconcileFrontFromBacking(
front: CacheHandler,
backing: CacheHandler,
cacheKey: string,
softTags: string[],
frontEntry: CacheEntry
): Promise<void> {
try {
const backingEntry = await backing.get(cacheKey, softTags)
if (!backingEntry) {
// The backing no longer has this entry (it was purged out-of-band). The
// cache-handler interface has no per-key delete, so evict the front entry
// by overwriting it with an already-expired copy: the next read sees a
// front miss, falls through to the (also empty) backing, and the wrapper
// regenerates. The entry we just served was the last stale read.
await front.set(cacheKey, Promise.resolve(toExpiredEntry(frontEntry)))
return
}
if (backingEntry.timestamp > frontEntry.timestamp) {
await front.set(cacheKey, Promise.resolve(backingEntry))
} else {
// The front is already up to date, so the backing entry goes unused.
// Release its stream without awaiting: a teed stream's `cancel()` only
// settles once the sibling branch (retained by the backing handler) is
// also cancelled, so awaiting it here would hang the reconcile.
void backingEntry.value.cancel()
}
} catch {
// Background warming; failures are non-fatal.
}
}
/**
* Mirror a backing entry into the front.
*/
async function mirrorIntoFront(
front: CacheHandler,
cacheKey: string,
entry: CacheEntry
): Promise<void> {
try {
await front.set(cacheKey, Promise.resolve(entry))
} catch {
// Background warming; failures are non-fatal.
}
}
/**
* 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
* dev the default handler treats an entry as missing once `now > timestamp +
* expire * 1000`, so `expire: 0` against the original (past) timestamp makes
* the next read a miss. The value is never read once the entry is expired, 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 {
return {
...entry,
expire: 0,
value: new ReadableStream({
start(controller) {
controller.enqueue(new Uint8Array(1))
controller.close()
},
}),
}
}
...@@ -64,8 +64,15 @@ import { createDigestWithErrorCode } from '../../lib/error-telemetry-utils' ...@@ -64,8 +64,15 @@ import { createDigestWithErrorCode } from '../../lib/error-telemetry-utils'
import stringHash from 'next/dist/compiled/string-hash' import stringHash from 'next/dist/compiled/string-hash'
import { DYNAMIC_EXPIRE, DYNAMIC_STALE } from './constants' import { DYNAMIC_EXPIRE, DYNAMIC_STALE } from './constants'
import { NEXT_CACHE_ROOT_PARAM_TAG_ID } from '../../lib/constants' import { NEXT_CACHE_ROOT_PARAM_TAG_ID } from '../../lib/constants'
import type { CacheHandler } from '../lib/cache-handlers/types' import {
import { getCacheHandler, getPrivateCacheHandler } from './handlers' getCacheHandler,
getDevTieredCacheHandler,
getPrivateCacheHandler,
isCustomCacheHandler,
isMemoryCacheDisabled,
} from './handlers'
import type { CacheReadWriteHandler } from './tiered-cache-handler'
import { cloneCacheEntry } from './clone-cache-entry'
import { import {
NEXT_HMR_REFRESH_HASH_COOKIE, NEXT_HMR_REFRESH_HASH_COOKIE,
NEXT_INSTANT_TEST_COOKIE, NEXT_INSTANT_TEST_COOKIE,
...@@ -499,7 +506,7 @@ function saveSharedCacheEntryToResumeDataCache( ...@@ -499,7 +506,7 @@ function saveSharedCacheEntryToResumeDataCache(
} }
function saveToCacheHandler( function saveToCacheHandler(
cacheHandler: CacheHandler, cacheHandler: CacheReadWriteHandler,
workStore: WorkStore, workStore: WorkStore,
id: string, id: string,
cacheHandlerKeyBase: string, cacheHandlerKeyBase: string,
...@@ -1076,25 +1083,36 @@ async function collectResult( ...@@ -1076,25 +1083,36 @@ async function collectResult(
const collectedTags = innerCacheStore.tags const collectedTags = innerCacheStore.tags
// In development, private caches are forced to `revalidate: 0` and an
// `expire` of `DYNAMIC_EXPIRE` (5 minutes), the shortest expire not treated
// as dynamically shortened. The zero revalidate makes every read serve
// stale-while-revalidate (re-warming a fresh entry in the background) so warm
// reloads stay fast. The expire bounds how long an entry lingers in the dev
// in-memory cache.
const isPrivateCacheInDev = Boolean( const isPrivateCacheInDev = Boolean(
process.env.__NEXT_DEV_SERVER && cacheContext.kind === 'private' process.env.__NEXT_DEV_SERVER && cacheContext.kind === 'private'
) )
// In development, force a dynamic cache life (`revalidate: 0`, `expire:
// DYNAMIC_EXPIRE`) for caches that have no real backing: private caches, and
// any built-in (non-custom) kind when the in-memory cache is disabled
// (`cacheMaxMemorySize: 0`). The zero revalidate makes every read serve
// stale-while-revalidate (re-warming a fresh entry in the background) so warm
// reloads stay fast, and `DYNAMIC_EXPIRE` (5 minutes, the shortest expire not
// treated as dynamically shortened) bounds how long an entry lingers in the
// dev in-memory cache. Custom kinds keep their real cache life, since their
// backing handler owns it.
const forceDynamicCacheLifeInDev =
isPrivateCacheInDev ||
Boolean(
process.env.__NEXT_DEV_SERVER &&
isMemoryCacheDisabled() &&
!isCustomCacheHandler(cacheContext.kind)
)
// 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
// use that. Otherwise, we use the lowest of all inner fetch(), // use that. Otherwise, we use the lowest of all inner fetch(),
// unstable_cache() or nested "use cache", if they're lower than our default. // unstable_cache() or nested "use cache", if they're lower than our default.
const collectedRevalidate = isPrivateCacheInDev const collectedRevalidate = forceDynamicCacheLifeInDev
? 0 ? 0
: innerCacheStore.explicitRevalidate !== undefined : innerCacheStore.explicitRevalidate !== undefined
? innerCacheStore.explicitRevalidate ? innerCacheStore.explicitRevalidate
: innerCacheStore.revalidate : innerCacheStore.revalidate
const collectedExpire = isPrivateCacheInDev const collectedExpire = forceDynamicCacheLifeInDev
? DYNAMIC_EXPIRE ? DYNAMIC_EXPIRE
: innerCacheStore.explicitExpire !== undefined : innerCacheStore.explicitExpire !== undefined
? innerCacheStore.explicitExpire ? innerCacheStore.explicitExpire
...@@ -1514,20 +1532,6 @@ async function generateCacheEntryImpl( ...@@ -1514,20 +1532,6 @@ async function generateCacheEntryImpl(
} }
} }
function cloneCacheEntry(entry: CacheEntry): [CacheEntry, CacheEntry] {
const [streamA, streamB] = entry.value.tee()
entry.value = streamA
const clonedEntry: CacheEntry = {
value: streamB,
timestamp: entry.timestamp,
revalidate: entry.revalidate,
expire: entry.expire,
stale: entry.stale,
tags: entry.tags,
}
return [entry, clonedEntry]
}
function cloneCacheResult( function cloneCacheResult(
result: CollectedCacheResult result: CollectedCacheResult
): [CollectedCacheResult, CollectedCacheResult] { ): [CollectedCacheResult, CollectedCacheResult] {
...@@ -1635,7 +1639,7 @@ export async function cache( ...@@ -1635,7 +1639,7 @@ export async function cache(
// Probe re-executions (the dev-server's hang-detection worker) short-circuit // Probe re-executions (the dev-server's hang-detection worker) short-circuit
// further down before any handler is consulted, so we skip handler selection // further down before any handler is consulted, so we skip handler selection
// entirely and the worker can boot without registering handlers at all. // entirely and the worker can boot without registering handlers at all.
let cacheHandler: CacheHandler | undefined let cacheHandler: CacheReadWriteHandler | undefined
if (workStore.useCacheProbeMode === undefined) { if (workStore.useCacheProbeMode === undefined) {
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
...@@ -1645,10 +1649,31 @@ export async function cache( ...@@ -1645,10 +1649,31 @@ export async function cache(
cacheHandler = getPrivateCacheHandler() cacheHandler = getPrivateCacheHandler()
} }
} else { } else {
cacheHandler = getCacheHandler(kind) const handler = getCacheHandler(kind)
if (!cacheHandler) { if (!handler) {
throw new Error('Unknown cache handler: ' + kind) throw new Error('Unknown cache handler: ' + kind)
} }
// In development, a user-configured (custom) handler may be slow or
// 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.
// Built-in handlers (the default handler, and its size-0 replacement) are
// already in-memory and used directly.
if (process.env.__NEXT_DEV_SERVER && isCustomCacheHandler(kind)) {
// A custom kind always has a dev tiered handler: it is created in the
// same `setCacheHandler` call that makes `isCustomCacheHandler` true.
const tieredCacheHandler = getDevTieredCacheHandler(kind)
if (!tieredCacheHandler) {
throw new InvariantError(
`Expected a dev tiered cache handler for kind "${kind}".`
)
}
cacheHandler = tieredCacheHandler
} else {
cacheHandler = handler
}
} }
} }
......
...@@ -14,18 +14,25 @@ describe('cache-components-dev-streaming', () => { ...@@ -14,18 +14,25 @@ describe('cache-components-dev-streaming', () => {
}) })
// The loading boundary should be streamed immediately, without waiting for // The loading boundary should be streamed immediately, without waiting for
// the cache to be filled. // the cache to be filled. Read it at commit so we don't wait for "load"
expect(await browser.elementByCss('p').text()).toBe('Loading...') // (which only fires once the cache has filled).
expect(await browser.elementByCss('p', { waitUntil: false }).text()).toBe(
'Loading...'
)
// Eventually, the cache content should be streamed in. // Eventually, the cache content should be streamed in.
await retry(async () => { await retry(async () => {
expect(await browser.elementByCss('p').text()).toBeDateString() expect(
await browser.elementByCss('p', { waitUntil: false }).text()
).toBeDateString()
}) })
// Now that the cache is filled, it should be served immediately on the next // Now that the cache is filled, it should be served immediately with the
// page load. // shell on the next page load, without going through the loading boundary.
await browser.refresh() await browser.refresh({ waitUntil: 'commit' })
expect(await browser.elementByCss('p').text()).toBeDateString() expect(
await browser.elementByCss('p', { waitUntil: false }).text()
).toBeDateString()
}) })
it('streams a Suspense fallback above a private cache while filling it in the background', async () => { it('streams a Suspense fallback above a private cache while filling it in the background', async () => {
...@@ -36,10 +43,13 @@ describe('cache-components-dev-streaming', () => { ...@@ -36,10 +43,13 @@ describe('cache-components-dev-streaming', () => {
}) })
// The loading boundary should be streamed immediately, without waiting for // The loading boundary should be streamed immediately, without waiting for
// the private cache to be filled. // the private cache to be filled. Read it at commit (`waitUntil: false`) so
expect(await browser.elementByCss('#private-fallback').text()).toBe( // we don't wait for "load" (which only fires once the cache has filled).
'Loading...' expect(
) await browser
.elementByCss('#private-fallback', { waitUntil: false })
.text()
).toBe('Loading...')
// Eventually, the private cache content should be streamed in. // Eventually, the private cache content should be streamed in.
await retry(async () => { await retry(async () => {
......
import { Suspense } from 'react'
import { setTimeout } from 'timers/promises'
// A distinct slug per test, so each test exercises its own cache entry and no
// cache hits are shared across tests (the first request for a slug is a genuine
// cold miss). 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: 'cold-badge' }, { slug: 'purged' }]
}
async function getCachedValue(slug: string) {
'use cache'
// A slow generation, so the cold read is clearly pending at a staged-render
// boundary (which surfaces the cold cache indicator on the first load), and a
// warm reload served from the front is observably different. The slug keys
// the entry; the value itself is just a timestamp.
await setTimeout(1000)
return new Date().toISOString()
}
async function CachedValue({ slug }: { slug: string }) {
const value = await getCachedValue(slug)
return <p id="value">{value}</p>
}
export default async function Page({
params,
}: {
params: Promise<{ slug: string }>
}) {
const { slug } = await params
return (
<main>
<Suspense fallback={<p id="loading">Loading...</p>}>
<CachedValue slug={slug} />
</Suspense>
</main>
)
}
import { ReactNode } from 'react'
export default function Root({ children }: { children: ReactNode }) {
return (
<html>
<body>{children}</body>
</html>
)
}
// Clears the custom handler's backing store, simulating the remote cache being
// purged out-of-band. The dev-only in-memory front handler still holds its
// entries, so this exercises whether the tiered handler stops serving them.
export async function GET() {
const purge = (globalThis as Record<string, unknown>).__purgeUseCacheBacking
if (typeof purge === 'function') {
purge()
}
return Response.json({ purged: true })
}
// @ts-check
const { setTimeout } = require('timers/promises')
/**
* A persistent cache handler that simulates a remote cache: its `get` resolves
* on a macro task (after a delay) rather than in a microtask. Without a
* built-in in-memory front, a warm read would therefore still be pending at a
* staged render boundary in dev and be reported as a cold-cache miss. The
* tiered handler fronts this so warm reads resolve in a microtask instead.
*/
/** @type {Map<string, import('next/dist/server/lib/cache-handlers/types').CacheEntry>} */
const store = new Map()
// Let a route handler purge this backing store out-of-band, so a test can
// verify the tiered front handler stops serving its cached entry afterwards.
/** @type {any} */
const globalScope = globalThis
globalScope.__purgeUseCacheBacking = () => {
store.clear()
}
/** @type {Map<string, Promise<void>>} */
const pendingSets = new Map()
/**
* @type {import('next/dist/server/lib/cache-handlers/types').CacheHandler}
*/
const cacheHandler = {
async get(cacheKey) {
const pendingPromise = pendingSets.get(cacheKey)
if (pendingPromise) {
await pendingPromise
}
// Simulate the latency of fetching from a remote cache.
await setTimeout(200)
const entry = store.get(cacheKey)
if (!entry) {
return undefined
}
const [returnStream, savedStream] = entry.value.tee()
entry.value = savedStream
return { ...entry, value: returnStream }
},
async set(cacheKey, pendingEntry) {
/** @type {() => void} */
let resolvePending = () => {}
const pendingPromise = new Promise((resolve) => {
resolvePending = /** @type {() => void} */ (resolve)
})
pendingSets.set(cacheKey, pendingPromise)
try {
const entry = await pendingEntry
const [value, clonedValue] = entry.value.tee()
entry.value = value
// Consume the cloned stream so the entry is fully resolved before
// storing.
const reader = clonedValue.getReader()
while (!(await reader.read()).done) {}
store.set(cacheKey, entry)
} finally {
resolvePending()
pendingSets.delete(cacheKey)
}
},
async refreshTags() {},
async getExpiration() {
return 0
},
async updateTags() {},
}
module.exports = cacheHandler
/**
* @type {import('next').NextConfig}
*/
const nextConfig = {
cacheComponents: true,
// Route the default `"use cache"` kind through a custom handler that
// simulates a remote cache (its `get` has macro-task latency). In dev this is
// fronted by a built-in in-memory handler so warm reads still resolve in a
// microtask.
cacheHandlers: {
default: require.resolve('./handler.js'),
},
}
module.exports = nextConfig
import { nextTestSetup } from 'e2e-utils'
import { retry, waitFor } from 'next-test-utils'
describe('use-cache-custom-handler-dev', () => {
const { next, skipped } = nextTestSetup({
files: __dirname,
})
if (skipped) {
return
}
it('shows the Cold cache badge on a cold load but not on a warm reload through a slow custom handler', async () => {
const browser = await next.browser('/cold-badge')
// Cold load: the cache misses and fills while streaming, so the cold
// verdict is reported and (once the dev overlay's socket connects) the
// badge appears.
await browser.elementById('value')
await retry(async () => {
expect(await browser.hasElementByCss('[data-cold-cache-badge]')).toBe(
true
)
})
expect(
await browser
.elementByCss('[data-cold-cache-badge] [data-issues-open]')
.text()
).toBe('Cold cache')
// Warm reload: the built-in front serves the entry in a microtask, so the
// read isn't pending at a staged render boundary and no cold verdict is
// reported - even though the custom handler's own `get` is slow. Without
// the front, that slow `get` would make this a phantom cold miss. An
// absence can't be retried on, so wait out the replay window, then assert
// it never appeared.
await browser.refresh()
await browser.elementById('value')
await waitFor(500)
expect(await browser.hasElementByCss('[data-cold-cache-badge]')).toBe(false)
})
it('stops serving a front-cached entry after the backing cache is purged out-of-band', async () => {
const browser = await next.browser('/purged')
// 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.
const coldValue = await browser.elementById('value').text()
// Warm reload: served from the front. Its real cache life keeps it
// shell-eligible, so the same cached value shows immediately.
await browser.refresh()
expect(await browser.elementById('value').text()).toBe(coldValue)
// Purge the backing handler out-of-band. The front still holds the entry,
// so it would keep serving the stale value indefinitely if the tiered
// handler didn't evict it.
await next.fetch('/purge')
// The reconcile can only evict the front entry once it has observed the
// backing miss, which happens one read after the purge. So reloads converge
// on a freshly generated value instead of serving the purged front copy
// forever.
await retry(async () => {
await browser.refresh()
expect(await browser.elementById('value').text()).not.toBe(coldValue)
})
})
})
import { Suspense } from 'react'
import { setTimeout } from 'timers/promises'
// A distinct slug per test, so each test exercises its own cache entry and no
// cache hits are shared across tests (the first request for a slug is a genuine
// cold miss). 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: 'reload' }, { slug: 'cold-badge' }]
}
async function getCachedValue(slug: string) {
'use cache'
// A slow generation, so a warm reload that serves the stale entry is
// observably faster than a cold load that has to generate, and so a cold read
// is still pending at a staged-render boundary (which surfaces the cold cache
// indicator). The slug keys the entry; the value itself is just a timestamp.
await setTimeout(1000)
return new Date().toISOString()
}
async function CachedValue({ slug }: { slug: string }) {
const value = await getCachedValue(slug)
return <p id="value">{value}</p>
}
export default async function Page({
params,
}: {
params: Promise<{ slug: string }>
}) {
const { slug } = await params
return (
<main>
<Suspense fallback={<p id="loading">Loading...</p>}>
<CachedValue slug={slug} />
</Suspense>
</main>
)
}
import { ReactNode } from 'react'
export default function Root({ children }: { children: ReactNode }) {
return (
<html>
<body>{children}</body>
</html>
)
}
/**
* @type {import('next').NextConfig}
*/
const nextConfig = {
cacheComponents: true,
// Disable the in-memory cache to emulate a deploy environment without one. In
// development this should still cache (stale-while-revalidate) so reloads
// stay fast; in production it caches nothing.
cacheMaxMemorySize: 0,
}
module.exports = nextConfig
import { nextTestSetup } from 'e2e-utils'
import { retry, waitFor } from 'next-test-utils'
describe('use-cache-size-zero', () => {
const { next, skipped } = nextTestSetup({
files: __dirname,
})
if (skipped) {
return
}
it('serves the stale cached value on a warm reload, then converges to a fresh one', async () => {
const browser = await next.browser('/reload', {
waitHydration: false,
// Do not wait for "load"; inspect the page as it streams in.
waitUntil: 'commit',
})
// Cold load: the cache misses, so the loading boundary (the only `p` at
// this point) streams first, and the generated value streams in once the
// ~1s generation completes. Read at commit (`waitUntil: false`) so we don't
// wait for "load", which only fires once the value has streamed in.
expect(await browser.elementByCss('p', { waitUntil: false }).text()).toBe(
'Loading...'
)
await retry(async () => {
expect(
await browser.elementByCss('p', { waitUntil: false }).text()
).toBeDateString()
})
const coldValue = await browser
.elementByCss('p', { waitUntil: false })
.text()
// Warm reload: `cacheMaxMemorySize: 0` still caches in development, so the
// reload serves the same (stale) cached value instead of regenerating it.
// The forced `revalidate: 0` keeps the value a dynamic hole, so it still
// streams behind the loading boundary - but it's the cached value, served
// fast, not a fresh generation.
await browser.refresh({ waitUntil: 'commit' })
await retry(async () => {
expect(
await browser.elementByCss('p', { waitUntil: false }).text()
).toBeDateString()
})
expect(await browser.elementByCss('p', { waitUntil: false }).text()).toBe(
coldValue
)
// That warm reload regenerated 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('value').text()).not.toBe(coldValue)
})
})
it('shows the Cold cache badge on an initial cold load and not on a warm reload', async () => {
const browser = await next.browser('/cold-badge')
// Cold load: the cache misses and fills while streaming, so the cold
// verdict is reported and (once the dev overlay's socket connects) the
// badge appears.
await browser.elementById('value')
await retry(async () => {
expect(await browser.hasElementByCss('[data-cold-cache-badge]')).toBe(
true
)
})
expect(
await browser
.elementByCss('[data-cold-cache-badge] [data-issues-open]')
.text()
).toBe('Cold cache')
// Warm reload: the dev cache serves the entry without a miss, so no cold
// verdict is reported. An absence can't be retried on, so wait out the
// window in which a replayed push would arrive, then assert it never did.
await browser.refresh()
await browser.elementById('value')
await waitFor(500)
expect(await browser.hasElementByCss('[data-cold-cache-badge]')).toBe(false)
})
})
...@@ -2,7 +2,7 @@ import { nextTestSetup } from 'e2e-utils' ...@@ -2,7 +2,7 @@ import { nextTestSetup } from 'e2e-utils'
import { retry } from 'next-test-utils' import { retry } from 'next-test-utils'
describe('use-cache-swr', () => { describe('use-cache-swr', () => {
const { next, skipped } = nextTestSetup({ const { next, skipped, isNextDev } = nextTestSetup({
files: __dirname, files: __dirname,
skipDeployment: true, skipDeployment: true,
}) })
...@@ -51,11 +51,17 @@ describe('use-cache-swr', () => { ...@@ -51,11 +51,17 @@ describe('use-cache-swr', () => {
// The data should now be fresh (different from the stale data). // The data should now be fresh (different from the stale data).
expect(afterRegen).not.toBe(initialOuter) expect(afterRegen).not.toBe(initialOuter)
// Verify this was served from the pre-warmed cache (get hit, no set). // Verify this was served from the pre-warmed cache (get hit, no regen set).
// In production the backing `get` hit is logged synchronously during the
// request. In dev the warm read is served from the built-in front handler
// in a microtask and the backing `get` runs in the background reconcile, so
// we poll for it. Either way, no regeneration `set` should occur.
await retry(() => {
const cliOutput = next.cliOutput.slice(outputIndex) const cliOutput = next.cliOutput.slice(outputIndex)
expect(cliOutput).toMatch(/PersistentCacheHandler::get.*"outer".*-> hit/) expect(cliOutput).toMatch(/PersistentCacheHandler::get.*"outer".*-> hit/)
expect(cliOutput).not.toMatch(/PersistentCacheHandler::set.*"outer"/) expect(cliOutput).not.toMatch(/PersistentCacheHandler::set.*"outer"/)
}) })
})
it('should serve stale data without blocking on the background regeneration', async () => { it('should serve stale data without blocking on the background regeneration', async () => {
// Fetch 1: cold cache. The cached component blocks for ~1s. // Fetch 1: cold cache. The cached component blocks for ~1s.
...@@ -202,6 +208,15 @@ describe('use-cache-swr', () => { ...@@ -202,6 +208,15 @@ describe('use-cache-swr', () => {
// Ignore replayed logs that have a Cache badge. // Ignore replayed logs that have a Cache badge.
!line.includes(' Cache ') !line.includes(' Cache ')
) )
// In dev, warm reads resolve in a microtask via the built-in front handler,
// so the cross-request dedup window (the leader's read latency) is too
// small for concurrent requests to reliably join one leader. That is the
// intended dev-fast trade, and only costs a redundant regen in single-user
// dev. The strict dedup guarantee is a production concern, where the
// backing read holds the window open.
if (!isNextDev) {
expect(generationCalls).toHaveLength(1) expect(generationCalls).toHaveLength(1)
}
}) })
}) })
...@@ -383,10 +383,10 @@ export class Playwright<TCurrent = undefined> { ...@@ -383,10 +383,10 @@ export class Playwright<TCurrent = undefined> {
await page.goForward(options) await page.goForward(options)
}) })
} }
refresh() { refresh(opts?: { waitUntil?: PlaywrightNavigationWaitUntil }) {
// do not preserve the previous chained value, it's likely to be invalid after a reload. // do not preserve the previous chained value, it's likely to be invalid after a reload.
return this.startChain(async () => { return this.startChain(async () => {
await page.reload() await page.reload({ waitUntil: opts?.waitUntil ?? 'load' })
}) })
} }
/** /**
......
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