Unverified Commit ec0abf41 authored by Hendrik Liebau's avatar Hendrik Liebau Committed by GitHub

Fix missing content in Cached Navigations (#98767)

React can render outlined elements in later `setImmediate` callbacks
after an asynchronous cache read resolves. `cacheReady()` can resolve
before those elements start their cached reads. The embedded prerender
for Cached Navigations then reports unexpected cache misses and omits
cacheable content.

This change tracks pending native immediates in an `AsyncLocalStorage`
scope around each Cache Components render. `CacheSignal` waits for that
work before accepting a zero read count. If more native immediates
appear before the readiness timer runs, it waits and checks again.
Tracking does not make native immediates fast or change the existing
explicit, task-local fast-immediate behavior.

The e2e regression uses a delayed cache handler and a large outlined
tree. It verifies that Cached Navigations reuse outlined content while
content behind dynamic I/O remains uncached. Each test invocation uses a
fresh cache key through `searchParams`, so cases and retries cannot
reuse previously warmed entries.

Unit tests in the existing immediates suite cover scope isolation,
nested scheduling, cancellation, native scheduling semantics, and error
recovery.

Fixes #98543
parent b1c15da6
......@@ -6,6 +6,7 @@
*/
import { InvariantError } from '../../shared/lib/invariant-error'
import type { ImmediateTracker } from '../node-environment-extensions/fast-set-immediate.external'
export class CacheSignal {
private count = 0
......@@ -16,7 +17,7 @@ export class CacheSignal {
private subscribedSignals: Set<CacheSignal> | null = null
constructor() {
constructor(private readonly immediateTracker: ImmediateTracker | null) {
if (process.env.NEXT_RUNTIME === 'edge') {
// we rely on `process.nextTick`, which is not supported in edge
throw new InvariantError(
......@@ -41,19 +42,29 @@ export class CacheSignal {
)
}
// After a cache resolves, React will schedule new rendering work:
// - in a microtask (when prerendering)
// - in setImmediate (when rendering)
// To cover both of these, we have to make sure that we let immediates execute at least once after each cache resolved.
// We don't know when the pending timeout was scheduled (and if it's about to resolve),
// so by scheduling a new one, we can be sure that we'll go around the event loop at least once.
// Wait for rendering work that can start more cache reads. After a cache
// read finishes, React can schedule more Flight rendering:
// - The prerender API uses microtasks.
// - Streaming render APIs can use setImmediate callbacks.
//
// React can render outlined elements across multiple immediates. Those
// elements can start further cache reads.
//
// We give that work time to run before checking the count:
// - With a tracker, we wait for the render's pending native immediates.
// - Without one, an immediate gives native callbacks a chance to run.
//
// The timer checks the count after microtasks, nextTicks, and fast
// immediates finish. If the tracker sees new native immediates before the
// timer runs, we wait for those too and check again.
if (this.pendingTimeoutCleanup) {
// We cancel the timeout in beginRead, so this shouldn't ever be active here,
// but we still cancel it defensively.
// Multiple cacheReady() calls can get here without an intervening
// beginRead(). We cancel the earlier check before scheduling another one.
this.pendingTimeoutCleanup()
}
this.pendingTimeoutCleanup = scheduleImmediateAndTimeoutWithCleanup(
this.invokeListenersIfNoPendingReads
this.invokeListenersIfNoPendingReads,
this.immediateTracker
)
}
......@@ -178,16 +189,48 @@ export class CacheSignal {
}
}
function scheduleImmediateAndTimeoutWithCleanup(cb: () => void): () => void {
// If we decide to clean up the timeout, we want to remove
// either the immediate or the timeout, whichever is still pending.
let clearPending: () => void
function scheduleImmediateAndTimeoutWithCleanup(
callback: () => void,
immediateTracker: ImmediateTracker | null
): () => void {
let cancelled = false
let unsubscribe: (() => void) | null = null
let immediate: NodeJS.Immediate | null = null
let timeout: ReturnType<typeof setTimeout> | null = null
function scheduleTimeout() {
unsubscribe = null
if (!cancelled) {
timeout = setTimeout(() => {
timeout = null
// Repeat the wait only if the tracker reports pending native
// immediates. The initial immediate wait has already completed.
if (immediateTracker?.hasPendingImmediates()) {
unsubscribe = immediateTracker.onIdle(scheduleTimeout)
} else {
callback()
}
}, 0)
}
}
const immediate = setImmediate(() => {
const timeout = setTimeout(cb, 0)
clearPending = clearTimeout.bind(null, timeout)
})
clearPending = clearImmediate.bind(null, immediate)
// Always wait for an immediate before the first readiness timer, even if no
// native work is tracked yet. The render can start in a timer scheduled after
// this call.
if (immediateTracker === null) {
immediate = setImmediate(scheduleTimeout)
} else {
unsubscribe = immediateTracker.onIdle(scheduleTimeout)
}
return () => clearPending()
return () => {
cancelled = true
unsubscribe?.()
if (immediate !== null) {
clearImmediate(immediate)
}
if (timeout !== null) {
clearTimeout(timeout)
}
}
}
......@@ -7,7 +7,7 @@ import { CacheSignal } from '../cache-signal'
let _moduleLoadingSignal: CacheSignal | null
function getModuleLoadingSignal() {
if (!_moduleLoadingSignal) {
_moduleLoadingSignal = new CacheSignal()
_moduleLoadingSignal = new CacheSignal(null)
}
return _moduleLoadingSignal
}
......
import { promisify } from 'node:util'
import { InvariantError } from '../../shared/lib/invariant-error'
import { bindSnapshot } from '../app-render/async-local-storage'
import {
bindSnapshot,
getOrCreateGlobalAsyncLocalStorage,
} from '../app-render/async-local-storage'
type Execution = {
state: ExecutionState
......@@ -189,6 +192,120 @@ export function expectNoPendingImmediates() {
export { originalSetImmediate as unpatchedSetImmediate }
const immediateAsyncStorage =
getOrCreateGlobalAsyncLocalStorage<ImmediateTracker>(
'immediate-async-storage'
)
/**
* Run a callback and its async work with this native-immediate tracker.
*/
export function runWithNativeImmediateTracking<TArgs extends any[], TResult>(
tracker: ImmediateTracker,
callback: (...args: TArgs) => TResult,
...args: TArgs
): TResult {
return immediateAsyncStorage.run(tracker, callback, ...args)
}
/**
* Tracks native immediates for one render's async scope without changing their
* scheduling.
*
* A sentinel notifies idle subscribers after the last tracked immediate and its
* microtasks and nextTicks finish. New native immediates postpone notification.
*
* Subscribers can cancel their wait without stopping tracking. Tracking
* continues between subscriptions, including when asynchronous cache reads
* resume the render.
*/
export class ImmediateTracker {
private sentinel: NodeJS.Immediate | null = null
private needsAnotherCheck = false
private listeners = new Set<() => void>()
hasPendingImmediates(): boolean {
return this.sentinel !== null
}
/**
* Calls `callback` asynchronously in a native immediate, even when no
* immediates are pending. The callback runs in the subscriber's async
* context. The returned function cancels the subscription without stopping
* tracking.
*/
onIdle(callback: () => void): () => void {
const listeners = this.listeners
const listener = bindSnapshot(callback)
listeners.add(listener)
if (this.sentinel === null) {
this.scheduleIdleCheck()
} else {
this.sentinel.ref()
}
return () => {
listeners.delete(listener)
if (this.listeners.size === 0) {
this.sentinel?.unref()
}
}
}
scheduleIdleCheck(): void {
if (this.sentinel !== null) {
// New immediates are queued after the pending sentinel. Record that
// `checkForIdle` must check again before notifying subscribers. Further
// scheduling calls reuse this flag and the pending sentinel.
//
// Node's uncaught-exception recovery can also reach this branch:
//
// 1. We queue immediate `A`, then sentinel `S`: `[A, S]`.
// 2. `A` throws and interrupts Node's immediate-processing loop,
// leaving `S` first in Node's outstanding queue.
// 3. An uncaughtException handler handles the error, so Node continues.
// 4. Node calls `timers.setImmediate(noop)` for another immediate cycle.
// 5. Our patch runs before async-context cleanup and sees `A`'s tracker.
// 6. The tracker finds `S` still pending.
//
// Node schedules this no-op after any handled uncaught exception so
// pending ticks get another chance to run. After exception handling
// returns, Node's C++ dispatcher retries the outstanding queue in the
// same check phase, before the no-op runs.
//
// On Node 20, clearing `S` here leaves the outstanding queue's head
// pointing to a destroyed immediate. When Node retries the queue, it
// tries to skip the cleared entry through its predecessor. The first
// entry has no predecessor, so recovery throws another exception. Keep
// `S` queued and record that another check is needed instead.
this.needsAnotherCheck = true
return
}
this.sentinel = originalSetImmediate(this.checkForIdle)
if (this.listeners.size === 0) {
this.sentinel.unref()
}
}
private checkForIdle = () => {
this.sentinel = null
if (this.needsAnotherCheck) {
// Schedule the next check after the immediates queued since this
// sentinel. Their callbacks and microtasks/nextTicks can then run before
// we notify idle subscribers. A synchronous burst shares this next check.
this.needsAnotherCheck = false
this.scheduleIdleCheck()
return
}
const listeners = this.listeners
this.listeners = new Set()
for (const callback of listeners) {
listeners.delete(callback)
callback()
}
}
}
/**
* Wait until all nextTicks and microtasks spawned from the current task are done,
* then execute any immediates that they queued.
......@@ -595,11 +712,13 @@ function patchedSetImmediate<TArgs extends any[]>(
function patchedSetImmediate(callback: (args: void) => void): NodeJS.Immediate
function patchedSetImmediate(): NodeJS.Immediate {
if (currentExecution === null) {
return originalSetImmediate.apply(
const immediate = originalSetImmediate.apply(
null,
// @ts-expect-error: this is valid, but typescript doesn't get it
arguments
)
immediateAsyncStorage.getStore()?.scheduleIdleCheck()
return immediate
}
if (arguments.length === 0 || typeof arguments[0] !== 'function') {
......@@ -646,7 +765,9 @@ function patchedSetImmediatePromise<T = void>(
options?: import('node:timers').TimerOptions
): Promise<T> {
if (currentExecution === null) {
return originalSetImmediatePromisify(value, options)
const promise = originalSetImmediatePromisify(value, options)
immediateAsyncStorage.getStore()?.scheduleIdleCheck()
return promise
}
return new Promise<T>((resolve, reject) => {
......
......@@ -563,7 +563,7 @@ export class AppRouteRouteModule extends RouteModule<
*/
const prospectiveController = new AbortController()
let prospectiveRenderIsDynamic = false
const cacheSignal = new CacheSignal()
const cacheSignal = new CacheSignal(null)
let dynamicTracking = createDynamicTrackingState(undefined)
// TODO: Route handlers are never resumed, so it's counter-intuitive
......
import Link from 'next/link'
import { Suspense } from 'react'
type Props = {
searchParams: Promise<{ cacheKey?: string | string[] }>
}
async function ReturnLink({ searchParams }: Props) {
const { cacheKey } = await searchParams
if (typeof cacheKey !== 'string' || cacheKey.length === 0) {
throw new Error('A non-empty cacheKey search parameter is required')
}
return (
<Link href={{ pathname: '/', query: { cacheKey } }} prefetch={false}>
Return to cached content
</Link>
)
}
export default function Page({ searchParams }: Props) {
return (
<>
<h1>Hub</h1>
<Suspense fallback={null}>
<ReturnLink searchParams={searchParams} />
</Suspense>
</>
)
}
import type { ReactNode } from 'react'
export default function Root({ children }: { children: ReactNode }) {
return (
<html>
<body>{children}</body>
</html>
)
}
import { setTimeout } from 'node:timers/promises'
import { Suspense } from 'react'
import Link from 'next/link'
import { connection } from 'next/server'
type Props = {
searchParams: Promise<{ cacheKey?: string | string[] }>
}
async function cachedRead(name: string) {
'use cache'
return name
}
async function CachedChild({ cacheKey }: { cacheKey: string }) {
return <p id="content">{await cachedRead(`${cacheKey}:content`)}</p>
}
async function DynamicChild({ cacheKey }: { cacheKey: string }) {
await connection()
await setTimeout(100)
return <p id="dynamic-content">{await cachedRead(`${cacheKey}:dynamic`)}</p>
}
function LargeTree({ depth, cacheKey }: { depth: number; cacheKey: string }) {
if (depth === 0) {
return <CachedChild cacheKey={cacheKey} />
}
// Flight defers the child after this text exceeds its size threshold of 3200.
// The nesting tests whether cache warming waits for those descendant tasks.
return (
<section>
{'x'.repeat(3201)}
<LargeTree depth={depth - 1} cacheKey={cacheKey} />
</section>
)
}
async function Content({ searchParams }: Props) {
const { cacheKey } = await searchParams
if (typeof cacheKey !== 'string' || cacheKey.length === 0) {
throw new Error('A non-empty cacheKey search parameter is required')
}
const first = await cachedRead(`${cacheKey}:first`)
return (
<div>
<Link href={{ pathname: '/hub', query: { cacheKey } }} prefetch={false}>
Go to hub
</Link>
<p>{first}</p>
<LargeTree depth={3} cacheKey={cacheKey} />
<Suspense fallback={<p id="dynamic-fallback">Loading dynamic...</p>}>
<DynamicChild cacheKey={cacheKey} />
</Suspense>
</div>
)
}
export default function Page({ searchParams }: Props) {
return (
<Suspense fallback={<p>Loading...</p>}>
<Content searchParams={searchParams} />
</Suspense>
)
}
import { randomUUID } from 'node:crypto'
import { nextTestSetup } from 'e2e-utils'
import type { Page } from 'playwright'
import { createRouterAct } from 'router-act'
import { UNEXPECTED_CACHE_MISS_MESSAGE } from 'next/dist/server/use-cache/use-cache-errors'
// @force-gate prod
describe('cached-navigations-cache-warming', () => {
const { next } = nextTestSetup({
files: __dirname,
})
// This assertion needs next start and its local server logs.
// @force-gate start
it('does not report cache misses for children deferred by a large render', async () => {
const cacheKey = `server-render-${randomUUID()}`
const outputIndex = next.cliOutput.length
const $ = await next.render$(`/?cacheKey=${cacheKey}`)
expect($('#content').text()).toBe(`${cacheKey}:content`)
expect($('#dynamic-content').text()).toBe(`${cacheKey}:dynamic`)
expect(next.cliOutput.slice(outputIndex)).not.toContain(
UNEXPECTED_CACHE_MISS_MESSAGE
)
})
it('caches outlined elements but not content behind dynamic I/O', async () => {
const cacheKey = `client-navigation-${randomUUID()}`
let page: Page | undefined
const browser = await next.browser(`/?cacheKey=${cacheKey}`, {
beforePageLoad(browserPage: Page) {
page = browserPage
},
})
if (!page) {
throw new Error('The browser page was not initialized')
}
expect(await browser.elementByCss('#content:visible').text()).toBe(
`${cacheKey}:content`
)
expect(await browser.elementByCss('#dynamic-content:visible').text()).toBe(
`${cacheKey}:dynamic`
)
await browser.elementByCss(`a[href="/hub?cacheKey=${cacheKey}"]`).click()
expect(await browser.elementByCss('h1').text()).toBe('Hub')
await browser.elementByCss(`a[href="/?cacheKey=${cacheKey}"]`)
const act = createRouterAct(page)
await act(async () => {
await act(
() => browser.elementByCss(`a[href="/?cacheKey=${cacheKey}"]`).click(),
{
includes: 'dynamic-content',
block: true,
}
)
expect(await browser.hasElementByCss('#content:visible')).toBe(true)
expect(await browser.elementByCss('#content:visible').text()).toBe(
`${cacheKey}:content`
)
expect(
await browser.elementByCss('#dynamic-fallback:visible').text()
).toBe('Loading dynamic...')
expect(await browser.hasElementByCss('#dynamic-content:visible')).toBe(
false
)
})
expect(await browser.elementByCss('#dynamic-content:visible').text()).toBe(
`${cacheKey}:dynamic`
)
})
})
// @ts-check
const { setTimeout } = require('node:timers/promises')
const defaultCacheHandler =
require('next/dist/server/lib/cache-handlers/default.external').default
/**
* @type {import('next/cache').CacheHandler}
*/
const cacheHandler = {
...defaultCacheHandler,
async get(cacheKey, softTags) {
// Simulate a network-backed cache.
await setTimeout(10)
return defaultCacheHandler.get(cacheKey, softTags)
},
}
module.exports = cacheHandler
import type { NextConfig } from 'next'
const nextConfig: NextConfig = {
cacheComponents: true,
partialPrefetching: true,
cacheHandlers: {
default: require.resolve('./handler.js'),
},
}
export default nextConfig
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