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(
_isRoutePPREnabled: isRoutePPREnabled,
_allowEmptyStaticShell: !route.throwOnEmptyStaticShell,
// 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:
Boolean(config.partialPrefetching) &&
(route.remainingPrerenderableParams?.length ?? 0) > 0,
}
})
......
......@@ -629,7 +629,17 @@ export function createAppPageEntrypoint({
: prerenderMatch.source
: 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) {
const completedShellCacheKey = buildCompletedShellCacheKey(
fallbackPathname,
......@@ -710,7 +720,7 @@ export function createAppPageEntrypoint({
routerServerContext?.isWrappedByNextServer
)
const remainingFallbackRouteParams =
remainingPrerenderableParams.length > 0
nextConfig.partialPrefetching && remainingPrerenderableParams.length > 0
? (prerenderInfo?.fallbackRouteParams?.filter(
(param) =>
!remainingPrerenderableParams.some(
......@@ -930,9 +940,14 @@ export function createAppPageEntrypoint({
partialPrefetching: nextConfig.partialPrefetching,
// A fallback shell can only be upgraded to a concrete version if at
// least one of its fallback params is a `generateStaticParams`
// candidate (`remainingPrerenderableParams`). This gates whether the
// per-segment prefetch responses are flagged `isUpgradeableISRFallback`.
isFallbackUpgradeable: remainingPrerenderableParams.length > 0,
// candidate (`remainingPrerenderableParams`), and only when Partial
// Prefetching is enabled (the upgrade itself is gated on it above).
// 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:
nextConfig.experimental.instantInsights.validationLevel,
experimental: {
......@@ -1105,6 +1120,7 @@ export function createAppPageEntrypoint({
}
if (
nextConfig.partialPrefetching &&
prerenderInfo?.fallback === null &&
!hasOmittedConcreteFallbackParam &&
!hasUnresolvedRootFallbackParams &&
......@@ -1277,6 +1293,10 @@ export function createAppPageEntrypoint({
if (
!isMinimalMode &&
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
// still be completed with prerenderable params should upgrade.
remainingPrerenderableParams.length > 0 &&
......
......@@ -3,6 +3,11 @@
*/
const nextConfig = {
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
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', () => {
)
})
})
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() {
<li>
{/* Prerendered at build time via generateStaticParams — the prefetch
receives the concrete version, never a fallback. */}
<LinkAccordion href="/static-posts/1">
<LinkAccordion href="/static-posts/1" prefetch={true}>
Static post 1 (concrete)
</LinkAccordion>
</li>
......@@ -15,14 +15,14 @@ export default function Page() {
un-enumerated param is upgradeable: the server serves a fallback
shell on first prefetch, then regenerates the concrete version in
the background. Used by the recovery test. */}
<LinkAccordion href="/posts/recovery">
<LinkAccordion href="/posts/recovery" prefetch={true}>
Post recovery (upgradeable fallback)
</LinkAccordion>
</li>
<li>
{/* No generateStaticParams — the fallback shell can never be upgraded,
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)
</LinkAccordion>
</li>
......@@ -32,7 +32,7 @@ export default function Page() {
test's. Used by the retry-*limit* test, which forces every prefetch
response to keep returning the fallback so the client retries to
its cap and then stops. */}
<LinkAccordion href="/posts/retry-limit">
<LinkAccordion href="/posts/retry-limit" prefetch={true}>
Post retry-limit (upgradeable fallback)
</LinkAccordion>
</li>
......
......@@ -2,6 +2,11 @@ import type { NextConfig } from 'next'
const nextConfig: NextConfig = {
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: {
prefetchInlining: true,
varyParams: true,
......
......@@ -2,6 +2,13 @@
* @type {import('next').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: {
prefetchInlining: false,
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