Unverified Commit 13809269 authored by Andrew Clark's avatar Andrew Clark Committed by GitHub

[Segment Bundling] [Scaffolding] Ensure inlining hint correctness (#91320)

Inlining hints (which segments to bundle together) are computed once at
build time by measuring gzip sizes, then persisted to
`prefetch-hints.json`. There are several scenarios where these hints may
not be available at render time. This commit addresses each scenario to
ensure the client always receives correct hints and never enters a bad
state.

### Build-time static pages (stale hints)

The initial RSC payload baked into the HTML is generated before hints
are computed, since hint computation requires at least one completed
render to measure sizes. The server marks these trees with
`InliningHintsStale`. The client immediately expires the route cache
entry so that the next prefetch re-fetches the correct tree from the
`/_tree` response. The segment data doesn't need re-fetching since it
was already cached from the initial HTML payload.

### ISR / revalidation

Hints are always available from the manifest. A missing entry is an
internal error — it means the build pipeline failed to produce hints for
a route that needs them.

### Fully dynamic routes at runtime

No hints exist and none will ever be computed. Every segment gets
`PrefetchDisabled`, which tells the client not to attempt prefetching.
This avoids an infinite re-fetch loop that would occur if the client
kept trying to fetch "correct" hints.

### Unified response format

Also simplifies the segment prefetch response format: every response is
now a `SegmentPrefetchResponse` with a top-level `buildId` and a `data`
array, treating a single-segment response as a bundle that happens to
have length one. This unifies the format so that bundled multi-segment
responses (added in a follow-up) require no additional client parsing
logic.
parent cbb5879f
......@@ -1140,5 +1140,9 @@
"1139": "`unstable_catchError` can only be used in Client Components.",
"1140": "Route %s used \\`import('next/root-params').%s()\\` inside \\`\"use cache\"\\` nested within \\`unstable_cache\\`. Root params are not available in this context.",
"1141": "Route %s used \\`import('next/root-params').%s()\\` inside \\`unstable_cache\\`. This is not supported. Use \\`\"use cache\"\\` instead.",
"1142": "Route %s used \\`import('next/root-params').%s()\\` inside \\`generateStaticParams\\`, but the \\`%s\\` parameter was not provided by a parent \\`generateStaticParams\\`. In \\`generateStaticParams\\`, root params are only available for segments nested below the segment that provides them."
"1142": "Route %s used \\`import('next/root-params').%s()\\` inside \\`generateStaticParams\\`, but the \\`%s\\` parameter was not provided by a parent \\`generateStaticParams\\`. In \\`generateStaticParams\\`, root params are only available for segments nested below the segment that provides them.",
"1143": "Prefetch inlining is enabled but no hint tree was provided during incremental static revalidation. The prefetch-hints.json manifest should contain an entry for this route.",
"1144": "Prefetch inlining is enabled but no hints were found for route \"%s\". This is a bug in the Next.js build pipeline — prefetch-hints.json should contain an entry for every route that produces segment data.",
"1145": "Internal Next.js Error: Prefetch inlining is enabled but no hints were found for route \"%s\". prefetch-hints.json should contain an entry for every route that produces segment data. This is a bug in Next.js.",
"1146": "Internal Next.js Error: Prefetch inlining is enabled but no hint tree was provided during incremental static revalidation. The prefetch-hints.json manifest should contain an entry for this route. This is a bug in Next.js."
}
......@@ -75,12 +75,12 @@ export function createInitialRouterState({
// head is embedded into the CacheNode tree, but eventually we'll lift it out
// and store it on the top-level state object.
//
// TODO: For statically-generated-at-build-time HTML pages, the
// FlightRouterState baked into the initial RSC payload won't have the
// correct segment inlining hints (ParentInlinedIntoSelf, InlinedIntoChild)
// because those are computed after the pre-render. The client will need to
// fetch the correct hints from the route tree prefetch (/_tree) response
// before acting on inlining decisions.
// For statically-generated-at-build-time HTML pages, the FlightRouterState
// baked into the initial RSC payload won't have the correct segment inlining
// hints because those are computed after the pre-render. The server marks
// these trees with InliningHintsStale, which causes the route cache entry
// to be immediately expired. The next prefetch will re-fetch the tree with
// correct hints from the /_tree response.
const acc = { metadataVaryPath: null }
const initialRouteTree = convertRootFlightRouterStateToRouteTree(
initialTree,
......
import type {
TreePrefetch,
RootTreePrefetch,
SegmentPrefetch,
SegmentPrefetchResponse,
InlinedPrefetchResponse,
InlinedSegmentPrefetch,
} from '../../../server/app-render/collect-segment-data'
......@@ -10,6 +10,7 @@ import type {
FlightData,
Segment as FlightRouterStateSegment,
} from '../../../shared/lib/app-router-types'
import { PrefetchHint } from '../../../shared/lib/app-router-types'
import {
readVaryParams,
type VaryParams,
......@@ -452,7 +453,7 @@ export function readRouteCacheEntry(
// No cache hit. Attempt to construct from template using the new
// optimistic routing mechanism (pattern-based matching).
if (process.env.__NEXT_OPTIMISTIC_ROUTING) {
return matchKnownRoute(key.pathname, key.search)
return matchKnownRoute(now, key.pathname, key.search)
}
return null
......@@ -1070,7 +1071,17 @@ export function fulfillRouteCacheEntry(
// Always use the static stale time.
// NOTE: An exception is rewrites/redirects in middleware or proxy, which can
// change routes dynamically. We have other strategies for handling those.
fulfilledEntry.staleAt = now + STATIC_STALETIME_MS
//
// If the route tree has stale inlining hints (e.g. the initial RSC payload
// for a build-time static page, generated before collectPrefetchHints ran),
// immediately expire the entry so it gets re-fetched with correct hints.
// The segment data itself is still valid — only the route tree (which
// contains the hint bits) needs to be re-fetched.
if (tree.prefetchHints & PrefetchHint.InliningHintsStale) {
fulfilledEntry.staleAt = -1
} else {
fulfilledEntry.staleAt = now + STATIC_STALETIME_MS
}
fulfilledEntry.couldBeIntercepted = couldBeIntercepted
fulfilledEntry.canonicalUrl = canonicalUrl
fulfilledEntry.renderedSearch = renderedSearch
......@@ -1924,42 +1935,57 @@ export async function fetchSegmentOnCacheMiss(
await createNonTaskyPrefetchResponseStream(response.body)
closed.resolve()
setSizeInCacheMap(segmentCacheEntry, responseSize)
const serverData = await createFromNextReadableStream<SegmentPrefetch>(
prefetchStream,
headers,
{ allowPartialStream: true }
)
const serverResponse =
await createFromNextReadableStream<SegmentPrefetchResponse>(
prefetchStream,
headers,
{ allowPartialStream: true }
)
if (
(response.headers.get(NEXT_NAV_DEPLOYMENT_ID_HEADER) ??
serverData.buildId) !== getNavigationBuildId()
serverResponse.buildId) !== getNavigationBuildId()
) {
// The server build does not match the client. Treat as a 404. During
// an actual navigation, the router will trigger an MPA navigation.
rejectSegmentCacheEntry(segmentCacheEntry, Date.now() + 10 * 1000)
return null
}
const now = Date.now()
const staleAt = now + getStaleTimeMs(serverData.staleTime)
const fulfilledEntry = fulfillSegmentCacheEntry(
segmentCacheEntry,
serverData.rsc,
staleAt,
serverData.isPartial
)
// Iterate over the segment data in the response array. Currently each
// per-segment response contains a single entry, but the format supports
// bundled responses with multiple entries (used when segment inlining
// is enabled).
let fulfilledEntry: FulfilledSegmentCacheEntry | null = null
for (const serverData of serverResponse.data) {
if (serverData === null) {
// Null entries represent segments with static prefetch disabled
// (runtime prefetch or unstable_instant = false). Skip them.
continue
}
const now = Date.now()
const staleAt = now + getStaleTimeMs(serverData.staleTime)
fulfilledEntry = fulfillSegmentCacheEntry(
segmentCacheEntry,
serverData.rsc,
staleAt,
serverData.isPartial
)
// If the server tells us which params the segment varies by, we can re-key
// the entry to a more generic vary path. This allows the entry to be reused
// across different param values for params that the segment doesn't
// actually depend on.
const varyParams = serverData.varyParams
const fulfilledVaryPath =
process.env.__NEXT_VARY_PARAMS && varyParams !== null
? getFulfilledSegmentVaryPath(tree.varyPath, varyParams)
: getSegmentVaryPathForRequest(segmentCacheEntry.fetchStrategy, tree)
// Re-key and upsert the entry at the fulfilled vary path. This ensures
// the entry is stored at the most generic path possible based on which
// params the segment actually depends on.
upsertSegmentEntry(now, fulfilledVaryPath, fulfilledEntry)
// If the server tells us which params the segment varies by, we can
// re-key the entry to a more generic vary path. This allows the entry
// to be reused across different param values for params that the
// segment doesn't actually depend on.
const varyParams = serverData.varyParams
const fulfilledVaryPath =
process.env.__NEXT_VARY_PARAMS && varyParams !== null
? getFulfilledSegmentVaryPath(tree.varyPath, varyParams)
: getSegmentVaryPathForRequest(segmentCacheEntry.fetchStrategy, tree)
upsertSegmentEntry(now, fulfilledVaryPath, fulfilledEntry)
}
if (fulfilledEntry === null) {
rejectSegmentCacheEntry(segmentCacheEntry, Date.now() + 10 * 1000)
return null
}
return {
value: fulfilledEntry,
......@@ -2037,7 +2063,7 @@ export async function fetchInlinedSegmentsOnCacheMiss(
if (
(response.headers.get(NEXT_NAV_DEPLOYMENT_ID_HEADER) ??
serverData.tree.segment.buildId) !== getNavigationBuildId()
serverData.buildId) !== getNavigationBuildId()
) {
rejectSegmentEntriesIfStillPending(spawnedEntries, Date.now() + 10 * 1000)
return null
......
......@@ -49,9 +49,11 @@ import {
EntryStatus,
writeRouteIntoCache,
fulfillRouteCacheEntry,
getCurrentRouteCacheVersion,
type PendingRouteCacheEntry,
createMetadataRouteTree,
} from './cache'
import { isValueExpired } from './cache-map'
import { doesStaticSegmentAppearInURL } from '../../route-params'
import type { NormalizedPathname, NormalizedSearch } from './cache-key'
import {
......@@ -137,6 +139,30 @@ type KnownRoutePart =
*/
type ResolvedParams = Map<string, string | string[]>
/**
* Read the pattern from a KnownRoutePart, evicting it if expired.
*
* This prevents stale patterns (e.g. from InliningHintsStale route entries
* with staleAt = -1) from being cloned into synthetic entries indefinitely.
* Once evicted, the pattern slot can be repopulated by the next
* discoverKnownRoute call with a fresh entry from a /_tree response.
*/
function readPattern(
now: number,
part: KnownRoutePart
): FulfilledRouteCacheEntry | null {
const pattern = part.pattern
if (pattern === null) {
return null
}
if (isValueExpired(now, getCurrentRouteCacheVersion(), pattern)) {
// The pattern is expired. Null it out so the slot can be repopulated.
part.pattern = null
return null
}
return pattern
}
function createEmptyPart(): KnownRoutePart {
return {
staticChildren: null,
......@@ -442,12 +468,13 @@ function discoverKnownRoutePart(
// Reached a page node. Create/get the route cache entry and store as a
// pattern. First, check if there's already a pattern for this route.
if (knownRoutePart.pattern !== null) {
const existingPattern = readPattern(now, knownRoutePart)
if (existingPattern !== null) {
// If this route has a dynamic rewrite, mark the existing pattern.
if (hasDynamicRewrite) {
knownRoutePart.pattern.hasDynamicRewrite = true
existingPattern.hasDynamicRewrite = true
}
return knownRoutePart.pattern
return existingPattern
}
// Get or create the entry
......@@ -486,12 +513,14 @@ function discoverKnownRoutePart(
* pattern, or null if no match is found (fall back to server resolution).
*/
export function matchKnownRoute(
now: number,
pathname: string,
search: NormalizedSearch
): FulfilledRouteCacheEntry | null {
const pathnameParts = pathname.split('/').filter((p) => p !== '')
const resolvedParams: ResolvedParams = new Map()
const match = matchKnownRoutePart(
now,
knownRouteTreeRoot,
pathnameParts,
0,
......@@ -593,6 +622,7 @@ type KnownRouteMatch = {
* Returns null if no match found (caller should fall back to server).
*/
function matchKnownRoutePart(
now: number,
part: KnownRoutePart,
pathnameParts: string[],
partIndex: number,
......@@ -610,7 +640,7 @@ function matchKnownRoutePart(
if (part.staticChildren === null) {
// The only safe match is a direct pattern when no URL parts remain.
if (urlPart === null) {
const pattern = part.pattern
const pattern = readPattern(now, part)
if (pattern !== null && !pattern.hasDynamicRewrite) {
return { part, pattern }
}
......@@ -636,6 +666,7 @@ function matchKnownRoutePart(
return null
}
const match = matchKnownRoutePart(
now,
staticChild,
pathnameParts,
partIndex + 1,
......@@ -658,7 +689,7 @@ function matchKnownRoutePart(
const dynamicPart = part.dynamicChild
const paramName = part.dynamicChildParamName
const paramType = part.dynamicChildParamType
const dynamicPattern = dynamicPart.pattern
const dynamicPattern = readPattern(now, dynamicPart)
switch (paramType) {
case 'c':
......@@ -672,7 +703,7 @@ function matchKnownRoutePart(
return { part: dynamicPart, pattern: dynamicPattern }
}
break
case 'oc':
case 'oc': {
// Optional catch-all [[...param]]: consumes 0+ URL parts
if (dynamicPattern !== null && !dynamicPattern.hasDynamicRewrite) {
if (urlPart !== null) {
......@@ -681,12 +712,14 @@ function matchKnownRoutePart(
}
// urlPart is null - can match with zero parts, but a direct pattern
// (e.g., page.tsx alongside [[...param]]) takes precedence.
if (part.pattern === null || part.pattern.hasDynamicRewrite) {
const directPattern = readPattern(now, part)
if (directPattern === null || directPattern.hasDynamicRewrite) {
resolvedParams.set(paramName, [])
return { part: dynamicPart, pattern: dynamicPattern }
}
}
break
}
case 'd':
// Regular dynamic [param]: consumes exactly 1 URL part.
// Unlike catch-all which terminates here, regular dynamic must
......@@ -694,6 +727,7 @@ function matchKnownRoutePart(
if (urlPart !== null) {
resolvedParams.set(paramName, urlPart)
return matchKnownRoutePart(
now,
dynamicPart,
pathnameParts,
partIndex + 1,
......@@ -721,7 +755,7 @@ function matchKnownRoutePart(
// No children matched. If we've consumed all URL parts, check for a direct
// pattern at this node (the route terminates here).
if (urlPart === null) {
const pattern = part.pattern
const pattern = readPattern(now, part)
if (pattern !== null && !pattern.hasDynamicRewrite) {
return { part, pattern }
}
......
......@@ -13,6 +13,7 @@ import type {
FlightDataPath,
PrefetchHints,
} from '../../shared/lib/app-router-types'
import { PrefetchHint } from '../../shared/lib/app-router-types'
import type { Readable } from 'node:stream'
import {
workAsyncStorage,
......@@ -1733,9 +1734,15 @@ async function getRSCPayload(
} = ctx
const hints = ctx.renderOpts.prefetchHints?.[ctx.pagePath] ?? null
const prefetchInliningEnabled = Boolean(
ctx.renderOpts.experimental.prefetchInlining
)
const initialTree = await createFlightRouterStateFromLoaderTree(
tree,
hints,
prefetchInliningEnabled,
workStore.isStaticGeneration,
ctx.renderOpts.isBuildTimePrerendering ?? false,
getDynamicParamFromSegment,
query
)
......@@ -1924,9 +1931,15 @@ async function getErrorRSCPayload(
)
const errorHints = ctx.renderOpts.prefetchHints?.[ctx.pagePath] ?? null
const errorPrefetchInliningEnabled = Boolean(
ctx.renderOpts.experimental.prefetchInlining
)
const initialTree = await createFlightRouterStateFromLoaderTree(
tree,
errorHints,
errorPrefetchInliningEnabled,
workStore.isStaticGeneration,
ctx.renderOpts.isBuildTimePrerendering ?? false,
getDynamicParamFromSegment,
query
)
......@@ -7244,7 +7257,27 @@ async function collectSegmentData(
} else {
// Runtime: use hints from the manifest. Never compute fresh hints
// during ISR/revalidation.
hints = renderOpts.prefetchHints?.[pagePath] ?? null
const manifestHints = renderOpts.prefetchHints?.[pagePath]
if (manifestHints === undefined) {
// TODO(#91407): No hints found for this route. This currently
// happens for routes with `instant = false` at the root segment,
// which causes the prerender to run per-request and the hints
// manifest to be unavailable at runtime.
//
// Fall back to a hint tree that marks everything as unprefetchable.
// The root gets PrefetchDisabled, and children inherit null hints
// which triggers PrefetchDisabled in createFlightRouterStateFromLoaderTree.
//
// Once the instant:false bug is fixed, this should become an error —
// the manifest should always have an entry for every route that
// reaches collectSegmentData.
hints = {
hints: PrefetchHint.PrefetchDisabled,
slots: null,
}
} else {
hints = manifestHints
}
}
// Pass the resolved hints so collectSegmentData can union them into
......
......@@ -73,8 +73,16 @@ export type TreePrefetch = {
prefetchHints: number
}
/**
* Top-level response for a segment prefetch request. Contains the build ID
* and an array of segment data (one per segment in the bundle).
*/
export type SegmentPrefetchResponse = {
buildId: string
data: Array<SegmentPrefetch | null>
}
export type SegmentPrefetch = {
buildId?: string
rsc: React.ReactNode | null
isPartial: boolean
staleTime: number
......@@ -110,6 +118,7 @@ export type InlinedSegmentPrefetch = {
* data for a route bundled into a single tree structure, plus the head segment.
*/
export type InlinedPrefetchResponse = {
buildId: string
tree: InlinedSegmentPrefetch
head: SegmentPrefetch
}
......@@ -501,12 +510,19 @@ async function collectPrefetchHintsImpl(
? acceptingChildInlinedBytes
: smallestChildInlinedBytes
// At leaf nodes (pages), try to inline the head (metadata/viewport) into
// this page's response. The head is treated like an additional inlined
// Try to inline the head (metadata/viewport) into this segment's
// response. The head can only be inlined into a page, not a layout,
// because pages may access additional params (e.g. searchParams) that
// layouts cannot. The head is treated like an additional inlined
// entry — it counts against the same total budget. Only the first page
// that has room gets the head; subsequent pages skip via the shared
// headInlineState accumulator.
if (!hasChildren && !headInlineState.inlined) {
const segment = route[0]
const isPageSegment =
typeof segment === 'string'
? segment === PAGE_SEGMENT_KEY
: segment[0] === PAGE_SEGMENT_KEY
if (isPageSegment && !headInlineState.inlined) {
if (inlinedBytes + headGzipSize < maxBundleSize) {
hints |= PrefetchHint.HeadInlinedIntoSelf
inlinedBytes += headGzipSize
......@@ -733,8 +749,14 @@ function collectSegmentDataImpl(
// inlining hints (ParentInlinedIntoSelf, InlinedIntoChild) won't be in
// route[4] yet. On subsequent renders the hints are already in the
// FlightRouterState, so the union is idempotent.
//
// Strip InliningHintsStale — it's a transient flag set on the initial
// build-time FlightRouterState and must never appear in /_tree responses.
// If it leaked through, the client would re-fetch the tree in an infinite
// loop.
const prefetchHints =
(route[4] ?? 0) | (hintTree !== null ? hintTree.hints : 0)
((route[4] ?? 0) & ~PrefetchHint.InliningHintsStale) |
(hintTree !== null ? hintTree.hints : 0)
// Determine which params this segment varies on.
// Read the vary params thenable directly from the seed data. By the time
......@@ -816,23 +838,22 @@ async function renderSegmentPrefetch(
staleTime,
varyParams,
}
if (buildId) {
segmentPrefetch.buildId = buildId
// Wrap in a SegmentPrefetchResponse with a top-level buildId.
// For non-bundled responses, the data array has a single element.
const response: SegmentPrefetchResponse = {
buildId: buildId ?? '',
data: [segmentPrefetch],
}
// Since all we're doing is decoding and re-encoding a cached prerender, if
// it takes longer than a microtask, it must because of hanging promises
// caused by dynamic data. Abort the stream at the end of the current task.
const abortController = new AbortController()
waitAtLeastOneReactRenderTask().then(() => abortController.abort())
const { prelude: segmentStream } = await prerender(
segmentPrefetch,
clientModules,
{
filterStackFrame,
signal: abortController.signal,
onError: onSegmentPrerenderError,
}
)
const { prelude: segmentStream } = await prerender(response, clientModules, {
filterStackFrame,
signal: abortController.signal,
onError: onSegmentPrerenderError,
})
const segmentBuffer = await streamToBuffer(segmentStream)
if (requestKey === ROOT_SEGMENT_REQUEST_KEY) {
return ['/_index' as SegmentRequestKey, segmentBuffer]
......@@ -866,11 +887,9 @@ async function renderInlinedPrefetchResponse(
staleTime,
varyParams: headVaryParams,
}
if (buildId) {
headPrefetch.buildId = buildId
}
const response: InlinedPrefetchResponse = {
buildId: buildId ?? '',
tree: inlinedTree,
head: headPrefetch,
}
......@@ -928,9 +947,6 @@ async function buildInlinedSegmentPrefetch(
staleTime,
varyParams,
}
if (buildId) {
segment.buildId = buildId
}
return { segment, slots }
}
......
......@@ -11,6 +11,9 @@ import type { AppSegmentConfig } from '../../build/segment-config/app/app-segmen
async function createFlightRouterStateFromLoaderTreeImpl(
loaderTree: LoaderTree,
hintTree: PrefetchHints | null,
prefetchInliningEnabled: boolean,
isStaticGeneration: boolean,
isBuildTimePrerendering: boolean,
getDynamicParamFromSegment: GetDynamicParamFromSegment,
searchParams: any,
didFindRootLayout: boolean
......@@ -43,6 +46,32 @@ async function createFlightRouterStateFromLoaderTreeImpl(
// precomputed bitmask rather than re-derive hints on every render.
if (hintTree !== null) {
prefetchHints |= hintTree.hints
} else if (prefetchInliningEnabled) {
if (isBuildTimePrerendering) {
// Prefetch inlining is enabled but no hint tree was provided during a
// build-time prerender. This happens for the initial RSC payload
// generated before collectPrefetchHints has run. Mark so the client
// can expire the route cache entry and re-fetch the tree with correct
// hints.
prefetchHints |= PrefetchHint.InliningHintsStale
} else if (isStaticGeneration) {
// TODO(#91407): Temporary mitigation: when hints are missing during
// runtime static generation, fall back to treating every segment as
// unprefetchable. This currently happens for routes with
// `instant = false` at the root segment, which causes the prerender
// to run per-request instead of being cached, and the prefetch hints
// manifest is not available.
//
// Once that bug is fixed, this branch should become an error again —
// hints should always be available from the manifest during ISR.
prefetchHints |= PrefetchHint.PrefetchDisabled
} else {
// At runtime with no hint tree, this is a fully dynamic route with no
// manifest entry. Treat every segment as unprefetchable. Do NOT set
// InliningHintsStale — that would cause the client to enter an
// infinite re-fetch loop trying to get hints that will never exist.
prefetchHints |= PrefetchHint.PrefetchDisabled
}
}
// Mark the first segment that has a layout as the "root" layout
......@@ -51,7 +80,9 @@ async function createFlightRouterStateFromLoaderTreeImpl(
prefetchHints |= PrefetchHint.IsRootLayout
}
if (instantConfig && typeof instantConfig === 'object') {
if (instantConfig === false) {
prefetchHints |= PrefetchHint.PrefetchDisabled
} else if (instantConfig && typeof instantConfig === 'object') {
prefetchHints |= PrefetchHint.SubtreeHasInstant
if (instantConfig.prefetch === 'runtime') {
prefetchHints |= PrefetchHint.HasRuntimePrefetch
......@@ -72,6 +103,9 @@ async function createFlightRouterStateFromLoaderTreeImpl(
const child = await createFlightRouterStateFromLoaderTreeImpl(
parallelRoutes[parallelRouteKey],
childHintNode,
prefetchInliningEnabled,
isStaticGeneration,
isBuildTimePrerendering,
getDynamicParamFromSegment,
searchParams,
didFindRootLayout
......@@ -81,7 +115,8 @@ async function createFlightRouterStateFromLoaderTreeImpl(
prefetchHints |=
child[4] &
(PrefetchHint.SubtreeHasInstant |
PrefetchHint.SubtreeHasLoadingBoundary)
PrefetchHint.SubtreeHasLoadingBoundary |
PrefetchHint.SubtreeHasRuntimePrefetch)
// If a child has a loading boundary (either directly or in its subtree),
// propagate that as SubtreeHasLoadingBoundary to this segment.
if (
......@@ -91,6 +126,15 @@ async function createFlightRouterStateFromLoaderTreeImpl(
) {
prefetchHints |= PrefetchHint.SubtreeHasLoadingBoundary
}
// If a child has runtime prefetch (either directly or in its subtree),
// propagate that as SubtreeHasRuntimePrefetch to this segment.
if (
child[4] &
(PrefetchHint.HasRuntimePrefetch |
PrefetchHint.SubtreeHasRuntimePrefetch)
) {
prefetchHints |= PrefetchHint.SubtreeHasRuntimePrefetch
}
}
children[parallelRouteKey] = child
}
......@@ -106,6 +150,9 @@ async function createFlightRouterStateFromLoaderTreeImpl(
export async function createFlightRouterStateFromLoaderTree(
loaderTree: LoaderTree,
hintTree: PrefetchHints | null,
prefetchInliningEnabled: boolean,
isStaticGeneration: boolean,
isBuildTimePrerendering: boolean,
getDynamicParamFromSegment: GetDynamicParamFromSegment,
searchParams: any
): Promise<FlightRouterState> {
......@@ -113,6 +160,9 @@ export async function createFlightRouterStateFromLoaderTree(
return createFlightRouterStateFromLoaderTreeImpl(
loaderTree,
hintTree,
prefetchInliningEnabled,
isStaticGeneration,
isBuildTimePrerendering,
getDynamicParamFromSegment,
searchParams,
didFindRootLayout
......@@ -122,6 +172,9 @@ export async function createFlightRouterStateFromLoaderTree(
export async function createRouteTreePrefetch(
loaderTree: LoaderTree,
hintTree: PrefetchHints | null,
prefetchInliningEnabled: boolean,
isStaticGeneration: boolean,
isBuildTimePrerendering: boolean,
getDynamicParamFromSegment: GetDynamicParamFromSegment
): Promise<FlightRouterState> {
// Search params should not be added to page segment's cache key during a
......@@ -132,6 +185,9 @@ export async function createRouteTreePrefetch(
return createFlightRouterStateFromLoaderTreeImpl(
loaderTree,
hintTree,
prefetchInliningEnabled,
isStaticGeneration,
isBuildTimePrerendering,
getDynamicParamFromSegment,
searchParams,
didFindRootLayout
......
......@@ -60,7 +60,12 @@ export async function walkTreeWithFlightRouterState({
isPrefetch,
getDynamicParamFromSegment,
parsedRequestHeaders,
workStore,
} = ctx
const prefetchInliningEnabled = Boolean(experimental.prefetchInlining)
const isStaticGeneration = workStore.isStaticGeneration
const isBuildTimePrerendering =
ctx.renderOpts.isBuildTimePrerendering ?? false
const [segment, parallelRoutes, modules] = loaderTreeToFilter
......@@ -155,11 +160,17 @@ export async function walkTreeWithFlightRouterState({
await createRouteTreePrefetch(
loaderTreeToFilter,
hintTree,
prefetchInliningEnabled,
isStaticGeneration,
isBuildTimePrerendering,
getDynamicParamFromSegment
)
: await createFlightRouterStateFromLoaderTree(
loaderTreeToFilter,
hintTree,
prefetchInliningEnabled,
isStaticGeneration,
isBuildTimePrerendering,
getDynamicParamFromSegment,
query
)
......@@ -187,11 +198,17 @@ export async function walkTreeWithFlightRouterState({
? await createRouteTreePrefetch(
loaderTreeToFilter,
hintTree,
prefetchInliningEnabled,
isStaticGeneration,
isBuildTimePrerendering,
getDynamicParamFromSegment
)
: await createFlightRouterStateFromLoaderTree(
loaderTreeToFilter,
hintTree,
prefetchInliningEnabled,
isStaticGeneration,
isBuildTimePrerendering,
getDynamicParamFromSegment,
query
)
......@@ -220,6 +237,9 @@ export async function walkTreeWithFlightRouterState({
// Create router state using the slice of the loaderTree
loaderTreeToFilter,
hintTree,
prefetchInliningEnabled,
isStaticGeneration,
isBuildTimePrerendering,
getDynamicParamFromSegment,
query
)
......@@ -339,6 +359,7 @@ export async function createFullTreeFlightDataForNavigation({
query,
getDynamicParamFromSegment,
pagePath,
workStore: workStoreForInitialRender,
} = ctx
const hintTreeForInitialRender =
......@@ -347,6 +368,9 @@ export async function createFullTreeFlightDataForNavigation({
const routerState = await createFlightRouterStateFromLoaderTree(
loaderTree,
hintTreeForInitialRender,
Boolean(experimental.prefetchInlining),
workStoreForInitialRender.isStaticGeneration,
ctx.renderOpts.isBuildTimePrerendering ?? false,
getDynamicParamFromSegment,
query
)
......
......@@ -195,8 +195,31 @@ export const enum PrefetchHint {
// On the root hint node: the head was NOT inlined into any page — fetch
// it separately. Absence of this bit means the head is bundled into a page.
HeadOutlined = 0b100000000,
// The inlining hints in this tree may be stale because the tree was
// generated before collectPrefetchHints ran (e.g. the initial RSC payload
// for a fully static page at build time). When writing this tree into the
// cache, the route entry should be immediately expired so it gets
// re-fetched with correct hints. Only set during build-time prerendering,
// never at runtime.
InliningHintsStale = 0b1000000000,
// This segment has unstable_instant = false, opting out of all
// prefetching entirely (neither static nor runtime).
PrefetchDisabled = 0b10000000000,
// This segment or one of its descendants has runtime prefetch enabled
// (HasRuntimePrefetch). Propagates upward so the root reflects the
// entire subtree.
SubtreeHasRuntimePrefetch = 0b100000000000,
}
/**
* Alias: this segment's static prefetch is skipped. Either because it uses
* runtime prefetching (fetched dynamically instead) or because prefetching
* is disabled entirely (unstable_instant = false). The segment participates
* in the bundle chain but with null data.
*/
export const StaticPrefetchDisabled =
PrefetchHint.HasRuntimePrefetch | PrefetchHint.PrefetchDisabled
/**
* Individual Flight response path
*/
......
import { LinkAccordion } from '../components/link-accordion'
export default function Page() {
return <p>hello world</p>
return (
<div>
<h1 id="home">Prefetch inlining home</h1>
<ul>
<li>
<LinkAccordion href="/test-small-chain">Small chain</LinkAccordion>
</li>
<li>
<LinkAccordion href="/test-deep/a/b/c">Deep chain</LinkAccordion>
</li>
<li>
<LinkAccordion href="/test-outlined">Outlined</LinkAccordion>
</li>
<li>
<LinkAccordion href="/test-restart/large-middle/after">
Restart
</LinkAccordion>
</li>
<li>
<LinkAccordion href="/test-parallel">Parallel</LinkAccordion>
</li>
<li>
<LinkAccordion href="/test-dynamic/hello">Dynamic</LinkAccordion>
</li>
<li>
<LinkAccordion href="/test-stale-hints/nested/deep">
Stale hints
</LinkAccordion>
</li>
<li>
<LinkAccordion href="/test-instant-false-root">
Instant false root
</LinkAccordion>
</li>
</ul>
</div>
)
}
import { ReactNode } from 'react'
import { connection } from 'next/server'
export const unstable_instant = false
export default async function Layout({ children }: { children: ReactNode }) {
await connection()
return <div>{children}</div>
}
export default function Page() {
return (
<p id="page-instant-false-root">Static page below instant:false root</p>
)
}
import { ReactNode } from 'react'
export default function Layout({ children }: { children: ReactNode }) {
return <div>{children}</div>
}
import { ReactNode } from 'react'
export default function Layout({ children }: { children: ReactNode }) {
return <div>{children}</div>
}
import { LinkAccordion } from '../../../../components/link-accordion'
// This page is the target for the stale hints test. It has multiple small
// parent layouts that would all be inlined. When the client loads this page
// via HTML, the initial tree doesn't have correct inlining hints. After
// navigating away and prefetching back, the client must not use the stale
// hints from the initial load.
export default function Page() {
return (
<div>
<p id="page-stale-hints">Stale hints page</p>
<LinkAccordion href="/">Go home</LinkAccordion>
</div>
)
}
import { ReactNode } from 'react'
export default function Layout({ children }: { children: ReactNode }) {
return <div>{children}</div>
}
......@@ -5,6 +5,7 @@ const nextConfig = {
cacheComponents: true,
experimental: {
prefetchInlining: true,
optimisticRouting: true,
},
}
......
import type * as Playwright from 'playwright'
import { nextTestSetup } from 'e2e-utils'
import { createRouterAct } from 'router-act'
// Bit values from PrefetchHint enum (const enum, so we duplicate values here)
const ParentInlinedIntoSelf = 0b100000 // 32
......@@ -162,14 +164,10 @@ describe('prefetch inlining', () => {
// accepts (children). The @sidebar slot doesn't receive the parent's
// data and is fetched independently.
//
// Turbopack and webpack produce slightly different route tree structures
// for parallel routes (turbopack adds a "(slot)" intermediate segment),
// so we use separate snapshots for each.
// Turbopack and webpack produce slightly different route tree structures
// for parallel routes. Turbopack adds a "(slot)" intermediate segment
// for the @sidebar slot; webpack puts __PAGE__ directly under it.
const data = await fetchRouteTreePrefetch(next, '/test-parallel')
if (isTurbopack) {
// Turbopack iterates children before @sidebar, so the parent
// inlines into children/__PAGE__.
expect(renderInliningTree(data.tree)).toMatchInlineSnapshot(`
"
⇣ root
......@@ -180,6 +178,8 @@ describe('prefetch inlining', () => {
"
`)
} else {
// Webpack iterates @sidebar before children, so the parent
// inlines into @sidebar/__PAGE__ instead.
expect(renderInliningTree(data.tree)).toMatchInlineSnapshot(`
"
⇣ root
......@@ -265,4 +265,51 @@ describe('prefetch inlining', () => {
const data2 = await fetchRouteTreePrefetch(next, '/test-dynamic/world')
expect(renderInliningTree(data2.tree)).toBe(helloTree)
})
// TODO: Add a test for stale hints (InliningHintsStale). The stale hints
// mechanism expires the route cache entry so the next prefetch re-fetches
// the correct tree. This is hard to test reliably with act() because the
// test needs to start on a page with stale hints, navigate away, and
// navigate back — and act() can hang on CI when intercepting requests
// that overlap with background prefetch activity. The server-side logic
// is covered by the build output (the route tree correctly includes
// InliningHintsStale for build-time static pages), but the client-side
// recovery path needs a more robust test harness.
it('instant false at root: does not prefetch segment data', async () => {
// TODO: This test exists as a temporary mitigation for a bug where
// routes with `instant = false` at the root segment cause the
// prerender to run per-request instead of being cached. Until that
// bug is fixed (see https://github.com/vercel/next.js/pull/91407),
// we fall back to treating every segment as unprefetchable. This
// test verifies that fallback works — the route builds successfully
// and the client doesn't attempt to prefetch any segment data.
let page: Playwright.Page
const browser = await next.browser('/', {
beforePageLoad(p: Playwright.Page) {
page = p
},
})
const act = createRouterAct(page!)
// Reveal the link to trigger a prefetch. Since all segments are
// treated as PrefetchDisabled, the client should fetch the route
// tree but not any segment data.
await act(async () => {
await browser
.elementByCss('input[data-link-accordion="/test-instant-false-root"]')
.click()
})
// The static page content should NOT appear in any prefetch response
// because all segments are marked as unprefetchable.
await act(
async () => {
await browser.elementByCss('a[href="/test-instant-false-root"]').click()
},
// The page content should not have been prefetched — it will be
// fetched during navigation instead.
{ includes: 'Static page below instant:false root' }
)
})
})
......@@ -293,6 +293,7 @@ export function createRouterAct(
}
const prevBatch = currentBatch
const batch: Batch = {
pendingRequestChecks: new Set(),
pendingRequests: new Set(),
......
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