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 {
readonly flightRouterState: FlightRouterState | undefined
readonly isPrefetchRequest: 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 isHmrRefresh: boolean
readonly isRSCRequest: boolean
......@@ -387,7 +393,12 @@ function parseRequestHeaders(
// (TODO: this is confusing, we should refactor this to express this better)
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
......@@ -440,6 +451,7 @@ function parseRequestHeaders(
flightRouterState,
isPrefetchRequest,
isRuntimePrefetchRequest,
isAppShellPrefetchRequest,
isRouteTreePrefetchRequest,
isHmrRefresh,
isRSCRequest,
......@@ -1276,7 +1288,8 @@ async function spawnRuntimePrefetchWithFilledCaches(
requestStore.cookies,
requestStore.draftMode,
onError,
staleTimeIterable
staleTimeIterable,
false // forceOmitParams — server-initiated background prefetch, not a shell request
)
await result.prelude.pipeTo(writable)
......@@ -1663,7 +1676,8 @@ async function generateDynamicFlightRenderResultWithStagesInDev(
async function generateRuntimePrefetchResult(
req: BaseNextRequest,
ctx: AppRenderContext,
requestStore: RequestStore
requestStore: RequestStore,
forceOmitParams: boolean
): Promise<RenderResult> {
const { workStore, renderOpts } = ctx
const { isBuildTimePrerendering = false, onInstrumentationRequestError } =
......@@ -1713,7 +1727,8 @@ async function generateRuntimePrefetchResult(
rootParams,
requestStore.headers,
requestStore.cookies,
requestStore.draftMode
requestStore.draftMode,
forceOmitParams
)
const response = await finalRuntimeServerPrerender(
......@@ -1726,7 +1741,8 @@ async function generateRuntimePrefetchResult(
requestStore.cookies,
requestStore.draftMode,
onError,
staleTimeIterable
staleTimeIterable,
forceOmitParams
)
applyMetadataFromPrerenderResult(response, metadata, workStore)
......@@ -1743,7 +1759,8 @@ async function prospectiveRuntimeServerPrerender(
rootParams: Params,
headers: PrerenderStoreModernRuntime['headers'],
cookies: PrerenderStoreModernRuntime['cookies'],
draftMode: PrerenderStoreModernRuntime['draftMode']
draftMode: PrerenderStoreModernRuntime['draftMode'],
forceOmitParams: boolean
) {
const { implicitTags, renderOpts, workStore } = ctx
const { ComponentMod } = renderOpts
......@@ -1793,6 +1810,7 @@ async function prospectiveRuntimeServerPrerender(
headers,
cookies,
draftMode,
forceOmitParams,
}
const { clientModules } = getClientReferenceManifest()
......@@ -1908,7 +1926,8 @@ async function finalRuntimeServerPrerender(
cookies: PrerenderStoreModernRuntime['cookies'],
draftMode: PrerenderStoreModernRuntime['draftMode'],
onError: (err: unknown) => string | undefined,
staleTimeIterable: StaleTimeIterable
staleTimeIterable: StaleTimeIterable,
forceOmitParams: boolean
) {
const { implicitTags, renderOpts } = ctx
const { ComponentMod, experimental, isDebugDynamicAccesses } = renderOpts
......@@ -1955,6 +1974,7 @@ async function finalRuntimeServerPrerender(
headers,
cookies,
draftMode,
forceOmitParams,
}
trackStaleTime(finalServerPrerenderStore, staleTimeIterable, selectStaleTime)
......@@ -2731,6 +2751,7 @@ async function renderToHTMLOrFlightImpl(
flightRouterState,
isPrefetchRequest,
isRuntimePrefetchRequest,
isAppShellPrefetchRequest,
isRSCRequest,
isHmrRefresh,
nonce,
......@@ -2957,7 +2978,12 @@ async function renderToHTMLOrFlightImpl(
if (isRSCRequest) {
if (isRuntimePrefetchRequest) {
// MARK: RSC runtimePrefetch
return generateRuntimePrefetchResult(req, ctx, requestStore)
return generateRuntimePrefetchResult(
req,
ctx,
requestStore,
isAppShellPrefetchRequest
)
} else {
if (
process.env.__NEXT_DEV_SERVER &&
......
......@@ -193,6 +193,14 @@ export interface PrerenderStoreModernRuntime
readonly headers: RequestStore['headers']
readonly cookies: RequestStore['cookies']
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 {
......
......@@ -2071,8 +2071,10 @@ export default abstract class Server<
const prefetchHeaderValue = headers[NEXT_ROUTER_PREFETCH_HEADER]
const routerPrefetch =
prefetchHeaderValue !== undefined
? // We only recognize '1' and '2'. Strip all other values here.
prefetchHeaderValue === '1' || prefetchHeaderValue === '2'
? // We only recognize '1', '2', and '3'. Strip all other values here.
prefetchHeaderValue === '1' ||
prefetchHeaderValue === '2' ||
prefetchHeaderValue === '3'
? prefetchHeaderValue
: undefined
: // For runtime prefetches, we always perform a dynamic request,
......
......@@ -177,6 +177,7 @@ export function createServerParamsForRoute(
return createRuntimePrerenderParams(
underlyingParams,
null,
workStore,
workUnitStore,
varyParamsAccumulator,
isRuntimePrefetchable
......@@ -249,6 +250,7 @@ export function createServerParamsForServerSegment(
return createRuntimePrerenderParams(
underlyingParams,
optionalCatchAllParamName,
workStore,
workUnitStore,
varyParamsAccumulator,
isRuntimePrefetchable
......@@ -343,9 +345,20 @@ export function createPrerenderParamsForClientSegment(
throw new InvariantError(
'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-legacy':
case 'prerender-runtime':
case 'request':
break
default:
......@@ -423,10 +436,21 @@ function createStaticPrerenderParams(
function createRuntimePrerenderParams(
underlyingParams: Params,
optionalCatchAllParamName: string | null,
workStore: WorkStore,
workUnitStore: PrerenderStoreModernRuntime,
varyParamsAccumulator: VaryParamsAccumulator | null,
isRuntimePrefetchable: boolean
): 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 =
varyParamsAccumulator !== null
? createVaryingParams(
......
......@@ -144,6 +144,7 @@ export function createServerSearchParamsForServerPage(
case 'prerender-runtime':
return createRuntimePrerenderSearchParams(
underlyingSearchParams,
workStore,
workUnitStore,
varyParamsAccumulator,
isRuntimePrefetchable
......@@ -241,10 +242,23 @@ function createStaticPrerenderSearchParams(
function createRuntimePrerenderSearchParams(
underlyingSearchParams: SearchParams,
workStore: WorkStore,
workUnitStore: PrerenderStoreModernRuntime,
varyParamsAccumulator: VaryParamsAccumulator | null,
isRuntimePrefetchable: boolean
): 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 =
varyParamsAccumulator !== null
? createVaryingSearchParams(varyParamsAccumulator, underlyingSearchParams)
......
......@@ -22,7 +22,7 @@ function normalizeCacheBustingInput(
}
function createCacheBustingSearchParamInput(
prefetchHeader: '1' | '2' | '0' | undefined,
prefetchHeader: '1' | '2' | '3' | '0' | undefined,
segmentPrefetchHeader: string | string[] | undefined,
stateTreeHeader: string | string[] | undefined,
nextUrlHeader: string | string[] | undefined
......@@ -58,7 +58,7 @@ async function computeCacheBustingSearchParamFromInput(
}
export async function computeCacheBustingSearchParam(
prefetchHeader: '1' | '2' | '0' | undefined,
prefetchHeader: '1' | '2' | '3' | '0' | undefined,
segmentPrefetchHeader: string | string[] | undefined,
stateTreeHeader: string | string[] | undefined,
nextUrlHeader: string | string[] | undefined
......@@ -77,7 +77,7 @@ export async function computeCacheBustingSearchParam(
}
export function computeLegacyCacheBustingSearchParam(
prefetchHeader: '1' | '2' | '0' | undefined,
prefetchHeader: '1' | '2' | '3' | '0' | undefined,
segmentPrefetchHeader: string | string[] | undefined,
stateTreeHeader: 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