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

Refactor server from CacheNodeSeedData -> TransportData (#96679)

The previous PR in this stack introduced TransportData, the unified
response format, but produced it via a temporary adapter layer that
converted from the old data formats — FlightRouterState and
CacheNodeSeedData trees, encoded as FlightDataPath entries. As promised
there, this PR updates the server to produce the new format directly and
deletes the adapter. Neither FlightRouterState nor CacheNodeSeedData
appears in a rendered response anymore; FlightRouterState survives only
on the client (router state, history) and as the request tree the client
sends to the server, and CacheNodeSeedData is deleted from the codebase
entirely.

createComponentTree now returns the response's transport tree: each node
carries its segment identity, its prefetch hints, and its render output,
constructed in place as the tree renders. When a non-PPR prefetch stops
at a loading boundary, the subtree below the cut is emitted as
structure-only nodes with no render output — the same shape the client
already interprets as "fetch lazily".

createFlightRouterStateFromLoaderTree is replaced by
createTransportTreeFromLoaderTree, which covers the cases where nothing
is rendered: router-state-only responses, route tree prefetches, the
structure below a loading-boundary cut, and error payloads. The prefetch
hints computation is shared with createComponentTree through
computeSegmentPrefetchHints so the two producers cannot drift.

walkTreeWithFlightRouterState returns the transport tree those producers
build: each emit is a transport node, and the levels above it become
"skipped" nodes (position acknowledged, no output attached). The
FlightDataPath encoding this replaces — repeating [segment,
parallelRouteKey] prefixes terminated by a positional data tuple, plus
the hack in generateDynamicRSCPayload that sliced the root segment off
every path — is deleted, along with the FlightData, FlightDataPath, and
FlightDataSegment types.

This also deletes the overriddenSegment / canSegmentBeOverridden
mechanism, which turned out to be dead code: it could only trigger if a
dynamic segment reached the walk as an uninterpolated string, but
getDynamicParam throws in that case rather than returning null.

Instant validation rebuilds its payload tree natively as well: the
builders walk the original payload's transport tree in parallel with the
loader tree, taking structure from the former and render output from the
validation segment cache.
parent c37b7368
......@@ -1466,5 +1466,6 @@
"1465": "\\`experimental.useCache\\` cannot be disabled when \\`cacheComponents\\` is enabled, because Cache Components relies on the \\`\"use cache\"\\` directive. Please remove it from %s.",
"1466": "TypeScript %s does not provide the compiler API required by Next.js. Set %s to true in your Next.js config to use the TypeScript CLI, or install TypeScript 6 instead.",
"1467": "TypeScript %s does not provide the compiler API required by Next.js. Set %s back to true in your Next.js config to use the TypeScript CLI, or install TypeScript 6 instead.",
"1468": "Missing workUnitStore in createComponentTree"
"1468": "Missing workUnitStore in createComponentTree",
"1469": "The payload's transport tree is missing a slot that exists in the loader tree: %s"
}
......@@ -147,13 +147,6 @@ export enum PrefetchKind {
FULL = 'full',
}
/**
* Prefetch adds the provided FlightData to the prefetch cache
* - Creates the router state tree based on the patch in FlightData
* - Adds the FlightData to the prefetch cache
* - In ACTION_NAVIGATE the prefetch cache is checked and the router state tree and FlightData are applied.
*/
export interface PushRef {
/**
* If the app-router should push a new history entry in app-router's useEffect()
......
......@@ -152,11 +152,11 @@ export function getStaleTimeMs(staleTimeSeconds: number): number {
* The output of a single segment from an RSC server response, stored
* directly on the RouteTree node it describes.
*
* `rsc` may be null: that means the response covered this segment's position
* without rendering it (e.g. an ancestor of a rendered subtree that the
* client is expected to already have). This is distinct from the RouteTree
* node's `data` slot being null, which means the response carried no
* information about the segment at all.
* `rsc` may be null: that means the response skipped this segment — it
* acknowledged the position without rendering it (e.g. an ancestor of a
* rendered subtree that the client is expected to already have). This is
* distinct from the RouteTree node's `data` slot being null, which means
* the response carried no information about the segment at all.
*/
export type RSCSegmentData = {
rsc: React.ReactNode
......@@ -2256,8 +2256,8 @@ export async function fetchRouteOnCacheMiss(
}
// Read head vary params synchronously (unioning in the response-level
// root params). Individual segments carry their own iterables in
// CacheNodeSeedData; the root iterable is threaded down so each segment
// root params). Individual segments carry their own iterables in the
// transport tree; the root iterable is threaded down so each segment
// unions it too.
writeDynamicTreeResponseIntoCache(
Date.now(),
......@@ -3446,7 +3446,7 @@ function writeDynamicTreeResponseIntoCache(
if (
transportData === undefined ||
serverData.n !== undefined ||
// A covered root (data present without output) means the response's
// A skipped root (data present without output) means the response's
// rendered content starts below the root — an unexpected format for this
// flow, which always requests a full render from the root.
(transportData.t.d !== undefined && transportData.t.d.r === null)
......@@ -3686,9 +3686,9 @@ function writeSeedDataIntoCache(
entriesOwnedByCurrentTask
)
} else {
// A null rsc with a non-null data object means the response covered this
// position without rendering it (an intermediate segment on the path to
// a patched subtree). Nothing to write, but the children may have output.
// A null rsc with a non-null data object means the response skipped this
// segment (an intermediate position on the path to a patched subtree).
// Nothing to write, but the children may have output.
}
// Recursively write the child data into the cache.
......
......@@ -222,11 +222,10 @@ export function createRouteTreeNode<TData>(
* server-sent structure whose output the client fetches lazily — are
* authoritative: their identity, hints, and subtree come entirely from
* the response.
* - Covered-but-not-rendered nodes (data with a null rsc) sit on the path
* from the root down to the rendered subtrees. The client is expected to
* already have them, so their refresh state and hints are inherited from
* the base tree, and any slot the response doesn't mention is reused from
* the base as-is.
* - Skipped nodes (data with a null rsc) sit on the path from the root down
* to the rendered subtrees. The client is expected to already have them,
* so their refresh state and hints are inherited from the base tree, and
* any slot the response doesn't mention is reused from the base as-is.
*
* TODO: The base is a FlightRouterState only because that's the
* representation the client router currently renders from (the router
......@@ -363,7 +362,7 @@ function decodeTransportNode(
if (inheritsFromBase) {
// Recompute the propagated "subtree" prefetch hints for this segment,
// since its children may combine response and base subtrees. Mirrors the
// propagation done on the server in createFlightRouterStateFromLoaderTree.
// propagation done on the server in createTransportTreeFromLoaderTree.
let propagated = prefetchHints & ~SubtreePrefetchHints
if (slots !== null) {
for (const childTree of slots.values()) {
......
import type { ComponentType, ErrorInfo, JSX, ReactNode } from 'react'
import {
convertFlightDataPathsToPartialTransportData,
convertInitialFlightDataToFullTransportData,
} from './transport-adapter'
import type { PartialTransportData } from '../../shared/lib/rsc-transport'
import type { RenderOpts, PreloadCallbacks } from './types'
import type {
......@@ -10,7 +6,6 @@ import type {
DynamicParamTypesShort,
DynamicSegmentTuple,
FlightRouterState,
CacheNodeSeedData,
RSCPayload,
NavigationFlightResponse,
ActionFlightResponse,
......@@ -135,10 +130,10 @@ import { getSegmentParam } from '../../shared/lib/router/utils/get-segment-param
import { getScriptNonceFromHeader } from './get-script-nonce-from-header'
import { parseAndValidateFlightRouterState } from './parse-and-validate-flight-router-state'
import {
createFlightRouterStateFromLoaderTree,
createFullTransportTreeFromLoaderTree,
getMissingPrefetchHintPolicy,
type MissingPrefetchHintPolicy,
} from './create-flight-router-state-from-loader-tree'
} from './create-transport-tree-from-loader-tree'
import { handleAction } from './action-handler'
import { isBailoutToCSRError } from '../../shared/lib/lazy-dynamic/bailout-to-csr'
import { warn, error } from '../../build/output/log'
......@@ -153,9 +148,9 @@ import { addPathPrefix } from '../../shared/lib/router/utils/add-path-prefix'
import { makeGetServerInsertedHTML } from './make-get-server-inserted-html'
import {
walkTreeWithFlightRouterState,
createFullTreeFlightDataForNavigation,
createFullTreeForNavigation,
} from './walk-tree-with-flight-router-state'
import { createComponentTree, getRootParams } from './create-component-tree'
import { createFullComponentTree, getRootParams } from './create-component-tree'
import { getAssetQueryString } from './get-asset-query-string'
import {
getClientReferenceManifest,
......@@ -756,39 +751,41 @@ async function generateDynamicRSCPayload(
})
)
const flightDataPaths = (
needsFullTree
? await createFullTreeFlightDataForNavigation({
ctx,
loaderTree,
rscHead,
injectedCSS: new Set(),
injectedJS: new Set(),
injectedFontPreloadTags: new Set(),
preloadCallbacks,
MetadataOutlet,
})
: await walkTreeWithFlightRouterState({
ctx,
loaderTreeToFilter: loaderTree,
parentParams: {},
flightRouterState,
rscHead,
injectedCSS: new Set(),
injectedJS: new Set(),
injectedFontPreloadTags: new Set(),
rootLayoutIncluded: false,
preloadCallbacks,
MetadataOutlet,
hintTree: ctx.renderOpts.prefetchHints?.[ctx.pagePath] ?? null,
})
).map((path) => path.slice(1)) // remove the '' (root) segment
const responseTree = needsFullTree
? await createFullTreeForNavigation({
ctx,
loaderTree,
rscHead,
injectedCSS: new Set(),
injectedJS: new Set(),
injectedFontPreloadTags: new Set(),
preloadCallbacks,
MetadataOutlet,
})
: await walkTreeWithFlightRouterState({
ctx,
loaderTreeToFilter: loaderTree,
parentParams: {},
flightRouterState,
rscHead,
injectedCSS: new Set(),
injectedJS: new Set(),
injectedFontPreloadTags: new Set(),
rootLayoutIncluded: false,
preloadCallbacks,
MetadataOutlet,
hintTree: ctx.renderOpts.prefetchHints?.[ctx.pagePath] ?? null,
})
if (flightDataPaths.length > 0) {
transportData = convertFlightDataPathsToPartialTransportData(
flightDataPaths,
getMetadataVaryParamsAccumulator()
)
if (responseTree !== null) {
transportData = {
t: responseTree.tree,
h: {
r: responseTree.head,
p: responseTree.isHeadPartial,
v: getMetadataVaryParamsAccumulator(),
},
}
}
}
......@@ -919,7 +916,6 @@ async function generateDynamicFlightRenderResult(
options?: {
actionResult: ActionResult
skipPageRendering: boolean
componentTree?: CacheNodeSeedData
preloadCallbacks?: PreloadCallbacks
temporaryReferences?: WeakMap<any, string>
waitUntil?: Promise<unknown>
......@@ -2141,7 +2137,6 @@ async function getRSCPayload(
}
const {
getDynamicParamFromSegment,
query,
appUsingSizeAdjustment,
componentMod: { createMetadataComponents, createElement, Fragment },
......@@ -2149,18 +2144,6 @@ 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,
ctx.missingPrefetchHintPolicy,
ctx.renderOpts.partialPrefetching,
getDynamicParamFromSegment,
query
)
const serveStreamingMetadata = !!ctx.renderOpts.serveStreamingMetadata
const hasGlobalNotFound = !!tree[2]['global-not-found']
......@@ -2181,7 +2164,7 @@ async function getRSCPayload(
const preloadCallbacks: PreloadCallbacks = []
const seedData = await createComponentTree({
const initialTree = await createFullComponentTree({
ctx,
loaderTree: tree,
parentParams: {},
......@@ -2196,6 +2179,7 @@ async function getRSCPayload(
authInterrupts: ctx.renderOpts.experimental.authInterrupts,
MetadataOutlet,
isPrerendering,
hintTree: hints,
})
// When the `vary` response header is present with `Next-URL`, that means there's a chance
......@@ -2251,13 +2235,14 @@ async function getRSCPayload(
c: prepareInitialCanonicalUrl(url),
q: getRenderedSearch(query),
i: !!couldBeIntercepted,
t: convertInitialFlightDataToFullTransportData(
initialTree,
seedData,
initialHead,
isPossiblyPartialHead,
getMetadataVaryParamsAccumulator()
),
t: {
t: initialTree,
h: {
r: initialHead,
p: isPossiblyPartialHead,
v: getMetadataVaryParamsAccumulator(),
},
},
m: missingSlots,
G: [GlobalError, globalErrorStyles],
// Tells the client whether this route supports per-segment prefetching.
......@@ -2348,15 +2333,6 @@ async function getErrorRSCPayload(
const errorPrefetchInliningEnabled = Boolean(
ctx.renderOpts.experimental.prefetchInlining
)
const initialTree = await createFlightRouterStateFromLoaderTree(
tree,
errorHints,
errorPrefetchInliningEnabled,
ctx.missingPrefetchHintPolicy,
ctx.renderOpts.partialPrefetching,
getDynamicParamFromSegment,
query
)
let err: Error | undefined = undefined
if (ssrError) {
......@@ -2365,30 +2341,37 @@ async function getErrorRSCPayload(
// For metadata notFound error there's no global not found boundary on top
// so we create a not found page with AppRouter
const seedData: CacheNodeSeedData = [
const errorShell = createElement(
'html',
{
id: '__next_error__',
},
createElement('head', null),
createElement(
'html',
{
id: '__next_error__',
},
createElement('head', null),
createElement(
'body',
null,
process.env.__NEXT_DEV_SERVER && err
? createElement('template', {
'data-next-error-message': err.message,
'data-next-error-digest': 'digest' in err ? err.digest : '',
'data-next-error-stack': err.stack,
})
: null
)
),
{},
null,
false,
null, // varyParams - not tracked for error pages
]
'body',
null,
process.env.__NEXT_DEV_SERVER && err
? createElement('template', {
'data-next-error-message': err.message,
'data-next-error-digest': 'digest' in err ? err.digest : '',
'data-next-error-stack': err.stack,
})
: null
)
)
const initialTree = await createFullTransportTreeFromLoaderTree(
tree,
errorHints,
errorPrefetchInliningEnabled,
ctx.missingPrefetchHintPolicy,
ctx.renderOpts.partialPrefetching,
getDynamicParamFromSegment,
query
)
// Attach the error shell as the root's render output. Vary params are not
// tracked for error pages.
initialTree.d = { r: errorShell, p: false, v: null }
const { GlobalError, styles: globalErrorStyles } = await getGlobalErrorStyles(
tree,
......@@ -2402,13 +2385,14 @@ async function getErrorRSCPayload(
q: getRenderedSearch(query),
m: undefined,
i: false,
t: convertInitialFlightDataToFullTransportData(
initialTree,
seedData,
initialHead,
isPossiblyPartialHead,
getMetadataVaryParamsAccumulator()
),
t: {
t: initialTree,
h: {
r: initialHead,
p: isPossiblyPartialHead,
v: getMetadataVaryParamsAccumulator(),
},
},
G: [GlobalError, globalErrorStyles],
// Tells the client whether this route supports per-segment prefetching.
// With Cache Components, all routes support it. Without it, only fully
......
......@@ -847,7 +847,7 @@ async function collectPrefetchHintsImpl(
// collectPrefetchHints when prefetch inlining is disabled: there are no sizes
// to measure, but the static-prefetch-attempt hint still needs a manifest
// tree — the client reads the bit per node, and the runtime hint merging
// (createFlightRouterStateFromLoaderTree) walks the manifest tree in parallel
// (createTransportTreeFromLoaderTree) walks the manifest tree in parallel
// with the loader tree, so a bit that's missing from a node never reaches the
// corresponding segment.
function createUniformHintTree(
......
import { getMissingPrefetchHintPolicy } from './create-flight-router-state-from-loader-tree'
import { getMissingPrefetchHintPolicy } from './create-transport-tree-from-loader-tree'
describe('getMissingPrefetchHintPolicy', () => {
it('marks missing build-time hints as stale', () => {
......
......@@ -2,9 +2,16 @@ import type { LoaderTree } from '../lib/app-dir-module'
import {
PrefetchHint,
propagateSubtreeBits,
type FlightRouterState,
type PrefetchHints,
} from '../../shared/lib/app-router-types'
import type {
FullTransportNode,
PartialTransportNode,
} from '../../shared/lib/rsc-transport'
import {
createSkippedSegmentData,
segmentToTransportSegment,
} from '../../shared/lib/rsc-transport'
import type { GetDynamicParamFromSegment } from './app-render'
import { addSearchParamsIfPageSegment } from '../../shared/lib/segment'
import type { AppSegmentConfig } from '../../build/segment-config/app/app-segment-config'
......@@ -38,24 +45,28 @@ export function getMissingPrefetchHintPolicy(
return 'none'
}
async function createFlightRouterStateFromLoaderTreeImpl(
/**
* Computes the segment-local prefetch hints for a loader tree node: the
* precomputed build-time hints unioned with the hints derived from the
* segment's own configuration (instant/prefetch exports, loading boundary,
* root layout position). Does not include the "subtree" bits propagated up
* from children — the caller folds those in with propagateSubtreeBits as it
* assembles the tree.
*
* Shared by createComponentTree (rendered trees) and the builders in this
* module (structure-only trees) so the two cannot drift.
*/
export async function computeSegmentPrefetchHints(
loaderTree: LoaderTree,
hintTree: PrefetchHints | null,
prefetchInliningEnabled: boolean,
missingPrefetchHintPolicy: MissingPrefetchHintPolicy,
partialPrefetching: boolean | 'unstable_eager' | undefined,
getDynamicParamFromSegment: GetDynamicParamFromSegment,
searchParams: any,
didFindRootLayout: boolean
): Promise<FlightRouterState> {
const [segment, parallelRoutes, { layout, loading, page }] = loaderTree
const dynamicParam = getDynamicParamFromSegment(loaderTree)
const treeSegment = dynamicParam ? dynamicParam.treeSegment : segment
const segmentTree: FlightRouterState = [
addSearchParamsIfPageSegment(treeSegment, searchParams),
{},
]
// Whether this segment is at or above the root layout (no layout was found
// above it).
isRootLayoutOrAbove: boolean
): Promise<number> {
const { layout, loading, page } = loaderTree[2]
// Load the layout or page module to check its instant and prefetch
// configs. When a segment doesn't export prefetch, it defaults to
......@@ -107,14 +118,9 @@ async function createFlightRouterStateFromLoaderTreeImpl(
}
}
// Mark every segment at or above the root layout (i.e. until we descend past
// the first segment that has a layout).
if (!didFindRootLayout) {
// Mark every segment at or above the root layout.
if (isRootLayoutOrAbove) {
prefetchHints |= PrefetchHint.IsRootLayoutOrAbove
if (typeof layout !== 'undefined') {
// This segment is the root layout; its descendants are below it.
didFindRootLayout = true
}
}
if (instantConfig === false) {
......@@ -150,14 +156,58 @@ async function createFlightRouterStateFromLoaderTreeImpl(
prefetchHints |= PrefetchHint.SegmentHasLoadingBoundary
}
const children: FlightRouterState[1] = {}
return prefetchHints
}
/**
* Builds a transport tree with no render output directly from the loader
* tree: each node carries its segment identity and prefetch hints. Rendered
* trees are produced by createComponentTree instead; this module covers the
* responses (and subtrees) where nothing is rendered — router-state-only
* responses, route tree prefetches, the structure beneath a loading-boundary
* cut in a non-PPR prefetch, and error payloads.
*/
async function createTransportTreeFromLoaderTreeImpl(
loaderTree: LoaderTree,
// What to emit for each position: nothing (the client fetches it lazily;
// false) or skipped data (true). Full trees require the latter — see
// createFullTransportTreeFromLoaderTree.
emitSkippedData: boolean,
hintTree: PrefetchHints | null,
prefetchInliningEnabled: boolean,
missingPrefetchHintPolicy: MissingPrefetchHintPolicy,
partialPrefetching: boolean | 'unstable_eager' | undefined,
getDynamicParamFromSegment: GetDynamicParamFromSegment,
searchParams: any,
didFindRootLayout: boolean
): Promise<PartialTransportNode> {
const [segment, parallelRoutes, { layout }] = loaderTree
const dynamicParam = getDynamicParamFromSegment(loaderTree)
const treeSegment = dynamicParam ? dynamicParam.treeSegment : segment
let prefetchHints = await computeSegmentPrefetchHints(
loaderTree,
hintTree,
prefetchInliningEnabled,
missingPrefetchHintPolicy,
partialPrefetching,
!didFindRootLayout
)
if (!didFindRootLayout && typeof layout !== 'undefined') {
// This segment is the root layout; its descendants are below it.
didFindRootLayout = true
}
let children: Map<string, PartialTransportNode> | undefined
for (const parallelRouteKey in parallelRoutes) {
// Look up the child hint node by parallel route key, traversing the
// hint tree in parallel with the loader tree.
const childHintNode = hintTree?.slots?.[parallelRouteKey] ?? null
const child = await createFlightRouterStateFromLoaderTreeImpl(
const child = await createTransportTreeFromLoaderTreeImpl(
parallelRoutes[parallelRouteKey],
emitSkippedData,
childHintNode,
prefetchInliningEnabled,
missingPrefetchHintPolicy,
......@@ -167,21 +217,39 @@ async function createFlightRouterStateFromLoaderTreeImpl(
didFindRootLayout
)
// Propagate subtree flags from children
if (child[4] !== undefined) {
prefetchHints = propagateSubtreeBits(prefetchHints, child[4])
if (child.h !== undefined) {
prefetchHints = propagateSubtreeBits(prefetchHints, child.h)
}
children[parallelRouteKey] = child
if (children === undefined) {
children = new Map()
}
children.set(parallelRouteKey, child)
}
segmentTree[1] = children
const node: PartialTransportNode = {
s: segmentToTransportSegment(
addSearchParamsIfPageSegment(treeSegment, searchParams)
),
}
if (prefetchHints !== 0) {
segmentTree[4] = prefetchHints
node.h = prefetchHints
}
return segmentTree
if (emitSkippedData) {
node.d = createSkippedSegmentData()
}
if (children !== undefined) {
node.c = children
}
return node
}
export async function createFlightRouterStateFromLoaderTree(
/**
* Builds a structure-only transport tree from the loader tree: identity and
* hints, no render output on any node. Used for router-state-only responses
* and for the structure beneath a loading-boundary cut in a non-PPR
* prefetch, where the client fetches the content lazily.
*/
export async function createTransportTreeFromLoaderTree(
loaderTree: LoaderTree,
hintTree: PrefetchHints | null,
prefetchInliningEnabled: boolean,
......@@ -193,9 +261,10 @@ export async function createFlightRouterStateFromLoaderTree(
// slice that starts below the root layout doesn't mark a sub-layout as the
// root layout.
didFindRootLayout: boolean = false
): Promise<FlightRouterState> {
return createFlightRouterStateFromLoaderTreeImpl(
): Promise<PartialTransportNode> {
return createTransportTreeFromLoaderTreeImpl(
loaderTree,
false,
hintTree,
prefetchInliningEnabled,
missingPrefetchHintPolicy,
......@@ -206,6 +275,40 @@ export async function createFlightRouterStateFromLoaderTree(
)
}
/**
* Builds a full transport tree from the loader tree where every position is
* skipped. Used for error payloads, which don't render the route: the caller
* attaches the error shell to the root node's data.
*/
export async function createFullTransportTreeFromLoaderTree(
loaderTree: LoaderTree,
hintTree: PrefetchHints | null,
prefetchInliningEnabled: boolean,
missingPrefetchHintPolicy: MissingPrefetchHintPolicy,
partialPrefetching: boolean | 'unstable_eager' | undefined,
getDynamicParamFromSegment: GetDynamicParamFromSegment,
searchParams: any
): Promise<FullTransportNode> {
// With emitSkippedData, every node carries data, which is what
// FullTransportNode requires. TypeScript can't see through the flag,
// hence the cast.
return createTransportTreeFromLoaderTreeImpl(
loaderTree,
true,
hintTree,
prefetchInliningEnabled,
missingPrefetchHintPolicy,
partialPrefetching,
getDynamicParamFromSegment,
searchParams,
false
) as Promise<FullTransportNode>
}
/**
* Builds the transport tree for a route tree prefetch response. Router state
* only — no render output.
*/
export async function createRouteTreePrefetch(
loaderTree: LoaderTree,
hintTree: PrefetchHints | null,
......@@ -213,15 +316,16 @@ export async function createRouteTreePrefetch(
missingPrefetchHintPolicy: MissingPrefetchHintPolicy,
partialPrefetching: boolean | 'unstable_eager' | undefined,
getDynamicParamFromSegment: GetDynamicParamFromSegment,
// See note on createFlightRouterStateFromLoaderTree's didFindRootLayout.
// See note on createTransportTreeFromLoaderTree's didFindRootLayout.
didFindRootLayout: boolean = false
): Promise<FlightRouterState> {
): Promise<PartialTransportNode> {
// Search params should not be added to page segment's cache key during a
// route tree prefetch request, because they do not affect the structure of
// the route. The client cache has its own logic to handle search params.
const searchParams = {}
return createFlightRouterStateFromLoaderTreeImpl(
return createTransportTreeFromLoaderTreeImpl(
loaderTree,
false,
hintTree,
prefetchInliningEnabled,
missingPrefetchHintPolicy,
......
import type {
CacheNodeSeedData,
FlightDataPath,
FlightRouterState,
HeadData,
} from '../../shared/lib/app-router-types'
import type { VaryParamsIterable } from '../../shared/lib/segment-cache/vary-params-decoding'
import type {
FullTransportData,
FullTransportNode,
PartialTransportData,
PartialTransportNode,
TransportSegmentData,
} from '../../shared/lib/rsc-transport'
import { segmentToTransportSegment } from '../../shared/lib/rsc-transport'
/**
* Adapts the render's internal output — FlightDataPath entries, each carrying
* a FlightRouterState patch and a CacheNodeSeedData tree — into the transport
* format: a single root-anchored tree where every node carries both its
* identity and (optionally) its render output.
*
* TODO: This is a transitional step. Eventually the render should produce
* transport nodes directly, at which point the internal FlightDataPath /
* CacheNodeSeedData representation (and this adapter) can be deleted.
*/
/**
* Marks a segment's position as covered by the response without carrying any
* output for it. Used for the segments along the path from the root to a
* rendered subtree: the client already has them; the response is only
* accounting for their position.
*/
function createCoveredSegmentData(): TransportSegmentData {
return { r: null, p: true, v: null }
}
/**
* Converts a rendered subtree — a FlightRouterState patch zipped with its
* CacheNodeSeedData — into a transport node.
*/
function convertRenderedSubtree(
routerState: FlightRouterState,
seedData: CacheNodeSeedData | null
): PartialTransportNode {
const node: PartialTransportNode = {
s: segmentToTransportSegment(routerState[0]),
}
const hints = routerState[4]
if (hints !== undefined && hints !== 0) {
node.h = hints
}
if (seedData !== null) {
node.d = { r: seedData[0], p: seedData[3], v: seedData[4] }
}
const routerStateChildren = routerState[1]
const seedDataChildren = seedData !== null ? seedData[1] : null
let children: Map<string, PartialTransportNode> | undefined
for (const parallelRouteKey in routerStateChildren) {
const childSeedData =
seedDataChildren !== null
? (seedDataChildren[parallelRouteKey] ?? null)
: null
if (children === undefined) {
children = new Map()
}
children.set(
parallelRouteKey,
convertRenderedSubtree(
routerStateChildren[parallelRouteKey],
childSeedData
)
)
}
if (children !== undefined) {
node.c = children
}
return node
}
/**
* Converts the output of the shared-layout diff (one or more FlightDataPath
* entries, with the root segment already stripped) into a single partial
* transport tree.
*
* Each path is a repeating [parallelRouteKey, segment] prefix followed by
* [routerStatePatch, seedData, head, isHeadPartial]. The prefixes become
* covered-but-not-rendered nodes; the patches become rendered subtrees. All
* paths share the same head, so it's emitted once at the response level.
*/
export function convertFlightDataPathsToPartialTransportData(
flightDataPaths: FlightDataPath[],
headVaryParams: VaryParamsIterable | null
): PartialTransportData {
const root: PartialTransportNode = {
s: '',
}
let head: TransportSegmentData | undefined
for (const flightDataPath of flightDataPaths) {
const prefixLength = flightDataPath.length - 4
if (prefixLength > 0 && root.d === undefined) {
// The rendered subtree is below the root, so the root is a covered
// position.
root.d = createCoveredSegmentData()
}
const routerStatePatch: FlightRouterState = flightDataPath[prefixLength]
const seedData: CacheNodeSeedData | null = flightDataPath[prefixLength + 1]
const headNode: HeadData = flightDataPath[prefixLength + 2]
const isHeadPartial: boolean = flightDataPath[prefixLength + 3]
if (head === undefined) {
// The head is identical across all paths in a response; take the
// first one.
head = { r: headNode, p: isHeadPartial, v: headVaryParams }
}
// Walk the [parallelRouteKey, segment] prefix, creating covered nodes
// along the way, then attach the rendered subtree at the anchor.
let parent = root
let index = 0
while (index < prefixLength - 2) {
const parallelRouteKey: string = flightDataPath[index]
const segment = flightDataPath[index + 1]
let children = parent.c
if (children === undefined) {
children = parent.c = new Map()
}
let child = children.get(parallelRouteKey)
if (child === undefined) {
child = {
s: segmentToTransportSegment(segment),
d: createCoveredSegmentData(),
}
children.set(parallelRouteKey, child)
}
parent = child
index += 2
}
const subtree = convertRenderedSubtree(routerStatePatch, seedData)
if (prefixLength === 0) {
// A root render. The rendered subtree *is* the root of the
// transport tree.
root.s = subtree.s
if (subtree.h !== undefined) {
root.h = subtree.h
}
if (subtree.d !== undefined) {
root.d = subtree.d
}
if (subtree.c !== undefined) {
root.c = subtree.c
}
} else {
const parallelRouteKey: string = flightDataPath[prefixLength - 2]
let children = parent.c
if (children === undefined) {
children = parent.c = new Map()
}
children.set(parallelRouteKey, subtree)
}
}
const transportData: PartialTransportData = { t: root }
if (head !== undefined) {
transportData.h = head
}
return transportData
}
/**
* Converts the full render of an initial document (or error) payload into a
* full transport tree. Structure without seed data — which only occurs in
* hand-constructed error payloads, where the seed data covers only the root —
* is emitted as covered-but-not-rendered rather than omitted, preserving the
* "full trees have no lazy holes" property.
*/
export function convertInitialFlightDataToFullTransportData(
routerState: FlightRouterState,
seedData: CacheNodeSeedData,
head: HeadData,
isHeadPartial: boolean,
headVaryParams: VaryParamsIterable | null
): FullTransportData {
return {
t: convertFullSubtree(routerState, seedData),
h: { r: head, p: isHeadPartial, v: headVaryParams },
}
}
function convertFullSubtree(
routerState: FlightRouterState,
seedData: CacheNodeSeedData | null
): FullTransportNode {
const node: FullTransportNode = {
s: segmentToTransportSegment(routerState[0]),
d:
seedData !== null
? { r: seedData[0], p: seedData[3], v: seedData[4] }
: createCoveredSegmentData(),
}
const hints = routerState[4]
if (hints !== undefined && hints !== 0) {
node.h = hints
}
const routerStateChildren = routerState[1]
const seedDataChildren = seedData !== null ? seedData[1] : null
let children: Map<string, FullTransportNode> | undefined
for (const parallelRouteKey in routerStateChildren) {
const childSeedData =
seedDataChildren !== null
? (seedDataChildren[parallelRouteKey] ?? null)
: null
if (children === undefined) {
children = new Map()
}
children.set(
parallelRouteKey,
convertFullSubtree(routerStateChildren[parallelRouteKey], childSeedData)
)
}
if (children !== undefined) {
node.c = children
}
return node
}
......@@ -321,7 +321,7 @@ export const SubtreePrefetchHints =
* root segment ends up reflecting the entire subtree.
*
* Used wherever a route tree is assembled bottom-up: on the server when building
* a prefetch tree (createFlightRouterStateFromLoaderTree) and on the client when
* a transport tree (createTransportTreeFromLoaderTree) and on the client when
* merging a navigation patch into the existing tree (convertServerPatchToFullTree).
* Keep these in sync by routing both through this helper.
*/
......@@ -355,7 +355,9 @@ export function propagateSubtreeBits(
}
/**
* Individual Flight response path
* A path through the segment tree: a repeating sequence of segment and
* parallel route key. Used by the client to address positions in the
* CacheNode tree (see layout-router).
*/
export type FlightSegmentPath =
// Uses `any` as repeating pattern can't be typed.
......@@ -370,64 +372,6 @@ export type FlightSegmentPath =
parallelRouterKey: string,
]
/**
* Represents a tree of segments and the Flight data (i.e. React nodes) that
* correspond to each one. The tree is isomorphic to the FlightRouterState;
* however in the future we want to be able to fetch arbitrary partial segments
* without having to fetch all its children. So this response format will
* likely change.
*/
export type CacheNodeSeedData = [
node: React.ReactNode | null,
parallelRoutes: {
[parallelRouterKey: string]: CacheNodeSeedData | null
},
// TODO: This field is no longer used. Remove it.
loading: null,
isPartial: boolean,
/**
* An AsyncIterable that yields the route params this segment accessed during
* server rendering (one name per yield, deduped). Used by the client router
* to determine cache key specificity - segments that only access certain
* params can be reused across navigations where unaccessed params change.
*
* Does NOT include root params; those are emitted once at the top level of
* the response (see `r` on the payload) and unioned in by the consumer.
*
* - null: tracking was not enabled for this render (e.g., not a prerender).
* Treat conservatively - assume all params vary.
* - Drains to empty Set: segment accesses no params (e.g., client components,
* or server components that don't read params). Can be shared across all
* param values.
* - Drains to non-empty Set: segment depends on those params. Can only reuse
* when those specific params match.
*/
varyParams: VaryParamsIterable | null,
]
export type FlightDataSegment = [
/* segment of the rendered slice: */ Segment,
/* treePatch */ FlightRouterState,
/* cacheNodeSeedData */ CacheNodeSeedData | null, // Can be null during prefetch if there's no loading component
/* head: viewport */ HeadData,
/* isHeadPartial */ boolean,
]
export type FlightDataPath =
// Uses `any` as repeating pattern can't be typed.
| any[]
// Looks somewhat like this
| [
// Holds full path to the segment.
...FlightSegmentPath[],
...FlightDataSegment,
]
/**
* The Flight response data
*/
export type FlightData = Array<FlightDataPath> | string
/**
* Per-route prefetch hints computed at build time. Mirrors the shape of the
* loader tree so hints can be traversed in parallel during router state
......
......@@ -54,21 +54,33 @@ export type TransportDynamicSegment = {
* "rendered vs skipped" state is a single presence check. Also used for the
* head (metadata/viewport), which is output without structure.
*
* `r` may be null: the response covered this segment's position without
* rendering anything for it — e.g. a shared layout the client is expected to
* already have. This is distinct from `d` being absent on the node, which
* means the response makes no claim about the segment's output at all (the
* client should fetch it lazily if it doesn't have it).
* `r` may be null: the segment was skipped — the response acknowledges its
* position without rendering anything for it, e.g. a shared layout the
* client is expected to already have. This is distinct from `d` being absent
* on the node, which means the response makes no claim about the segment's
* output at all (the client should fetch it lazily if it doesn't have it).
*/
export type TransportSegmentData = {
/** rsc — the React node for this segment; null = covered but not rendered */
/** rsc — the React node for this segment; null = skipped (not rendered) */
r: React.ReactNode
/** isPartial — contains unresolved dynamic holes (static prerender) */
p: boolean
/**
* varyParams — params this segment's output depends on. Does not include
* root params, which are emitted once at the response level (`r` on the
* response wrapper).
* varyParams — an iterable of the route params this segment's output
* depends on (one name per yield, deduped). Used by the client router to
* determine cache key specificity: segments that only access certain
* params can be reused across navigations where unaccessed params change.
*
* Does NOT include root params; those are emitted once at the response
* level (`r` on the response wrapper) and unioned in by the consumer.
*
* - null: tracking was not enabled for this render (e.g., not a
* prerender). Treat conservatively — assume all params vary.
* - Drains to empty: segment accesses no params (e.g., client components,
* or server components that don't read params). Can be shared across
* all param values.
* - Drains to non-empty: segment depends on those params. Can only be
* reused when those specific params match.
*/
v: VaryParamsIterable | null
}
......@@ -87,10 +99,9 @@ type TransportNodeShape = {
/**
* A node in a FULL response tree: every node carries data, and slot maps are
* exhaustive. Produced by full renders: the initial document payload and
* error payloads. "Full" means every node is covered by the response — there
* error payloads. "Full" means the response accounts for every node — there
* is nothing for the client to fetch lazily. Data-level holes
* (`d.p === true`) and covered-but-not-rendered nodes (`d.r === null`) are
* still possible.
* (`d.p === true`) and skipped nodes (`d.r === null`) are still possible.
*/
export type FullTransportNode = TransportNodeShape & {
/** data — always present in a full tree */
......@@ -113,16 +124,16 @@ export type FullTransportNode = TransportNodeShape & {
*
* - A node present in the tree is authoritative for that position's identity.
* - `d` present: the response accounts for this segment. Its output is `d.r`,
* which may be null when the position is covered without rendering (e.g. a
* shared layout the client already has).
* which may be null when the segment was skipped — not rendered because
* the client already has it (e.g. a shared layout).
* - `d` omitted: the response makes no claim about this segment's output.
* The client keeps what it has, or lazily fetches when it renders (e.g.
* segments beneath a loading boundary in a non-PPR prefetch).
* - A slot key omitted from `c` (or `c` omitted): on a covered node
* - A slot key omitted from `c` (or `c` omitted): on a skipped node
* (`d.r === null`), the response carries no information about that slot
* and the client keeps its subtree untouched. On any other node the
* subtree is authoritative, so an omitted slot is simply absent.
* - `h` omitted: on a covered node, the client keeps its existing hints for
* - `h` omitted: on a skipped node, the client keeps its existing hints for
* the segment; on any other node it means the hints are zero.
*
* TODO: A node with `d` omitted currently ends the client's cache write for
......@@ -163,6 +174,16 @@ export type PartialTransportData = {
export type TransportData = FullTransportData | PartialTransportData
/**
* Creates the data for a skipped segment: a null `r` marks the position as
* acknowledged by the response, with no output attached (see the note on
* TransportSegmentData). Used by producers for the segments along the path
* from the root down to the rendered subtrees.
*/
export function createSkippedSegmentData(): TransportSegmentData {
return { r: null, p: true, v: null }
}
/**
* Converts a segment's client/server-internal representation to its wire
* representation.
......
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