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

Respond to App Shell prefetches on the server (#93998)

Introduces a new prefetch request type — the App Shell — and the
server-side handler that renders it. With this PR, a client (or a test
harness) can issue a request with `NEXT_ROUTER_PREFETCH_HEADER: '3'` and
receive the param-independent shell of a route: param- and
searchParam-bearing segments suspend, leaving everything that doesn't
depend on them intact.

The App Shell render is a subtype of the existing runtime prerender,
distinguished by a single bit on the prerender store. When that bit is
set, `await params` and `await searchParams` both hang forever, so any
segment that depends on either suspends to its nearest fallback. The
"shell" of the route is whatever renders above those suspense boundaries
— layouts, cookie-derived UI, and other request-context-derived content.

Static shell prefetches are not covered by these changes; those will be
addressed by a future PR and use a slightly different strategy. (Instead
of creating a new response type, the existing static prefetch response
will be updated to support extraction of the shell via "rewinding",
similar to what we do for cached navigations.)

No client-side changes yet, only the server parts.
<!-- NEXT_JS_LLM_PR -->
parent 9741cb57
...@@ -370,6 +370,12 @@ interface ParsedRequestHeaders { ...@@ -370,6 +370,12 @@ interface ParsedRequestHeaders {
readonly flightRouterState: FlightRouterState | undefined readonly flightRouterState: FlightRouterState | undefined
readonly isPrefetchRequest: boolean readonly isPrefetchRequest: boolean
readonly isRuntimePrefetchRequest: boolean readonly isRuntimePrefetchRequest: boolean
/**
* App Shell prefetch: a runtime prefetch that the server renders with
* params omitted (any `await params` hangs forever). Produces the
* param-independent shell of the route. Implies isRuntimePrefetchRequest.
*/
readonly isAppShellPrefetchRequest: boolean
readonly isRouteTreePrefetchRequest: boolean readonly isRouteTreePrefetchRequest: boolean
readonly isHmrRefresh: boolean readonly isHmrRefresh: boolean
readonly isRSCRequest: boolean readonly isRSCRequest: boolean
...@@ -387,7 +393,12 @@ function parseRequestHeaders( ...@@ -387,7 +393,12 @@ function parseRequestHeaders(
// (TODO: this is confusing, we should refactor this to express this better) // (TODO: this is confusing, we should refactor this to express this better)
const isPrefetchRequest = headers[NEXT_ROUTER_PREFETCH_HEADER] === '1' const isPrefetchRequest = headers[NEXT_ROUTER_PREFETCH_HEADER] === '1'
const isRuntimePrefetchRequest = headers[NEXT_ROUTER_PREFETCH_HEADER] === '2' const isAppShellPrefetchRequest = headers[NEXT_ROUTER_PREFETCH_HEADER] === '3'
// App Shell prefetches are a subtype of runtime prefetch — same code path,
// with `forceOmitParams` set on the prerender store.
const isRuntimePrefetchRequest =
headers[NEXT_ROUTER_PREFETCH_HEADER] === '2' || isAppShellPrefetchRequest
const isHmrRefresh = headers[NEXT_HMR_REFRESH_HEADER] !== undefined const isHmrRefresh = headers[NEXT_HMR_REFRESH_HEADER] !== undefined
...@@ -440,6 +451,7 @@ function parseRequestHeaders( ...@@ -440,6 +451,7 @@ function parseRequestHeaders(
flightRouterState, flightRouterState,
isPrefetchRequest, isPrefetchRequest,
isRuntimePrefetchRequest, isRuntimePrefetchRequest,
isAppShellPrefetchRequest,
isRouteTreePrefetchRequest, isRouteTreePrefetchRequest,
isHmrRefresh, isHmrRefresh,
isRSCRequest, isRSCRequest,
...@@ -1276,7 +1288,8 @@ async function spawnRuntimePrefetchWithFilledCaches( ...@@ -1276,7 +1288,8 @@ async function spawnRuntimePrefetchWithFilledCaches(
requestStore.cookies, requestStore.cookies,
requestStore.draftMode, requestStore.draftMode,
onError, onError,
staleTimeIterable staleTimeIterable,
false // forceOmitParams — server-initiated background prefetch, not a shell request
) )
await result.prelude.pipeTo(writable) await result.prelude.pipeTo(writable)
...@@ -1663,7 +1676,8 @@ async function generateDynamicFlightRenderResultWithStagesInDev( ...@@ -1663,7 +1676,8 @@ async function generateDynamicFlightRenderResultWithStagesInDev(
async function generateRuntimePrefetchResult( async function generateRuntimePrefetchResult(
req: BaseNextRequest, req: BaseNextRequest,
ctx: AppRenderContext, ctx: AppRenderContext,
requestStore: RequestStore requestStore: RequestStore,
forceOmitParams: boolean
): Promise<RenderResult> { ): Promise<RenderResult> {
const { workStore, renderOpts } = ctx const { workStore, renderOpts } = ctx
const { isBuildTimePrerendering = false, onInstrumentationRequestError } = const { isBuildTimePrerendering = false, onInstrumentationRequestError } =
...@@ -1713,7 +1727,8 @@ async function generateRuntimePrefetchResult( ...@@ -1713,7 +1727,8 @@ async function generateRuntimePrefetchResult(
rootParams, rootParams,
requestStore.headers, requestStore.headers,
requestStore.cookies, requestStore.cookies,
requestStore.draftMode requestStore.draftMode,
forceOmitParams
) )
const response = await finalRuntimeServerPrerender( const response = await finalRuntimeServerPrerender(
...@@ -1726,7 +1741,8 @@ async function generateRuntimePrefetchResult( ...@@ -1726,7 +1741,8 @@ async function generateRuntimePrefetchResult(
requestStore.cookies, requestStore.cookies,
requestStore.draftMode, requestStore.draftMode,
onError, onError,
staleTimeIterable staleTimeIterable,
forceOmitParams
) )
applyMetadataFromPrerenderResult(response, metadata, workStore) applyMetadataFromPrerenderResult(response, metadata, workStore)
...@@ -1743,7 +1759,8 @@ async function prospectiveRuntimeServerPrerender( ...@@ -1743,7 +1759,8 @@ async function prospectiveRuntimeServerPrerender(
rootParams: Params, rootParams: Params,
headers: PrerenderStoreModernRuntime['headers'], headers: PrerenderStoreModernRuntime['headers'],
cookies: PrerenderStoreModernRuntime['cookies'], cookies: PrerenderStoreModernRuntime['cookies'],
draftMode: PrerenderStoreModernRuntime['draftMode'] draftMode: PrerenderStoreModernRuntime['draftMode'],
forceOmitParams: boolean
) { ) {
const { implicitTags, renderOpts, workStore } = ctx const { implicitTags, renderOpts, workStore } = ctx
const { ComponentMod } = renderOpts const { ComponentMod } = renderOpts
...@@ -1793,6 +1810,7 @@ async function prospectiveRuntimeServerPrerender( ...@@ -1793,6 +1810,7 @@ async function prospectiveRuntimeServerPrerender(
headers, headers,
cookies, cookies,
draftMode, draftMode,
forceOmitParams,
} }
const { clientModules } = getClientReferenceManifest() const { clientModules } = getClientReferenceManifest()
...@@ -1908,7 +1926,8 @@ async function finalRuntimeServerPrerender( ...@@ -1908,7 +1926,8 @@ async function finalRuntimeServerPrerender(
cookies: PrerenderStoreModernRuntime['cookies'], cookies: PrerenderStoreModernRuntime['cookies'],
draftMode: PrerenderStoreModernRuntime['draftMode'], draftMode: PrerenderStoreModernRuntime['draftMode'],
onError: (err: unknown) => string | undefined, onError: (err: unknown) => string | undefined,
staleTimeIterable: StaleTimeIterable staleTimeIterable: StaleTimeIterable,
forceOmitParams: boolean
) { ) {
const { implicitTags, renderOpts } = ctx const { implicitTags, renderOpts } = ctx
const { ComponentMod, experimental, isDebugDynamicAccesses } = renderOpts const { ComponentMod, experimental, isDebugDynamicAccesses } = renderOpts
...@@ -1955,6 +1974,7 @@ async function finalRuntimeServerPrerender( ...@@ -1955,6 +1974,7 @@ async function finalRuntimeServerPrerender(
headers, headers,
cookies, cookies,
draftMode, draftMode,
forceOmitParams,
} }
trackStaleTime(finalServerPrerenderStore, staleTimeIterable, selectStaleTime) trackStaleTime(finalServerPrerenderStore, staleTimeIterable, selectStaleTime)
...@@ -2731,6 +2751,7 @@ async function renderToHTMLOrFlightImpl( ...@@ -2731,6 +2751,7 @@ async function renderToHTMLOrFlightImpl(
flightRouterState, flightRouterState,
isPrefetchRequest, isPrefetchRequest,
isRuntimePrefetchRequest, isRuntimePrefetchRequest,
isAppShellPrefetchRequest,
isRSCRequest, isRSCRequest,
isHmrRefresh, isHmrRefresh,
nonce, nonce,
...@@ -2957,7 +2978,12 @@ async function renderToHTMLOrFlightImpl( ...@@ -2957,7 +2978,12 @@ async function renderToHTMLOrFlightImpl(
if (isRSCRequest) { if (isRSCRequest) {
if (isRuntimePrefetchRequest) { if (isRuntimePrefetchRequest) {
// MARK: RSC runtimePrefetch // MARK: RSC runtimePrefetch
return generateRuntimePrefetchResult(req, ctx, requestStore) return generateRuntimePrefetchResult(
req,
ctx,
requestStore,
isAppShellPrefetchRequest
)
} else { } else {
if ( if (
process.env.__NEXT_DEV_SERVER && process.env.__NEXT_DEV_SERVER &&
......
...@@ -193,6 +193,14 @@ export interface PrerenderStoreModernRuntime ...@@ -193,6 +193,14 @@ export interface PrerenderStoreModernRuntime
readonly headers: RequestStore['headers'] readonly headers: RequestStore['headers']
readonly cookies: RequestStore['cookies'] readonly cookies: RequestStore['cookies']
readonly draftMode: RequestStore['draftMode'] readonly draftMode: RequestStore['draftMode']
/**
* When true, `await params` and `await searchParams` both return hanging
* promises — segments that depend on either suspend, producing the App
* Shell of the route. Set by an App Shell prefetch request
* (NEXT_ROUTER_PREFETCH_HEADER === '3').
*/
readonly forceOmitParams: boolean
} }
export interface RevalidateStore { export interface RevalidateStore {
......
...@@ -2071,8 +2071,10 @@ export default abstract class Server< ...@@ -2071,8 +2071,10 @@ export default abstract class Server<
const prefetchHeaderValue = headers[NEXT_ROUTER_PREFETCH_HEADER] const prefetchHeaderValue = headers[NEXT_ROUTER_PREFETCH_HEADER]
const routerPrefetch = const routerPrefetch =
prefetchHeaderValue !== undefined prefetchHeaderValue !== undefined
? // We only recognize '1' and '2'. Strip all other values here. ? // We only recognize '1', '2', and '3'. Strip all other values here.
prefetchHeaderValue === '1' || prefetchHeaderValue === '2' prefetchHeaderValue === '1' ||
prefetchHeaderValue === '2' ||
prefetchHeaderValue === '3'
? prefetchHeaderValue ? prefetchHeaderValue
: undefined : undefined
: // For runtime prefetches, we always perform a dynamic request, : // For runtime prefetches, we always perform a dynamic request,
......
...@@ -177,6 +177,7 @@ export function createServerParamsForRoute( ...@@ -177,6 +177,7 @@ export function createServerParamsForRoute(
return createRuntimePrerenderParams( return createRuntimePrerenderParams(
underlyingParams, underlyingParams,
null, null,
workStore,
workUnitStore, workUnitStore,
varyParamsAccumulator, varyParamsAccumulator,
isRuntimePrefetchable isRuntimePrefetchable
...@@ -249,6 +250,7 @@ export function createServerParamsForServerSegment( ...@@ -249,6 +250,7 @@ export function createServerParamsForServerSegment(
return createRuntimePrerenderParams( return createRuntimePrerenderParams(
underlyingParams, underlyingParams,
optionalCatchAllParamName, optionalCatchAllParamName,
workStore,
workUnitStore, workUnitStore,
varyParamsAccumulator, varyParamsAccumulator,
isRuntimePrefetchable isRuntimePrefetchable
...@@ -343,9 +345,20 @@ export function createPrerenderParamsForClientSegment( ...@@ -343,9 +345,20 @@ export function createPrerenderParamsForClientSegment(
throw new InvariantError( throw new InvariantError(
'createPrerenderParamsForClientSegment should not be called inside generateStaticParams.' 'createPrerenderParamsForClientSegment should not be called inside generateStaticParams.'
) )
case 'prerender-runtime':
if (workUnitStore.forceOmitParams) {
// App Shell prefetch: hang on params so the client segment doesn't
// receive a resolved value and render. Matches the server-side
// behavior in createRuntimePrerenderParams.
return makeHangingPromise(
workUnitStore.renderSignal,
workStore.route,
'`params`'
)
}
break
case 'prerender-ppr': case 'prerender-ppr':
case 'prerender-legacy': case 'prerender-legacy':
case 'prerender-runtime':
case 'request': case 'request':
break break
default: default:
...@@ -423,10 +436,21 @@ function createStaticPrerenderParams( ...@@ -423,10 +436,21 @@ function createStaticPrerenderParams(
function createRuntimePrerenderParams( function createRuntimePrerenderParams(
underlyingParams: Params, underlyingParams: Params,
optionalCatchAllParamName: string | null, optionalCatchAllParamName: string | null,
workStore: WorkStore,
workUnitStore: PrerenderStoreModernRuntime, workUnitStore: PrerenderStoreModernRuntime,
varyParamsAccumulator: VaryParamsAccumulator | null, varyParamsAccumulator: VaryParamsAccumulator | null,
isRuntimePrefetchable: boolean isRuntimePrefetchable: boolean
): Promise<Params> { ): Promise<Params> {
if (workUnitStore.forceOmitParams) {
// App Shell prefetch: any `await params` suspends. Segments that depend
// on params render as holes, leaving the param-independent shell.
return makeHangingPromise<Params>(
workUnitStore.renderSignal,
workStore.route,
'`params`'
)
}
const underlyingParamsWithVarying = const underlyingParamsWithVarying =
varyParamsAccumulator !== null varyParamsAccumulator !== null
? createVaryingParams( ? createVaryingParams(
......
...@@ -144,6 +144,7 @@ export function createServerSearchParamsForServerPage( ...@@ -144,6 +144,7 @@ export function createServerSearchParamsForServerPage(
case 'prerender-runtime': case 'prerender-runtime':
return createRuntimePrerenderSearchParams( return createRuntimePrerenderSearchParams(
underlyingSearchParams, underlyingSearchParams,
workStore,
workUnitStore, workUnitStore,
varyParamsAccumulator, varyParamsAccumulator,
isRuntimePrefetchable isRuntimePrefetchable
...@@ -241,10 +242,23 @@ function createStaticPrerenderSearchParams( ...@@ -241,10 +242,23 @@ function createStaticPrerenderSearchParams(
function createRuntimePrerenderSearchParams( function createRuntimePrerenderSearchParams(
underlyingSearchParams: SearchParams, underlyingSearchParams: SearchParams,
workStore: WorkStore,
workUnitStore: PrerenderStoreModernRuntime, workUnitStore: PrerenderStoreModernRuntime,
varyParamsAccumulator: VaryParamsAccumulator | null, varyParamsAccumulator: VaryParamsAccumulator | null,
isRuntimePrefetchable: boolean isRuntimePrefetchable: boolean
): Promise<SearchParams> { ): Promise<SearchParams> {
if (workUnitStore.forceOmitParams) {
// App Shell prefetch: any `await searchParams` suspends. Segments that
// depend on search params render as holes, leaving the
// search-param-independent shell. Matches the behavior in
// createRuntimePrerenderParams for path params.
return makeHangingPromise<SearchParams>(
workUnitStore.renderSignal,
workStore.route,
'`searchParams`'
)
}
const underlyingSearchParamsWithVarying = const underlyingSearchParamsWithVarying =
varyParamsAccumulator !== null varyParamsAccumulator !== null
? createVaryingSearchParams(varyParamsAccumulator, underlyingSearchParams) ? createVaryingSearchParams(varyParamsAccumulator, underlyingSearchParams)
......
...@@ -22,7 +22,7 @@ function normalizeCacheBustingInput( ...@@ -22,7 +22,7 @@ function normalizeCacheBustingInput(
} }
function createCacheBustingSearchParamInput( function createCacheBustingSearchParamInput(
prefetchHeader: '1' | '2' | '0' | undefined, prefetchHeader: '1' | '2' | '3' | '0' | undefined,
segmentPrefetchHeader: string | string[] | undefined, segmentPrefetchHeader: string | string[] | undefined,
stateTreeHeader: string | string[] | undefined, stateTreeHeader: string | string[] | undefined,
nextUrlHeader: string | string[] | undefined nextUrlHeader: string | string[] | undefined
...@@ -58,7 +58,7 @@ async function computeCacheBustingSearchParamFromInput( ...@@ -58,7 +58,7 @@ async function computeCacheBustingSearchParamFromInput(
} }
export async function computeCacheBustingSearchParam( export async function computeCacheBustingSearchParam(
prefetchHeader: '1' | '2' | '0' | undefined, prefetchHeader: '1' | '2' | '3' | '0' | undefined,
segmentPrefetchHeader: string | string[] | undefined, segmentPrefetchHeader: string | string[] | undefined,
stateTreeHeader: string | string[] | undefined, stateTreeHeader: string | string[] | undefined,
nextUrlHeader: string | string[] | undefined nextUrlHeader: string | string[] | undefined
...@@ -77,7 +77,7 @@ export async function computeCacheBustingSearchParam( ...@@ -77,7 +77,7 @@ export async function computeCacheBustingSearchParam(
} }
export function computeLegacyCacheBustingSearchParam( export function computeLegacyCacheBustingSearchParam(
prefetchHeader: '1' | '2' | '0' | undefined, prefetchHeader: '1' | '2' | '3' | '0' | undefined,
segmentPrefetchHeader: string | string[] | undefined, segmentPrefetchHeader: string | string[] | undefined,
stateTreeHeader: string | string[] | undefined, stateTreeHeader: string | string[] | undefined,
nextUrlHeader: string | string[] | undefined nextUrlHeader: string | string[] | undefined
......
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