Unverified Commit 3717cd3d authored by Andrew Clark's avatar Andrew Clark Committed by GitHub

Gate partial fallback shell upgrades behind `partialPrefetching` for `next start` (#96297)

In #96074 I put the `partialFallback` behavior behind the
`partialPrefetching` flag, so that we don't risk an explosion in ISR
costs for apps that haven't opted into Partial Prefetching. But it turns
out I only handled this for deploy mode — i.e. the build output consumed
by the Vercel adapter. The behavior was still unconditionally on for
`next start`.

The reason it was easy to miss is that `next start` and the adapter
express partial fallback shells through completely separate mechanisms.
The adapter emits a `partialFallback` flag into the build output and
lets the platform's ISR layer perform the shell upgrade. `next start`
has no such flag; the server performs the upgrade itself, in the
compiled page runtime. So the gate I added to the adapter output had no
effect on the self-hosted path.

To understand how the `next start` path was configured, I looked at the
PR that removed the original top-level `partialFallbacks` config flag
(#93859). Before that PR, the behavior was gated in the runtime; when
the flag was removed those gates were deleted and the behavior became
always-on.

The important subtlety is that only the *upgrade* should be gated, not
the shell machinery as a whole. On `next start`, the value that decides
whether a shell can be specialized (`remainingPrerenderableParams`) also
drives core Cache Components behavior — build-time partial prerendering
of params and serving build-time sub-shells — which must stay on
regardless of `partialPrefetching`. So this gates only the two things
that make up the "upgrade on first request" cost risk: the background
ISR revalidation that specializes a shell per request, and the
client-facing `isFallbackUpgradeable` signal that tells the client to
retry a prefetch waiting for that upgrade.

Adds coverage with a `partialPrefetching`-disabled fixture asserting
that fallback shells stay shared rather than specializing per request.
parent d321ec8a
...@@ -3135,8 +3135,12 @@ export default async function build( ...@@ -3135,8 +3135,12 @@ export default async function build(
_isRoutePPREnabled: isRoutePPREnabled, _isRoutePPREnabled: isRoutePPREnabled,
_allowEmptyStaticShell: !route.throwOnEmptyStaticShell, _allowEmptyStaticShell: !route.throwOnEmptyStaticShell,
// A fallback shell can only be upgraded if at least one of // A fallback shell can only be upgraded if at least one of
// its fallback params is a `generateStaticParams` candidate. // its fallback params is a `generateStaticParams` candidate,
// and only when Partial Prefetching is enabled. Otherwise
// nothing ever performs the upgrade, so flagging the shell
// would only cause the client to retry the prefetch.
_isFallbackUpgradeable: _isFallbackUpgradeable:
Boolean(config.partialPrefetching) &&
(route.remainingPrerenderableParams?.length ?? 0) > 0, (route.remainingPrerenderableParams?.length ?? 0) > 0,
} }
}) })
......
...@@ -629,7 +629,17 @@ export function createAppPageEntrypoint({ ...@@ -629,7 +629,17 @@ export function createAppPageEntrypoint({
: prerenderMatch.source : prerenderMatch.source
: null : null
if (fallbackPathname && prerenderInfo?.fallbackRouteParams?.length) { if (
// Partial fallback shells are only specialized per request when Partial
// Prefetching is enabled, mirroring the `partialFallback` flag the
// adapter emits for deployments. When it's disabled we fall through to
// the normal ISR cache key (`resolvedPathname`) so the shell stays
// shared, matching the behavior before the `partialFallbacks` config
// flag was removed.
nextConfig.partialPrefetching &&
fallbackPathname &&
prerenderInfo?.fallbackRouteParams?.length
) {
if (remainingPrerenderableParams.length > 0) { if (remainingPrerenderableParams.length > 0) {
const completedShellCacheKey = buildCompletedShellCacheKey( const completedShellCacheKey = buildCompletedShellCacheKey(
fallbackPathname, fallbackPathname,
...@@ -710,7 +720,7 @@ export function createAppPageEntrypoint({ ...@@ -710,7 +720,7 @@ export function createAppPageEntrypoint({
routerServerContext?.isWrappedByNextServer routerServerContext?.isWrappedByNextServer
) )
const remainingFallbackRouteParams = const remainingFallbackRouteParams =
remainingPrerenderableParams.length > 0 nextConfig.partialPrefetching && remainingPrerenderableParams.length > 0
? (prerenderInfo?.fallbackRouteParams?.filter( ? (prerenderInfo?.fallbackRouteParams?.filter(
(param) => (param) =>
!remainingPrerenderableParams.some( !remainingPrerenderableParams.some(
...@@ -930,9 +940,14 @@ export function createAppPageEntrypoint({ ...@@ -930,9 +940,14 @@ export function createAppPageEntrypoint({
partialPrefetching: nextConfig.partialPrefetching, partialPrefetching: nextConfig.partialPrefetching,
// A fallback shell can only be upgraded to a concrete version if at // A fallback shell can only be upgraded to a concrete version if at
// least one of its fallback params is a `generateStaticParams` // least one of its fallback params is a `generateStaticParams`
// candidate (`remainingPrerenderableParams`). This gates whether the // candidate (`remainingPrerenderableParams`), and only when Partial
// per-segment prefetch responses are flagged `isUpgradeableISRFallback`. // Prefetching is enabled (the upgrade itself is gated on it above).
isFallbackUpgradeable: remainingPrerenderableParams.length > 0, // This gates whether the per-segment prefetch responses are flagged
// `isUpgradeableISRFallback`; without an upgrade to wait for, the
// client should not retry the prefetch.
isFallbackUpgradeable:
Boolean(nextConfig.partialPrefetching) &&
remainingPrerenderableParams.length > 0,
validationLevel: validationLevel:
nextConfig.experimental.instantInsights.validationLevel, nextConfig.experimental.instantInsights.validationLevel,
experimental: { experimental: {
...@@ -1105,6 +1120,7 @@ export function createAppPageEntrypoint({ ...@@ -1105,6 +1120,7 @@ export function createAppPageEntrypoint({
} }
if ( if (
nextConfig.partialPrefetching &&
prerenderInfo?.fallback === null && prerenderInfo?.fallback === null &&
!hasOmittedConcreteFallbackParam && !hasOmittedConcreteFallbackParam &&
!hasUnresolvedRootFallbackParams && !hasUnresolvedRootFallbackParams &&
...@@ -1277,6 +1293,10 @@ export function createAppPageEntrypoint({ ...@@ -1277,6 +1293,10 @@ export function createAppPageEntrypoint({
if ( if (
!isMinimalMode && !isMinimalMode &&
isRoutePPREnabled && isRoutePPREnabled &&
// Upgrading a fallback shell into a more specific ISR entry is
// only done when Partial Prefetching is enabled, mirroring the
// `partialFallback` flag the adapter emits for deployments.
nextConfig.partialPrefetching &&
// Match the build-time contract: only fallback shells that can // Match the build-time contract: only fallback shells that can
// still be completed with prerenderable params should upgrade. // still be completed with prerenderable params should upgrade.
remainingPrerenderableParams.length > 0 && remainingPrerenderableParams.length > 0 &&
......
...@@ -3,6 +3,11 @@ ...@@ -3,6 +3,11 @@
*/ */
const nextConfig = { const nextConfig = {
cacheComponents: true, cacheComponents: true,
// This suite observes the background upgrade of a fallback shell into a
// concrete ISR entry (the first request's spans differ from the upgraded
// second request's). That upgrade only runs when Partial Prefetching is
// enabled, so opt in to keep exercising it.
partialPrefetching: true,
} }
module.exports = nextConfig module.exports = nextConfig
export default function Loading() {
return (
<div id="fallback" data-fallback>
loading...
</div>
)
}
import { Suspense } from 'react'
async function Dynamic() {
await new Promise((resolve) => setTimeout(resolve, 1000))
return <div id="agent">Custom Data</div>
}
export async function generateStaticParams() {
return [{ slug: 'one' }]
}
export default async function Page({
params,
}: {
params: Promise<{ slug: string }>
}) {
const { slug } = await params
return (
<div>
<div id="slug" data-slug={slug}>
{slug}
</div>
<Suspense fallback={<div>Loading...</div>}>
<Dynamic />
</Suspense>
</div>
)
}
import type { ReactNode } from 'react'
export default async function RootLayout({
children,
}: {
children: ReactNode
}) {
return (
<html>
<body>{children}</body>
</html>
)
}
export default function Loading() {
return (
<div id="two-fallback" data-fallback>
loading two...
</div>
)
}
export default async function Page({
params,
}: {
params: Promise<{ one: string; two: string }>
}) {
const { two } = await params
return <div id="two">{two}</div>
}
import { Suspense, type ReactNode } from 'react'
export function generateStaticParams() {
return [{ one: 'b' }]
}
async function LayoutImpl({
children,
params,
}: {
children: ReactNode
params: Promise<{ one: string }>
}) {
const { one } = await params
return (
<div>
<div id="one">{one}</div>
{children}
</div>
)
}
export default async function LayoutWrapper(props) {
return (
<Suspense
fallback={
<div id="one-fallback" data-fallback>
loading one...
</div>
}
>
<LayoutImpl {...props} />
</Suspense>
)
}
/**
* @type {import('next').NextConfig}
*/
const nextConfig = {
cacheComponents: true,
}
module.exports = nextConfig
...@@ -170,3 +170,74 @@ describe('partial-fallback-shell-upgrade', () => { ...@@ -170,3 +170,74 @@ describe('partial-fallback-shell-upgrade', () => {
) )
}) })
}) })
describe('partial-fallback-shell-upgrade - partialPrefetching disabled', () => {
const { next, isNextDev } = nextTestSetup({
files: path.join(__dirname, 'fixtures', 'partial-prefetching-disabled'),
// The latest changes to support this behavior on deployed infra are available in the adapter,
// and are not being backported to the CLI
skipDeployment: !isAdapterTest,
})
if (isNextDev) {
it('skipped in dev', () => {})
return
}
const fetchSplitHTML = createSplitHTMLFetcher(next)
it('should not upgrade the fallback shell to a route shell', async () => {
const pathname = '/two'
const start = Date.now()
await retry(
async () => {
const $ = await next.render$(pathname)
expect($('#fallback').text()).toBe('loading...')
expect($('#slug').closest('[hidden]').length).toBe(1)
if (Date.now() - start < 5000) {
throw new Error('continue polling fallback shell')
}
},
6000,
500,
'fallback shell should remain unupgraded without partialPrefetching'
)
})
it('should not specialize a generic shell into a more specific shell', async () => {
const firstResult = await fetchSplitHTML('/prefix/c/foo')
expect(firstResult.response.status).toBe(200)
expect(firstResult.static$('#one').length).toBe(0)
expect(firstResult.static$('#one-fallback').text()).toBe('loading one...')
expect(firstResult.dynamicPart).toContain('<div id="one">c</div>')
expect(firstResult.dynamicPart).toContain('<div id="two">foo</div>')
const start = Date.now()
await retry(
async () => {
const secondResult = await fetchSplitHTML('/prefix/c/bar')
expect(secondResult.response.status).toBe(200)
// The generic shell stays shared: `#one` is never baked into the
// static part the way it is when Partial Prefetching is enabled.
expect(secondResult.static$('#one').length).toBe(0)
expect(secondResult.static$('#one-fallback').text()).toBe(
'loading one...'
)
expect(secondResult.dynamicPart).toContain('<div id="one">c</div>')
expect(secondResult.dynamicPart).toContain('<div id="two">bar</div>')
if (Date.now() - start < 5000) {
throw new Error('continue polling generic shell')
}
},
6000,
500,
'generic shell should remain shared without partialPrefetching'
)
})
})
...@@ -6,7 +6,7 @@ export default function Page() { ...@@ -6,7 +6,7 @@ export default function Page() {
<li> <li>
{/* Prerendered at build time via generateStaticParams — the prefetch {/* Prerendered at build time via generateStaticParams — the prefetch
receives the concrete version, never a fallback. */} receives the concrete version, never a fallback. */}
<LinkAccordion href="/static-posts/1"> <LinkAccordion href="/static-posts/1" prefetch={true}>
Static post 1 (concrete) Static post 1 (concrete)
</LinkAccordion> </LinkAccordion>
</li> </li>
...@@ -15,14 +15,14 @@ export default function Page() { ...@@ -15,14 +15,14 @@ export default function Page() {
un-enumerated param is upgradeable: the server serves a fallback un-enumerated param is upgradeable: the server serves a fallback
shell on first prefetch, then regenerates the concrete version in shell on first prefetch, then regenerates the concrete version in
the background. Used by the recovery test. */} the background. Used by the recovery test. */}
<LinkAccordion href="/posts/recovery"> <LinkAccordion href="/posts/recovery" prefetch={true}>
Post recovery (upgradeable fallback) Post recovery (upgradeable fallback)
</LinkAccordion> </LinkAccordion>
</li> </li>
<li> <li>
{/* No generateStaticParams — the fallback shell can never be upgraded, {/* No generateStaticParams — the fallback shell can never be upgraded,
so the prefetch shell must NOT be flagged as a fallback (no retry). */} so the prefetch shell must NOT be flagged as a fallback (no retry). */}
<LinkAccordion href="/no-static-params/1"> <LinkAccordion href="/no-static-params/1" prefetch={true}>
No static params 1 (non-upgradeable fallback) No static params 1 (non-upgradeable fallback)
</LinkAccordion> </LinkAccordion>
</li> </li>
...@@ -32,7 +32,7 @@ export default function Page() { ...@@ -32,7 +32,7 @@ export default function Page() {
test's. Used by the retry-*limit* test, which forces every prefetch test's. Used by the retry-*limit* test, which forces every prefetch
response to keep returning the fallback so the client retries to response to keep returning the fallback so the client retries to
its cap and then stops. */} its cap and then stops. */}
<LinkAccordion href="/posts/retry-limit"> <LinkAccordion href="/posts/retry-limit" prefetch={true}>
Post retry-limit (upgradeable fallback) Post retry-limit (upgradeable fallback)
</LinkAccordion> </LinkAccordion>
</li> </li>
......
...@@ -2,6 +2,11 @@ import type { NextConfig } from 'next' ...@@ -2,6 +2,11 @@ import type { NextConfig } from 'next'
const nextConfig: NextConfig = { const nextConfig: NextConfig = {
cacheComponents: true, cacheComponents: true,
// Fallback shells are only flagged upgradeable (and upgraded) when Partial
// Prefetching is enabled; this suite exercises that upgrade + client-retry
// path. The links opt into `prefetch={true}` because a Partial Prefetching
// app skips the speculative prefetch otherwise.
partialPrefetching: true,
experimental: { experimental: {
prefetchInlining: true, prefetchInlining: true,
varyParams: true, varyParams: true,
......
...@@ -2,6 +2,13 @@ ...@@ -2,6 +2,13 @@
* @type {import('next').NextConfig} * @type {import('next').NextConfig}
*/ */
const nextConfig = { const nextConfig = {
// The Cache Components cases in this suite (run with __NEXT_CACHE_COMPONENTS)
// exercise the navigation-triggered upgrade of a fallback shell into a
// concrete route shell, which only runs when Partial Prefetching is enabled.
// Enable it only in that mode: `partialPrefetching` requires Cache Components,
// so setting it unconditionally would fail the build in the non-Cache
// Components mode this fixture also runs in.
partialPrefetching: process.env.__NEXT_CACHE_COMPONENTS === 'true',
experimental: { experimental: {
prefetchInlining: false, prefetchInlining: false,
useCache: true, useCache: true,
......
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