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

Unify full/partial navigation response types (#96439)

Introduces a new type, TransportData, to replace FlightDataPath. The new
format is the same regardless of whether the entire page is rendered by
the server or if some segments are intentionally omitted.

The type also unifies FlightRouterState and CacheNodeSeedData into a
single tree that includes both route information and RSC data.
Previously these were sent in two separate trees that were isomorphic by
convention, requiring the consumer to walk both in parallel.

These new types are intended to be transport formats only. The client
already has its own, richer data structure called RouteTree. The
transport format is converted into the client format at the network
decoding boundary.

This does not remove FlightRouterState from the codebase entirely; it's
still used both for issuing requests to the server
(Next-Router-State-Tree) and for tracking state in the browser's history
object. A future refactor may replace it for the purpose of issuing
requests, but it will likely survive as the format for tracking state in
history.

This PR does not yet update the server to produce TransportData
directly; a temporary adapter layer is used to convert from the old data
formats to the new format. This intermediate step will not land on its
own; the next PR in the stack will both update the server and delete the
temporary adapter layer.
parent 4ce4c519
......@@ -4,15 +4,15 @@ import { createHrefFromUrl } from './create-href-from-url'
import { extractPathFromFlightRouterState } from './compute-changed-path'
import type { AppRouterState } from './router-reducer-types'
import { getFlightDataPartsFromPath } from '../../flight-data-helpers'
import { transportNodeToFlightRouterState } from '../../../shared/lib/rsc-transport'
import { createInitialCacheNodeForHydration } from './ppr-navigations'
import {
convertRootFlightRouterStateToRouteTree,
resolveStaleAt,
processRuntimePrefetchStream,
writeDynamicRenderResponseIntoCache,
writePrerenderResponseIntoCache,
} from '../segment-cache/cache'
import { decodeTransportTreeIntoRouteTree } from '../segment-cache/decode-server-response'
import { FetchStrategy } from '../segment-cache/types'
import {
UnknownDynamicStaleTime,
......@@ -37,13 +37,12 @@ export function createInitialRouterState({
}: InitialRouterStateParameters): AppRouterState {
const {
c: initialCanonicalUrlParts,
f: initialFlightData,
t: initialTransportData,
q: initialRenderedSearch,
i: initialCouldBeIntercepted,
S: initialSupportsPerSegmentPrefetching,
s: initialStaleTime,
l: initialStaticStageByteLength,
h: initialHeadVaryParams,
r: initialRootVaryParams,
p: initialRuntimePrefetchStream,
d: initialDynamicStaleTimeSeconds,
......@@ -54,14 +53,12 @@ export function createInitialRouterState({
// as a URL that should be crawled.
const initialCanonicalUrl = initialCanonicalUrlParts.join('/')
const normalizedFlightData = getFlightDataPartsFromPath(initialFlightData[0])
const {
tree: initialTree,
seedData: initialSeedData,
head: initialHead,
} = normalizedFlightData
// For the SSR render, seed data should always be available (we only send back a `null` response
// in the case of a `loading` segment, pre-PPR.)
const initialHead = initialTransportData.h.r
// The initial router state tree, derived from the transport tree. Page
// segments keep their search params, which travel inside the segment
// string.
const initialTree = transportNodeToFlightRouterState(initialTransportData.t)
const canonicalUrl =
// location.href is read as the initial value for canonicalUrl in the browser
......@@ -71,24 +68,26 @@ export function createInitialRouterState({
createHrefFromUrl(location)
: initialCanonicalUrl
// Convert the initial FlightRouterState into the RouteTree type.
// Decode the initial transport tree into the RouteTree type, with the
// payload's render output embedded on each node. (discoverKnownRoute below
// stores this tree in the route cache, which strips the data on write —
// see stripDataFromRouteTree.)
// NOTE: The metadataVaryPath isn't used for anything currently because the
// head is embedded into the CacheNode tree, but eventually we'll lift it out
// and store it on the top-level state object.
//
// 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
// For statically-generated-at-build-time HTML pages, the tree 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,
// Embed the initial payload's seed data directly into the RouteTree.
// (discoverKnownRoute below stores this tree in the route cache, which
// strips the data on write — see stripDataFromRouteTree.)
initialSeedData,
const initialRouteTree = decodeTransportTreeIntoRouteTree(
initialTransportData.t,
// There's no base tree to overlay onto; the initial payload is a full
// render from the root.
null,
initialRenderedSearch as NormalizedSearch,
acc
)
......@@ -127,7 +126,7 @@ export function createInitialRouterState({
// Write the initial seed data into the segment cache so subsequent
// navigations to the initial page can serve cached segments instantly.
if (initialSeedData !== null && initialStaleTime !== undefined) {
if (initialStaleTime !== undefined) {
if (
initialStaticStageByteLength !== undefined &&
initialFlightStreamForCache != null
......@@ -150,9 +149,8 @@ export function createInitialRouterState({
writePrerenderResponseIntoCache(
now,
FetchStrategy.PPR,
staticStageResponse.f,
staticStageResponse.t,
undefined, // no build ID mismatch check for initial HTML
staticStageResponse.h,
staticStageResponse.r ?? null,
staleAt,
initialTree,
......@@ -177,9 +175,8 @@ export function createInitialRouterState({
writePrerenderResponseIntoCache(
now,
FetchStrategy.PPR,
initialFlightData,
initialTransportData,
undefined, // buildId — not applicable for initial HTML
initialHeadVaryParams,
initialRootVaryParams ?? null,
staleAt,
initialTree,
......@@ -216,7 +213,6 @@ export function createInitialRouterState({
writeDynamicRenderResponseIntoCache(
Date.now(),
FetchStrategy.PPRRuntime,
processed.flightDatas,
processed.buildId,
processed.isResponsePartial,
processed.headVaryParams,
......
......@@ -30,11 +30,8 @@ import {
} from '../app-router-headers'
import { callServer } from '../../app-call-server'
import { findSourceMapURL } from '../../app-find-source-map-url'
import {
normalizeFlightData,
prepareFlightRouterStateForRequest,
type NormalizedFlightData,
} from '../../flight-data-helpers'
import { prepareFlightRouterStateForRequest } from '../../flight-data-helpers'
import type { PartialTransportData } from '../../../shared/lib/rsc-transport'
import { setCacheBustingSearchParam } from './set-cache-busting-search-param'
import { urlToUrlWithoutFlightMarker } from '../../route-params'
import type { NormalizedSearch } from '../segment-cache/cache-key'
......@@ -79,7 +76,7 @@ export type StaticStageData<
}
type SpaFetchServerResponseResult = {
flightData: NormalizedFlightData[]
transportData: PartialTransportData | null
canonicalUrl: URL
renderedSearch: NormalizedSearch
couldBeIntercepted: boolean
......@@ -279,9 +276,10 @@ export async function fetchServerResponse(
return doMpaNavigation(res.url)
}
const normalizedFlightData = normalizeFlightData(flightResponse.f)
if (typeof normalizedFlightData === 'string') {
return doMpaNavigation(normalizedFlightData)
if (flightResponse.n !== undefined) {
// The server responded with an MPA navigation URL instead of a
// SPA payload.
return doMpaNavigation(flightResponse.n)
}
const staticStageData =
......@@ -290,7 +288,7 @@ export async function fetchServerResponse(
: null
return {
flightData: normalizedFlightData,
transportData: flightResponse.t ?? null,
canonicalUrl: canonicalUrl,
// TODO: We should be able to read this from the rewrite header, not the
// Flight response. Theoretically they should always agree, but there are
......
......@@ -23,7 +23,7 @@ import { getLastCommittedTree } from './reducers/committed-state'
import {
convertServerPatchToFullTree,
type NavigationSeed,
} from '../segment-cache/navigation'
} from '../segment-cache/decode-server-response'
import {
type RouteTree,
type RSCSegmentData,
......@@ -1800,7 +1800,7 @@ async function fetchMissingDynamicData(
const seed = convertServerPatchToFullTree(
now,
task.route,
result.flightData,
result.transportData,
result.renderedSearch,
result.dynamicStaleTime
)
......@@ -1828,9 +1828,8 @@ async function fetchMissingDynamicData(
writePrerenderResponseIntoCache(
now,
FetchStrategy.PPR,
staticStageResponse.f,
staticStageResponse.t ?? null,
buildId,
staticStageResponse.h,
staticStageResponse.r ?? null,
staleAt,
dynamicRequestTree,
......@@ -1856,7 +1855,6 @@ async function fetchMissingDynamicData(
writeDynamicRenderResponseIntoCache(
now,
FetchStrategy.PPRRuntime,
processed.flightDatas,
processed.buildId,
processed.isResponsePartial,
processed.headVaryParams,
......
......@@ -4,10 +4,8 @@ import type {
RefreshAction,
} from '../router-reducer-types'
import { ScrollBehavior } from '../router-reducer-types'
import {
convertServerPatchToFullTree,
navigateToKnownRoute,
} from '../../segment-cache/navigation'
import { navigateToKnownRoute } from '../../segment-cache/navigation'
import { convertServerPatchToFullTree } from '../../segment-cache/decode-server-response'
import { invalidateSegmentCacheEntries } from '../../segment-cache/cache'
import { hasInterceptionRouteInCurrentTree } from './has-interception-route-in-current-tree'
import { FreshnessPolicy, getCurrentNavigationLock } from '../ppr-navigations'
......
......@@ -15,8 +15,8 @@ import type { FlightRouterState } from '../../../../shared/lib/app-router-types'
import {
completeHardNavigation,
completeTraverseNavigation,
convertServerPatchToFullTree,
} from '../../segment-cache/navigation'
import { convertServerPatchToFullTree } from '../../segment-cache/decode-server-response'
import { UnknownDynamicStaleTime } from '../../segment-cache/bfcache'
export function restoreReducer(
......
......@@ -33,12 +33,9 @@ import type {
import { ScrollBehavior } from '../router-reducer-types'
import { assignLocation } from '../../../assign-location'
import { createHrefFromUrl } from '../create-href-from-url'
import type { PartialTransportData } from '../../../../shared/lib/rsc-transport'
import { hasInterceptionRouteInCurrentTree } from './has-interception-route-in-current-tree'
import {
normalizeFlightData,
prepareFlightRouterStateForRequest,
type NormalizedFlightData,
} from '../../../flight-data-helpers'
import { prepareFlightRouterStateForRequest } from '../../../flight-data-helpers'
import { getRedirectError } from '../../redirect'
import type { RedirectType } from '../../redirect-error'
import { removeBasePath } from '../../../remove-base-path'
......@@ -54,10 +51,10 @@ import { getNavigationBuildId } from '../../../navigation-build-id'
import { NEXT_NAV_DEPLOYMENT_ID_HEADER } from '../../../../lib/constants'
import {
completeHardNavigation,
convertServerPatchToFullTree,
navigateToKnownRoute,
navigate,
} from '../../segment-cache/navigation'
import { convertServerPatchToFullTree } from '../../segment-cache/decode-server-response'
import { discoverKnownRoute } from '../../segment-cache/optimistic-routes'
import type { NormalizedSearch } from '../../segment-cache/cache-key'
import {
......@@ -95,7 +92,11 @@ type FetchServerActionResult = {
redirectType: RedirectType | undefined
revalidationKind: ActionRevalidationKind
actionResult: ActionResult | undefined
actionFlightData: NormalizedFlightData[] | string | undefined
/**
* The transport data from the action response, or a URL string when the
* response handling triggered an external (MPA) redirect.
*/
actionFlightData: PartialTransportData | string | undefined
actionFlightDataRenderedSearch: NormalizedSearch | undefined
isPrerender: boolean
couldBeIntercepted: boolean
......@@ -279,10 +280,12 @@ async function fetchServerAction(
// still be processed, and the absence of flight data will cause an
// MPA navigation via completeHardNavigation().
} else {
const maybeFlightData = normalizeFlightData(response.f)
if (maybeFlightData !== '') {
actionFlightData = maybeFlightData
if (response.t !== undefined) {
actionFlightData = response.t
actionFlightDataRenderedSearch = response.q as NormalizedSearch
} else if (response.n !== undefined) {
// The server responded with an MPA navigation URL.
actionFlightData = response.n
}
}
} else {
......
import type { CacheNode, ScrollRef } from '../../../shared/lib/app-router-types'
import type { FlightRouterState } from '../../../shared/lib/app-router-types'
import type { NavigationSeed } from '../segment-cache/navigation'
import type { NavigationSeed } from '../segment-cache/decode-server-response'
import type { FetchServerResponseResult } from './fetch-server-response'
import type { FreshnessPolicy } from './ppr-navigations'
......
import type {
CacheNodeSeedData,
FlightData,
FlightDataPath,
FlightRouterState,
FlightSegmentPath,
Segment,
HeadData,
InitialRSCPayload,
} from '../shared/lib/app-router-types'
import type {
FullTransportNode,
TransportSegment,
} from '../shared/lib/rsc-transport'
import { PAGE_SEGMENT_KEY } from '../shared/lib/segment'
import type { NormalizedSearch } from './components/segment-cache/cache-key'
import {
......@@ -19,55 +19,6 @@ import {
} from './route-params'
import { createHrefFromUrl } from './components/router-reducer/create-href-from-url'
export type NormalizedFlightData = {
/**
* The full `FlightSegmentPath` inclusive of the final `Segment`
*/
segmentPath: FlightSegmentPath
/**
* The `FlightSegmentPath` exclusive of the final `Segment`
*/
pathToSegment: FlightSegmentPath
segment: Segment
tree: FlightRouterState
seedData: CacheNodeSeedData | null
head: HeadData
isHeadPartial: boolean
isRootRender: boolean
}
// TODO: We should only have to export `normalizeFlightData`, however because the initial flight data
// that gets passed to `createInitialRouterState` doesn't conform to the `FlightDataPath` type (it's missing the root segment)
// we're currently exporting it so we can use it directly. This should be fixed as part of the unification of
// the different ways we express `FlightSegmentPath`.
export function getFlightDataPartsFromPath(
flightDataPath: FlightDataPath
): NormalizedFlightData {
// Pick the last 4 items from the `FlightDataPath` to get the [tree, seedData, viewport, isHeadPartial].
const flightDataPathLength = 4
// tree, seedData, and head are *always* the last three items in the `FlightDataPath`.
const [tree, seedData, head, isHeadPartial] =
flightDataPath.slice(-flightDataPathLength)
// The `FlightSegmentPath` is everything except the last three items. For a root render, it won't be present.
const segmentPath = flightDataPath.slice(0, -flightDataPathLength)
return {
// TODO: Unify these two segment path helpers. We are inconsistently pushing an empty segment ("")
// to the start of the segment path in some places which makes it hard to use solely the segment path.
// Look for "// TODO-APP: remove ''" in the codebase.
pathToSegment: segmentPath.slice(0, -1),
segmentPath,
// if the `FlightDataPath` corresponds with the root, there'll be no segment path,
// in which case we default to ''.
segment: segmentPath[segmentPath.length - 1] ?? '',
tree,
seedData,
head,
isHeadPartial,
isRootRender: flightDataPath.length === flightDataPathLength,
}
}
export function createInitialRSCPayloadFromFallbackPrerender(
response: Response,
fallbackInitialRSCPayload: InitialRSCPayload
......@@ -92,36 +43,28 @@ export function createInitialRSCPayloadFromFallbackPrerender(
// "export" mode, where we currently don't assume that custom response
// headers are present.
// Patch the Flight data sent by the server with the correct params parsed
// from the URL + response object.
// Patch the transport tree sent by the server with the correct params
// parsed from the URL + response object.
const renderedPathname = getRenderedPathname(response)
const renderedSearch = getRenderedSearch(response)
const canonicalUrl = createHrefFromUrl(new URL(location.href))
const originalFlightDataPath = fallbackInitialRSCPayload.f[0]
const originalFlightRouterState = originalFlightDataPath[0]
const fallbackTransportData = fallbackInitialRSCPayload.t
const payload: InitialRSCPayload = {
c: canonicalUrl.split('/'),
q: renderedSearch,
i: fallbackInitialRSCPayload.i,
f: [
[
fillInFallbackFlightRouterState(
originalFlightRouterState,
renderedPathname,
renderedSearch as NormalizedSearch
),
originalFlightDataPath[1],
originalFlightDataPath[2],
// isHeadPartial. Previously this incorrectly passed the head itself
// (index 2), which is truthy, so the head was always treated
// as partial.
originalFlightDataPath[3],
],
],
t: {
t: fillInFallbackTransportTree(
fallbackTransportData.t,
renderedPathname.split('/').filter((part) => part !== ''),
0,
renderedSearch as NormalizedSearch
),
h: fallbackTransportData.h,
},
m: fallbackInitialRSCPayload.m,
G: fallbackInitialRSCPayload.G,
S: fallbackInitialRSCPayload.S,
h: fallbackInitialRSCPayload.h,
}
if (fallbackInitialRSCPayload.b) {
payload.b = fallbackInitialRSCPayload.b
......@@ -129,44 +72,35 @@ export function createInitialRSCPayloadFromFallbackPrerender(
return payload
}
function fillInFallbackFlightRouterState(
flightRouterState: FlightRouterState,
renderedPathname: string,
renderedSearch: NormalizedSearch
): FlightRouterState {
const pathnameParts = renderedPathname.split('/').filter((p) => p !== '')
const index = 0
return fillInFallbackFlightRouterStateImpl(
flightRouterState,
renderedSearch,
pathnameParts,
index
)
}
function fillInFallbackFlightRouterStateImpl(
flightRouterState: FlightRouterState,
renderedSearch: NormalizedSearch,
/**
* A fallback prerender is rendered without concrete param values. Fill them
* in by parsing the rendered pathname, so the hydrated tree has the same
* identity a direct render of this URL would have.
*/
function fillInFallbackTransportTree(
node: FullTransportNode,
pathnameParts: Array<string>,
pathnamePartsIndex: number
): FlightRouterState {
const originalSegment = flightRouterState[0]
let newSegment: Segment
pathnamePartsIndex: number,
renderedSearch: NormalizedSearch
): FullTransportNode {
const originalSegment = node.s
let newSegment: TransportSegment
let doesAppearInURL: boolean
if (typeof originalSegment === 'string') {
newSegment = originalSegment
doesAppearInURL = doesStaticSegmentAppearInURL(originalSegment)
} else {
const paramName = originalSegment[0]
const paramType = originalSegment[2]
const staticSiblings = originalSegment[3]
const paramValue = parseDynamicParamFromURLPart(
paramType,
originalSegment.t,
pathnameParts,
pathnamePartsIndex
)
const cacheKey = getCacheKeyForDynamicParam(paramValue, renderedSearch)
newSegment = [paramName, cacheKey, paramType, staticSiblings]
newSegment = {
n: originalSegment.n,
t: originalSegment.t,
k: getCacheKeyForDynamicParam(paramValue, renderedSearch),
s: originalSegment.s,
}
doesAppearInURL = true
}
......@@ -176,26 +110,34 @@ function fillInFallbackFlightRouterStateImpl(
? pathnamePartsIndex + 1
: pathnamePartsIndex
const children = flightRouterState[1]
const newChildren: { [key: string]: FlightRouterState } = {}
for (let key in children) {
const childFlightRouterState = children[key]
newChildren[key] = fillInFallbackFlightRouterStateImpl(
childFlightRouterState,
renderedSearch,
pathnameParts,
childPathnamePartsIndex
)
const children = node.c
let newChildren: Map<string, FullTransportNode> | undefined
if (children !== undefined) {
newChildren = new Map()
for (const [parallelRouteKey, childNode] of children) {
newChildren.set(
parallelRouteKey,
fillInFallbackTransportTree(
childNode,
pathnameParts,
childPathnamePartsIndex,
renderedSearch
)
)
}
}
const newState: FlightRouterState = [
newSegment,
newChildren,
null,
flightRouterState[3],
flightRouterState[4],
]
return newState
const newNode: FullTransportNode = {
s: newSegment,
d: node.d,
}
if (node.h !== undefined) {
newNode.h = node.h
}
if (newChildren !== undefined) {
newNode.c = newChildren
}
return newNode
}
export function getNextFlightSegmentPath(
......@@ -206,20 +148,6 @@ export function getNextFlightSegmentPath(
return flightSegmentPath.slice(2)
}
export function normalizeFlightData(
flightData: FlightData
): NormalizedFlightData[] | string {
// FlightData can be a string when the server didn't respond with a proper flight response,
// or when a redirect happens, to signal to the client that it needs to perform an MPA navigation.
if (typeof flightData === 'string') {
return flightData
}
return flightData.map((flightDataPath) =>
getFlightDataPartsFromPath(flightDataPath)
)
}
/**
* This function is used to prepare the flight router state for the request.
* It removes markers that are not needed by the server, and are purely used
......
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 {
ActionResult,
......@@ -8,9 +13,8 @@ import type {
CacheNodeSeedData,
RSCPayload,
NavigationFlightResponse,
FlightData,
ActionFlightResponse,
InitialRSCPayload,
FlightDataPath,
PrefetchHints,
} from '../../shared/lib/app-router-types'
import { PrefetchHint } from '../../shared/lib/app-router-types'
......@@ -684,14 +688,11 @@ async function generateDynamicRSCPayload(
runtimePrefetchStream?: ReadableStream<Uint8Array>
}
): Promise<RSCPayload> {
// Flight data that is going to be passed to the browser.
// Currently a single item array but in the future multiple patches might be combined in a single request.
// We initialize `flightData` to an empty string because the client router knows how to tolerate
// it (treating it as an MPA navigation). The only time this function wouldn't generate flight data
// is for server actions, if the server action handler instructs this function to skip it. When the server
// action reducer sees a falsy value, it'll simply resolve the action with no data.
let flightData: FlightData = ''
// Transport data that is going to be passed to the browser. Undefined when
// the response renders nothing: server actions, if the server action
// handler instructs this function to skip rendering. When the server action
// reducer sees an absent tree, it resolves the action with no data.
let transportData: PartialTransportData | undefined = undefined
const {
componentMod: {
......@@ -755,7 +756,7 @@ async function generateDynamicRSCPayload(
})
)
flightData = (
const flightDataPaths = (
needsFullTree
? await createFullTreeFlightDataForNavigation({
ctx,
......@@ -782,6 +783,13 @@ async function generateDynamicRSCPayload(
hintTree: ctx.renderOpts.prefetchHints?.[ctx.pagePath] ?? null,
})
).map((path) => path.slice(1)) // remove the '' (root) segment
if (flightDataPaths.length > 0) {
transportData = convertFlightDataPathsToPartialTransportData(
flightDataPaths,
getMetadataVaryParamsAccumulator()
)
}
}
// In dev, the Vary header may not reliably reflect whether a route can
......@@ -796,19 +804,21 @@ async function generateDynamicRSCPayload(
// We can rely on this because `ActionResult` will always be a promise, even if
// the result is falsey.
if (options?.actionResult) {
return maybeAppendBuildIdToRSCPayload(ctx, {
const actionResponse: ActionFlightResponse = {
a: options.actionResult,
f: flightData,
q: getRenderedSearch(query),
i: !!couldBeIntercepted,
})
}
if (transportData !== undefined) {
actionResponse.t = transportData
}
return maybeAppendBuildIdToRSCPayload(ctx, actionResponse)
}
// Otherwise, it's a regular RSC response.
const baseResponse: NavigationFlightResponse = maybeAppendBuildIdToRSCPayload(
ctx,
{
f: flightData,
q: getRenderedSearch(query),
i: !!couldBeIntercepted,
// Tells the client whether this route supports per-segment prefetching.
......@@ -816,10 +826,12 @@ async function generateDynamicRSCPayload(
// static pages do, because their per-segment prefetch responses are
// generated during static generation (build or ISR).
S: ctx.renderCapabilities.supportsPerSegmentPrefetching,
h: getMetadataVaryParamsAccumulator(),
r: getRootParamsVaryParamsAccumulator() ?? undefined,
}
)
if (transportData !== undefined) {
baseResponse.t = transportData
}
if (options?.staleTimeIterable !== undefined) {
baseResponse.s = options.staleTimeIterable
......@@ -2239,14 +2251,13 @@ async function getRSCPayload(
c: prepareInitialCanonicalUrl(url),
q: getRenderedSearch(query),
i: !!couldBeIntercepted,
f: [
[
initialTree,
seedData,
initialHead,
isPossiblyPartialHead,
] as FlightDataPath,
],
t: convertInitialFlightDataToFullTransportData(
initialTree,
seedData,
initialHead,
isPossiblyPartialHead,
getMetadataVaryParamsAccumulator()
),
m: missingSlots,
G: [GlobalError, globalErrorStyles],
// Tells the client whether this route supports per-segment prefetching.
......@@ -2254,7 +2265,6 @@ async function getRSCPayload(
// static pages do, because their per-segment prefetch responses are
// generated during static generation (build or ISR).
S: ctx.renderCapabilities.supportsPerSegmentPrefetching,
h: getMetadataVaryParamsAccumulator(),
r: getRootParamsVaryParamsAccumulator() ?? undefined,
s: staleTimeIterable,
a: shellByteLengthPromise,
......@@ -2392,21 +2402,19 @@ async function getErrorRSCPayload(
q: getRenderedSearch(query),
m: undefined,
i: false,
f: [
[
initialTree,
seedData,
initialHead,
isPossiblyPartialHead,
] as FlightDataPath,
],
t: convertInitialFlightDataToFullTransportData(
initialTree,
seedData,
initialHead,
isPossiblyPartialHead,
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
// static pages do, because their per-segment prefetch responses are
// generated during static generation (build or ISR).
S: ctx.renderCapabilities.supportsPerSegmentPrefetching,
h: getMetadataVaryParamsAccumulator(),
r: getRootParamsVaryParamsAccumulator() ?? undefined,
} satisfies InitialRSCPayload)
}
......
import type {
CacheNodeSeedData,
FlightRouterState,
HeadData,
InitialRSCPayload,
Segment,
} from '../../../shared/lib/app-router-types'
import type { VaryParamsIterable } from '../../../shared/lib/segment-cache/vary-params-decoding'
import { InvariantError } from '../../../shared/lib/invariant-error'
import { convertInitialFlightDataToFullTransportData } from '../transport-adapter'
import {
transportNodeToFlightRouterState,
transportSegmentToSegment,
type FullTransportNode,
type TransportSegmentData,
} from '../../../shared/lib/rsc-transport'
import { RenderStage } from '../staged-rendering'
import { getServerModuleMap } from '../manifests-singleton'
import { runInSequentialTasks } from '../app-render-render-utils'
......@@ -108,62 +114,34 @@ export type RouteTree = {
function traverseRootSeedDataSegments(
initialRSCPayload: InitialRSCPayload,
processSegment: (
segmentPath: SegmentPath,
seedData: CacheNodeSeedData
) => void
processSegment: (segmentPath: SegmentPath, data: TransportSegmentData) => void
) {
const { flightRouterState, seedData } =
getRootDataFromPayload(initialRSCPayload)
const [rootSegment] = flightRouterState
const rootPath = stringifySegment(rootSegment)
return traverseCacheNodeSegments(
rootPath,
flightRouterState,
seedData,
processSegment
)
const rootNode = initialRSCPayload.t.t
const rootPath = stringifySegment(transportSegmentToSegment(rootNode.s))
return traverseTransportNodeSegments(rootPath, rootNode, processSegment)
}
function traverseCacheNodeSegments(
function traverseTransportNodeSegments(
path: SegmentPath,
route: FlightRouterState,
seedData: CacheNodeSeedData,
processSegment: (
segmentPath: SegmentPath,
seedData: CacheNodeSeedData
) => void
node: FullTransportNode,
processSegment: (segmentPath: SegmentPath, data: TransportSegmentData) => void
): void {
processSegment(path, seedData)
const [_segment, childRoutes] = route
const [_node, parallelRoutesData, _loading, _isPartial] = seedData
processSegment(path, node.d)
for (const parallelRouteKey in childRoutes) {
const childSeedData = parallelRoutesData[parallelRouteKey]
if (!childSeedData) {
throw new InvariantError(
`Got unexpected empty seed data during instant validation`
)
}
const childRoute = childRoutes[parallelRouteKey]
const children = node.c
if (children === undefined) {
return
}
for (const [parallelRouteKey, childNode] of children) {
// NOTE: if this is a __PAGE__ segment, it might have search params appended.
// Whoever reads from the cache needs to append them as well.
const [childSegment] = childRoute
const childPath = createChildSegmentPath(
path,
parallelRouteKey,
childSegment
transportSegmentToSegment(childNode.s)
)
traverseCacheNodeSegments(
childPath,
childRoute,
childSeedData,
processSegment
)
traverseTransportNodeSegments(childPath, childNode, processSegment)
}
}
......@@ -354,7 +332,7 @@ async function collectSegmentDataForStage(
// We have to preserve the stage information for each of them,
// so that we can later render each segment in any stage we need.
const { head } = getRootDataFromPayload(payload)
const head = payload.t.h.r
const segments = new Map<SegmentPath, SegmentData>()
traverseRootSeedDataSegments(payload, (segmentPath, seedData) => {
......@@ -664,29 +642,6 @@ export async function createCombinedPayloadStream(
}
}
function getRootDataFromPayload(initialRSCPayload: InitialRSCPayload) {
// FlightDataPath is an unsound type, hence the additional checks. The
// valid shapes are a single root path with no segment prefix: 4 elements
// ([tree, seedData, head, isHeadPartial], per getRSCPayload) or 3 when
// reconstructed without the isHeadPartial flag (see the payload literals
// in this module).
const flightDataPaths = initialRSCPayload.f
if (
flightDataPaths.length !== 1 ||
(flightDataPaths[0].length !== 3 && flightDataPaths[0].length !== 4)
) {
throw new InvariantError(
'InitialRSCPayload does not match the expected shape during instant validation.'
)
}
const flightRouterState: FlightRouterState = flightDataPaths[0][0]
const seedData: CacheNodeSeedData = flightDataPaths[0][1]
// TODO: handle head
const head: HeadData = flightDataPaths[0][2]
return { flightRouterState, seedData, head }
}
async function createValidationHead(
cache: SegmentCache,
releaseSignal: AbortSignal,
......@@ -775,12 +730,11 @@ type SegmentData = {
varyParams: VaryParamsIterable | null
}
function createSegmentData(seedData: CacheNodeSeedData): SegmentData {
const [node, _parallelRoutesData, _unused, isPartial, varyParams] = seedData
function createSegmentData(data: TransportSegmentData): SegmentData {
return {
node,
isPartial,
varyParams,
node: data.r,
isPartial: data.p,
varyParams: data.v,
}
}
type CacheNodeSeedDataSlots = CacheNodeSeedData[1]
......@@ -1454,7 +1408,12 @@ export async function createCombinedPayloadAtDepth(
// that occur above any fork (no slot marker in the component stack).
slotStacks[0] = createInstantStack
const { flightRouterState } = getRootDataFromPayload(initialRSCPayload)
// Identity + hints of the original payload's tree; zipped with the rebuilt
// seed data below. TODO: build the transport tree natively instead (this
// dies together with the transport adapter).
const flightRouterState = transportNodeToFlightRouterState(
initialRSCPayload.t.t
)
let headStage: PrefetchedSegmentStage
switch (prefetchKind) {
......@@ -1500,7 +1459,13 @@ export async function createCombinedPayloadAtDepth(
const payload: InitialRSCPayload = {
...initialRSCPayload,
f: [[flightRouterState, seedData, head]],
t: convertInitialFlightDataToFullTransportData(
flightRouterState,
seedData,
head,
initialRSCPayload.t.h.p,
initialRSCPayload.t.h.v
),
}
return {
......
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
}
......@@ -12,6 +12,7 @@ export type LoadingModuleData =
| null
import type { VaryParamsIterable } from './segment-cache/vary-params-decoding'
import type { FullTransportData, PartialTransportData } from './rsc-transport'
/** viewport metadata node */
export type HeadData = React.ReactNode
......@@ -455,19 +456,14 @@ export type InitialRSCPayload = {
q: string
/** couldBeIntercepted */
i: boolean
/** initialFlightData */
f: FlightDataPath[]
/** initial transport data — the tree + head for hydration */
t: FullTransportData
/** missingSlots */
m: Set<string> | undefined
/** GlobalError */
G: [React.ComponentType<any>, React.ReactNode | undefined]
/** supportsPerSegmentPrefetching */
S: boolean
/**
* headVaryParams - vary params for the head (metadata) of the response.
* Does not include root params (see `r`).
*/
h: VaryParamsIterable | null
/**
* rootVaryParams - the root params accessed anywhere in the response, emitted
* once. The client unions these into the head and every segment's vary
......@@ -532,8 +528,18 @@ export type InitialRSCPayload = {
export type NavigationFlightResponse = {
/** buildId, can be empty if the x-nextjs-build-id header is set */
b?: string
/** flightData */
f: FlightData
/**
* transport data — present iff the response carries a SPA payload.
* Absent when the response renders nothing (see `n` for MPA navigations).
*/
t?: PartialTransportData
/**
* MPA navigation URL — present iff the client should hard-navigate to
* this URL instead of applying a SPA payload. Reserved: no server path
* emits it today (hard navigations are signaled by non-RSC content types
* or a build-id mismatch), but the client honors it.
*/
n?: string
/** supportsPerSegmentPrefetching */
S: boolean
/** renderedSearch */
......@@ -556,8 +562,6 @@ export type NavigationFlightResponse = {
* where we have a proper session shell.
* */
u?: Promise<boolean>
/** headVaryParams. Does not include root params (see `r`). */
h: VaryParamsIterable | null
/**
* rootVaryParams - the root params accessed anywhere in the response, emitted
* once. The client unions these into the head and every segment's vary
......@@ -588,14 +592,23 @@ export type NavigationFlightResponse = {
_revealAfter?: Promise<void>
}
// Response from `createFromFetch` for server actions. Action's flight data can be null
// Response from `createFromFetch` for server actions.
export type ActionFlightResponse = {
/** actionResult */
a: ActionResult
/** buildId, can be empty if the x-nextjs-build-id header is set */
b?: string
/** flightData */
f: FlightData
/**
* transport data — present iff the action response re-rendered the page.
* Absent when the action rendered nothing (see `n` for MPA navigations).
*/
t?: PartialTransportData
/**
* MPA navigation URL — present iff the client should hard-navigate to
* this URL instead of applying a SPA payload. Reserved: no server path
* emits it today, but the client honors it.
*/
n?: string
/** renderedSearch */
q: string
/** couldBeIntercepted */
......
/**
* The transport format for RSC responses.
*
* Every type in this module is prefixed with `Transport` to distinguish the
* wire format from client-local types (`Segment`, `RouteTree`, `CacheNode`,
* `FlightRouterState`). Client code converts out of Transport types at the
* decode boundary and never stores them.
*
* A response carries a single tree, anchored at the root segment, where each
* node has both its identity and (optionally) its render output. Partial
* responses are expressed per node: the convention across the format is that
* absence means "nothing here" — an omitted `d` means the segment was not
* rendered as part of the response, an omitted slot key means the response
* carries no information about that slot.
*/
import type React from 'react'
import type {
DynamicParamTypesShort,
FlightRouterState,
Segment,
} from './app-router-types'
import type { VaryParamsIterable } from './segment-cache/vary-params-decoding'
/**
* Segment identity on the wire. A string for static segments; an object for
* dynamic (parameterized) segments.
*
* TODO: Page segments currently smuggle search params inside the string
* (`__PAGE__?{...}`, see addSearchParamsIfPageSegment). This convention is
* carried over as-is for now. Consider giving search params a dedicated
* field (or removing them from the response entirely, since the client
* already knows the rendered search from the response-level `q`).
*/
export type TransportSegment = string | TransportDynamicSegment
export type TransportDynamicSegment = {
/** name — the param name, e.g. 'id' for [id] */
n: string
/** type — dynamic param type */
t: DynamicParamTypesShort
/**
* key — the param value / cache key. null when the client is expected to
* parse the value from the URL itself, which keeps the response cacheable
* across param values.
*/
k: string | null
/** siblings — static sibling segments at this URL level; null = unknown */
s: readonly string[] | null
}
/**
* Render output for a single segment. Grouped into one object so a node's
* "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).
*/
export type TransportSegmentData = {
/** rsc — the React node for this segment; null = covered but 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).
*/
v: VaryParamsIterable | null
}
/**
* Structure of a segment node, independent of whether render output
* is attached. Shared by both response variants.
*/
type TransportNodeShape = {
/** segment — identity */
s: TransportSegment
/** hints — PrefetchHint bitmask; omitted when zero or unknown */
h?: number
}
/**
* 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
* 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.
*/
export type FullTransportNode = TransportNodeShape & {
/** data — always present in a full tree */
d: TransportSegmentData
/**
* children — parallel routes; omitted for leaf segments. A Map rather
* than a plain object because slot names are app-defined; with a plain
* object, every distinct combination of slot names creates a different
* hidden class, making keyed access megamorphic.
*/
c?: Map<string, FullTransportNode>
}
/**
* A node in a PARTIAL response tree: produced by navigations, refreshes, and
* actions — anywhere the server diffs against client state or renders a
* subset of the route.
*
* The client treats the response as an overlay over its current tree:
*
* - 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).
* - `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
* (`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
* 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
* its subtree (see writeSeedDataIntoCache), so "skip a middle segment but
* render below it" is not expressible yet. Extend the decode/write semantics
* when a producer needs that.
*/
export type PartialTransportNode = TransportNodeShape & {
/** data — omitted when this segment was not rendered in this response */
d?: TransportSegmentData
/** children — omitted field or key = no information about those slots */
c?: Map<string, PartialTransportNode>
}
/**
* Shared type for code that walks either variant. Note: FullTransportNode is
* structurally assignable to PartialTransportNode, so this union collapses
* to PartialTransportNode for the type checker; the union spelling
* documents intent.
*/
export type TransportNode = FullTransportNode | PartialTransportNode
/**
* The tree + head bundle of a response.
*/
export type FullTransportData = {
/** tree */
t: FullTransportNode
/** head — always present and complete in a full response */
h: TransportSegmentData
}
export type PartialTransportData = {
t: PartialTransportNode
/** omitted = this response carries no head (e.g. router-state-only responses) */
h?: TransportSegmentData
}
export type TransportData = FullTransportData | PartialTransportData
/**
* Converts a segment's client/server-internal representation to its wire
* representation.
*/
export function segmentToTransportSegment(segment: Segment): TransportSegment {
if (typeof segment === 'string') {
return segment
}
return {
n: segment[0],
t: segment[2],
k: segment[1],
s: segment[3],
}
}
/**
* Converts a segment's wire representation to the client/server-internal
* `Segment` type.
*/
export function transportSegmentToSegment(
transportSegment: TransportSegment
): Segment {
if (typeof transportSegment === 'string') {
return transportSegment
}
return [
transportSegment.n,
// TODO: `k` may be null when the client is expected to parse the param
// value from the URL. Navigation responses always include the key today;
// this becomes relevant when per-segment prefetch responses converge on
// this format.
transportSegment.k ?? '',
transportSegment.t,
transportSegment.s,
]
}
/**
* Derives a FlightRouterState from a transport tree. Used where the client
* needs a router-state representation of a full response (e.g. the initial
* hydration payload). Render output (`d`) is not carried over; page segments
* keep their search params, which travel inside the segment string.
*/
export function transportNodeToFlightRouterState(
node: TransportNode
): FlightRouterState {
const parallelRoutes: Record<string, FlightRouterState> = {}
const children = node.c
if (children !== undefined) {
for (const [parallelRouteKey, childNode] of children) {
parallelRoutes[parallelRouteKey] =
transportNodeToFlightRouterState(childNode)
}
}
const flightRouterState: FlightRouterState = [
transportSegmentToSegment(node.s),
parallelRoutes,
]
if (node.h !== undefined) {
flightRouterState[4] = node.h
}
return flightRouterState
}
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