Unverified Commit ae3f9f51 authored by Zack Tanner's avatar Zack Tanner Committed by GitHub

partial fallbacks: complete generic shells into more specific shells (#91231)

In #91158, I wired up the plumbing to indicate whether a partial
fallback shell is upgradeable. The previous heuristic was too coarse.
This wires up the handling in `next start`.

This PR teaches the runtime to complete a fallback shell only as far as
prerendering allows. Instead of promoting a generic shell like
`/[one]/[two]` directly to `/c/foo`, it promotes it to the most specific
prerendered shell for that branch, `/c/[two]`, where `[one]` has
`generateStaticParams`. That means later requests can reuse the more
complete shell, while fully dynamic params continue to stream as dynamic
content.

With this change:

- the first request still serves the generic fallback shell immediately
- the background revalidate writes a more specific shell, not a fully
concrete route
- later requests for the same prerendered branch reuse that shell
- upgrading stops once only fully dynamic params remain

This keeps the runtime behavior aligned with the build-time
`remainingPrerenderableParams` contract from the downstack PR.
parent 914df17a
...@@ -3453,7 +3453,7 @@ export default async function build( ...@@ -3453,7 +3453,7 @@ export default async function build(
fallbackExpire: fallbackCacheControl?.expire, fallbackExpire: fallbackCacheControl?.expire,
fallbackStatus: meta.status, fallbackStatus: meta.status,
fallbackHeaders: meta.headers, fallbackHeaders: meta.headers,
fallbackRootParams: fallback fallbackRootParams: route.fallbackRouteParams
? route.fallbackRootParams ? route.fallbackRootParams
: undefined, : undefined,
fallbackSourceRoute: fallbackSourceRoute:
......
...@@ -72,7 +72,10 @@ describe('PrerenderManifestMatcher', () => { ...@@ -72,7 +72,10 @@ describe('PrerenderManifestMatcher', () => {
const result = matcher.match('/products/123') const result = matcher.match('/products/123')
expect(result).toBe(specificRoute) expect(result).toEqual({
source: '/products/[id]',
route: specificRoute,
})
}) })
it('should handle when the fallbackSourceRoute is not set', () => { it('should handle when the fallbackSourceRoute is not set', () => {
...@@ -88,7 +91,10 @@ describe('PrerenderManifestMatcher', () => { ...@@ -88,7 +91,10 @@ describe('PrerenderManifestMatcher', () => {
const result = matcher.match('/products/123') const result = matcher.match('/products/123')
expect(result).toBe(route) expect(result).toEqual({
source: '/products/[id]',
route,
})
}) })
it('should match unknown root branches against the generic source shell', () => { it('should match unknown root branches against the generic source shell', () => {
...@@ -130,8 +136,14 @@ describe('PrerenderManifestMatcher', () => { ...@@ -130,8 +136,14 @@ describe('PrerenderManifestMatcher', () => {
manifest manifest
) )
expect(matcher.match('/root-gsp/en/two')).toBe(generatedRootRoute) expect(matcher.match('/root-gsp/en/two')).toEqual({
expect(matcher.match('/root-gsp/fr/two')).toBe(genericRootRoute) source: '/root-gsp/en/[slug]',
route: generatedRootRoute,
})
expect(matcher.match('/root-gsp/fr/two')).toEqual({
source: '/root-gsp/[lang]/[slug]',
route: genericRootRoute,
})
}) })
}) })
......
...@@ -30,6 +30,11 @@ type Matcher = { ...@@ -30,6 +30,11 @@ type Matcher = {
route: DeepReadonly<DynamicPrerenderManifestRoute> route: DeepReadonly<DynamicPrerenderManifestRoute>
} }
export type PrerenderManifestMatch = {
source: string
route: DeepReadonly<DynamicPrerenderManifestRoute>
}
/** /**
* A matcher for the prerender manifest. * A matcher for the prerender manifest.
* *
...@@ -57,9 +62,7 @@ export class PrerenderManifestMatcher { ...@@ -57,9 +62,7 @@ export class PrerenderManifestMatcher {
* @param pathname - The pathname to match. * @param pathname - The pathname to match.
* @returns The dynamic route that matches the pathname. * @returns The dynamic route that matches the pathname.
*/ */
public match( public match(pathname: string): PrerenderManifestMatch | null {
pathname: string
): DeepReadonly<DynamicPrerenderManifestRoute> | null {
// Iterate over the matchers. They're already in the correct order of // Iterate over the matchers. They're already in the correct order of
// specificity as they were inserted into the prerender manifest that way // specificity as they were inserted into the prerender manifest that way
// and iterating over them with Object.entries guarantees that. // and iterating over them with Object.entries guarantees that.
...@@ -71,7 +74,10 @@ export class PrerenderManifestMatcher { ...@@ -71,7 +74,10 @@ export class PrerenderManifestMatcher {
const match = matcher.matcher(pathname) const match = matcher.matcher(pathname)
if (match) { if (match) {
return matcher.route return {
source: matcher.source,
route: matcher.route,
}
} }
} }
......
...@@ -2873,6 +2873,7 @@ describe('app-dir static/dynamic handling', () => { ...@@ -2873,6 +2873,7 @@ describe('app-dir static/dynamic handling', () => {
}, },
], ],
"fallback": null, "fallback": null,
"fallbackRootParams": [],
"fallbackRouteParams": [], "fallbackRouteParams": [],
"prefetchDataRoute": null, "prefetchDataRoute": null,
"routeRegex": "^\\/articles\\/([^\\/]+?)(?:\\/)?$", "routeRegex": "^\\/articles\\/([^\\/]+?)(?:\\/)?$",
...@@ -2900,6 +2901,7 @@ describe('app-dir static/dynamic handling', () => { ...@@ -2900,6 +2901,7 @@ describe('app-dir static/dynamic handling', () => {
}, },
], ],
"fallback": false, "fallback": false,
"fallbackRootParams": [],
"fallbackRouteParams": [], "fallbackRouteParams": [],
"prefetchDataRoute": null, "prefetchDataRoute": null,
"routeRegex": "^\\/blog\\/([^\\/]+?)(?:\\/)?$", "routeRegex": "^\\/blog\\/([^\\/]+?)(?:\\/)?$",
...@@ -2927,6 +2929,7 @@ describe('app-dir static/dynamic handling', () => { ...@@ -2927,6 +2929,7 @@ describe('app-dir static/dynamic handling', () => {
}, },
], ],
"fallback": null, "fallback": null,
"fallbackRootParams": [],
"fallbackRouteParams": [], "fallbackRouteParams": [],
"prefetchDataRoute": null, "prefetchDataRoute": null,
"routeRegex": "^\\/blog\\/([^\\/]+?)\\/([^\\/]+?)(?:\\/)?$", "routeRegex": "^\\/blog\\/([^\\/]+?)\\/([^\\/]+?)(?:\\/)?$",
...@@ -2954,6 +2957,7 @@ describe('app-dir static/dynamic handling', () => { ...@@ -2954,6 +2957,7 @@ describe('app-dir static/dynamic handling', () => {
}, },
], ],
"fallback": null, "fallback": null,
"fallbackRootParams": [],
"fallbackRouteParams": [], "fallbackRouteParams": [],
"prefetchDataRoute": null, "prefetchDataRoute": null,
"routeRegex": "^\\/dynamic\\-error\\/([^\\/]+?)(?:\\/)?$", "routeRegex": "^\\/dynamic\\-error\\/([^\\/]+?)(?:\\/)?$",
...@@ -2981,6 +2985,7 @@ describe('app-dir static/dynamic handling', () => { ...@@ -2981,6 +2985,7 @@ describe('app-dir static/dynamic handling', () => {
}, },
], ],
"fallback": null, "fallback": null,
"fallbackRootParams": [],
"fallbackRouteParams": [], "fallbackRouteParams": [],
"prefetchDataRoute": null, "prefetchDataRoute": null,
"routeRegex": "^\\/force\\-static\\/([^\\/]+?)(?:\\/)?$", "routeRegex": "^\\/force\\-static\\/([^\\/]+?)(?:\\/)?$",
...@@ -3008,6 +3013,7 @@ describe('app-dir static/dynamic handling', () => { ...@@ -3008,6 +3013,7 @@ describe('app-dir static/dynamic handling', () => {
}, },
], ],
"fallback": false, "fallback": false,
"fallbackRootParams": [],
"fallbackRouteParams": [], "fallbackRouteParams": [],
"prefetchDataRoute": null, "prefetchDataRoute": null,
"routeRegex": "^\\/gen\\-params\\-catch\\-all\\-unique\\/(.+?)(?:\\/)?$", "routeRegex": "^\\/gen\\-params\\-catch\\-all\\-unique\\/(.+?)(?:\\/)?$",
...@@ -3035,6 +3041,7 @@ describe('app-dir static/dynamic handling', () => { ...@@ -3035,6 +3041,7 @@ describe('app-dir static/dynamic handling', () => {
}, },
], ],
"fallback": null, "fallback": null,
"fallbackRootParams": [],
"fallbackRouteParams": [], "fallbackRouteParams": [],
"prefetchDataRoute": null, "prefetchDataRoute": null,
"routeRegex": "^\\/gen\\-params\\-dynamic\\-revalidate\\/([^\\/]+?)(?:\\/)?$", "routeRegex": "^\\/gen\\-params\\-dynamic\\-revalidate\\/([^\\/]+?)(?:\\/)?$",
...@@ -3062,6 +3069,7 @@ describe('app-dir static/dynamic handling', () => { ...@@ -3062,6 +3069,7 @@ describe('app-dir static/dynamic handling', () => {
}, },
], ],
"fallback": null, "fallback": null,
"fallbackRootParams": [],
"fallbackRouteParams": [], "fallbackRouteParams": [],
"prefetchDataRoute": null, "prefetchDataRoute": null,
"routeRegex": "^\\/hooks\\/use\\-pathname\\/([^\\/]+?)(?:\\/)?$", "routeRegex": "^\\/hooks\\/use\\-pathname\\/([^\\/]+?)(?:\\/)?$",
...@@ -3089,6 +3097,7 @@ describe('app-dir static/dynamic handling', () => { ...@@ -3089,6 +3097,7 @@ describe('app-dir static/dynamic handling', () => {
}, },
], ],
"fallback": false, "fallback": false,
"fallbackRootParams": [],
"fallbackRouteParams": [], "fallbackRouteParams": [],
"prefetchDataRoute": null, "prefetchDataRoute": null,
"routeRegex": "^\\/partial\\-gen\\-params\\-no\\-additional\\-lang\\/([^\\/]+?)\\/([^\\/]+?)(?:\\/)?$", "routeRegex": "^\\/partial\\-gen\\-params\\-no\\-additional\\-lang\\/([^\\/]+?)\\/([^\\/]+?)(?:\\/)?$",
...@@ -3116,6 +3125,7 @@ describe('app-dir static/dynamic handling', () => { ...@@ -3116,6 +3125,7 @@ describe('app-dir static/dynamic handling', () => {
}, },
], ],
"fallback": false, "fallback": false,
"fallbackRootParams": [],
"fallbackRouteParams": [], "fallbackRouteParams": [],
"prefetchDataRoute": null, "prefetchDataRoute": null,
"routeRegex": "^\\/partial\\-gen\\-params\\-no\\-additional\\-slug\\/([^\\/]+?)\\/([^\\/]+?)(?:\\/)?$", "routeRegex": "^\\/partial\\-gen\\-params\\-no\\-additional\\-slug\\/([^\\/]+?)\\/([^\\/]+?)(?:\\/)?$",
...@@ -3143,6 +3153,7 @@ describe('app-dir static/dynamic handling', () => { ...@@ -3143,6 +3153,7 @@ describe('app-dir static/dynamic handling', () => {
}, },
], ],
"fallback": false, "fallback": false,
"fallbackRootParams": [],
"fallbackRouteParams": [], "fallbackRouteParams": [],
"prefetchDataRoute": null, "prefetchDataRoute": null,
"routeRegex": "^\\/partial\\-params\\-false\\/([^\\/]+?)\\/static(?:\\/)?$", "routeRegex": "^\\/partial\\-params\\-false\\/([^\\/]+?)\\/static(?:\\/)?$",
...@@ -3170,6 +3181,7 @@ describe('app-dir static/dynamic handling', () => { ...@@ -3170,6 +3181,7 @@ describe('app-dir static/dynamic handling', () => {
}, },
], ],
"fallback": null, "fallback": null,
"fallbackRootParams": [],
"fallbackRouteParams": [], "fallbackRouteParams": [],
"prefetchDataRoute": null, "prefetchDataRoute": null,
"routeRegex": "^\\/prerendered\\-not\\-found\\/([^\\/]+?)(?:\\/)?$", "routeRegex": "^\\/prerendered\\-not\\-found\\/([^\\/]+?)(?:\\/)?$",
...@@ -3197,6 +3209,7 @@ describe('app-dir static/dynamic handling', () => { ...@@ -3197,6 +3209,7 @@ describe('app-dir static/dynamic handling', () => {
}, },
], ],
"fallback": null, "fallback": null,
"fallbackRootParams": [],
"fallbackRouteParams": [], "fallbackRouteParams": [],
"prefetchDataRoute": null, "prefetchDataRoute": null,
"routeRegex": "^\\/ssg\\-draft\\-mode(?:\\/(.+?))?(?:\\/)?$", "routeRegex": "^\\/ssg\\-draft\\-mode(?:\\/(.+?))?(?:\\/)?$",
...@@ -3224,6 +3237,7 @@ describe('app-dir static/dynamic handling', () => { ...@@ -3224,6 +3237,7 @@ describe('app-dir static/dynamic handling', () => {
}, },
], ],
"fallback": null, "fallback": null,
"fallbackRootParams": [],
"fallbackRouteParams": [], "fallbackRouteParams": [],
"prefetchDataRoute": null, "prefetchDataRoute": null,
"routeRegex": "^\\/static\\-to\\-dynamic\\-error\\-forced\\/([^\\/]+?)(?:\\/)?$", "routeRegex": "^\\/static\\-to\\-dynamic\\-error\\-forced\\/([^\\/]+?)(?:\\/)?$",
......
export default function Loading() {
return (
<div id="slug-fallback" data-fallback>
loading slug...
</div>
)
}
export default async function Page({
params,
}: {
params: Promise<{ lang: string; slug: string }>
}) {
const { slug } = await params
return <div id="slug">{slug}</div>
}
import { Suspense, type ReactNode } from 'react'
export function generateStaticParams() {
return [{ lang: 'en' }]
}
type LayoutProps = {
children: ReactNode
params: Promise<{ lang: string }>
}
async function LayoutImpl({ children, params }: LayoutProps) {
const { lang } = await params
return (
<html>
<body>
<div id="lang">{lang}</div>
{children}
</body>
</html>
)
}
export default async function LayoutWrapper(props: LayoutProps) {
return (
<Suspense
fallback={
<html>
<body>
<div id="lang-fallback" data-fallback>
loading lang...
</div>
</body>
</html>
}
>
<LayoutImpl {...props} />
</Suspense>
)
}
/**
* @type {import('next').NextConfig}
*/
const nextConfig = {
cacheComponents: true,
experimental: {
partialFallbacks: true,
},
}
module.exports = nextConfig
import cheerio from 'cheerio'
import { nextTestSetup } from 'e2e-utils'
import { splitResponseWithPPRSentinel } from 'e2e-utils/ppr'
const isAdapterTest = Boolean(process.env.NEXT_ENABLE_ADAPTER)
describe('partial-fallback-root-blocking', () => {
const { next, isNextDev, isNextDeploy } = nextTestSetup({
files: __dirname,
// 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
}
async function fetchSplitHTML(pathname: string) {
let response: Awaited<ReturnType<typeof next.fetch>> | undefined
const [staticPart, dynamicPart] = await splitResponseWithPPRSentinel(
async () => {
response = await next.fetch(pathname)
expect(response.status).toBe(200)
if (!response.body) {
throw new Error(`Expected a streamed response body for ${pathname}`)
}
return response.body
}
)
return {
response: response!,
staticPart,
dynamicPart,
static$: cheerio.load(staticPart),
}
}
// TODO: Re-enable once infra supports multiple layers of fallbacks
if (!isNextDeploy) {
it('should not reuse a shared shell cache entry for unknown root branches', async () => {
const firstResult = await fetchSplitHTML('/fr/two')
expect(firstResult.response.status).toBe(200)
expect(firstResult.static$('#lang-fallback').length).toBe(0)
expect(firstResult.static$('#lang').text()).toBe('fr')
expect(firstResult.static$('#slug').text()).toBe('two')
expect(firstResult.dynamicPart).toBe('')
const secondResult = await fetchSplitHTML('/fr/other')
expect(secondResult.response.status).toBe(200)
expect(secondResult.static$('#lang-fallback').length).toBe(0)
expect(secondResult.static$('#lang').text()).toBe('fr')
expect(secondResult.static$('#slug').text()).toBe('other')
expect(secondResult.dynamicPart).toBe('')
})
}
it('should still serve a fallback shell for generated root branches', async () => {
const result = await fetchSplitHTML('/en/two')
expect(result.response.status).toBe(200)
expect(result.static$('#lang').text()).toBe('en')
expect(result.static$('#lang-fallback').length).toBe(0)
expect(result.static$('#slug-fallback').text()).toBe('loading slug...')
expect(result.static$('#slug').length).toBe(0)
expect(result.dynamicPart).toContain('<div id="slug">two</div>')
})
})
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>
)
}
import cheerio from 'cheerio'
import { nextTestSetup } from 'e2e-utils' import { nextTestSetup } from 'e2e-utils'
import { splitResponseWithPPRSentinel } from 'e2e-utils/ppr'
import { retry } from 'next-test-utils' import { retry } from 'next-test-utils'
const isAdapterTest = Boolean(process.env.NEXT_ENABLE_ADAPTER) const isAdapterTest = Boolean(process.env.NEXT_ENABLE_ADAPTER)
describe('partial-fallback-shell-upgrade', () => { describe('partial-fallback-shell-upgrade', () => {
const { next, isNextDev } = nextTestSetup({ const { next, isNextDev, isNextDeploy } = nextTestSetup({
files: __dirname, files: __dirname,
// The latest changes to support this behavior on deployed infra are available in the adapter, // The latest changes to support this behavior on deployed infra are available in the adapter,
// and are not being backported to the CLI // and are not being backported to the CLI
...@@ -16,6 +18,29 @@ describe('partial-fallback-shell-upgrade', () => { ...@@ -16,6 +18,29 @@ describe('partial-fallback-shell-upgrade', () => {
return return
} }
async function fetchSplitHTML(pathname: string) {
let response: Awaited<ReturnType<typeof next.fetch>> | undefined
const [staticPart, dynamicPart] = await splitResponseWithPPRSentinel(
async () => {
response = await next.fetch(pathname)
expect(response.status).toBe(200)
if (!response.body) {
throw new Error(`Expected a streamed response body for ${pathname}`)
}
return response.body
}
)
return {
response: response!,
staticPart,
dynamicPart,
static$: cheerio.load(staticPart),
}
}
it('should upgrade the fallback shell to a route shell', async () => { it('should upgrade the fallback shell to a route shell', async () => {
const pathname = '/two' const pathname = '/two'
let $ = await next.render$(pathname) let $ = await next.render$(pathname)
...@@ -48,4 +73,72 @@ describe('partial-fallback-shell-upgrade', () => { ...@@ -48,4 +73,72 @@ describe('partial-fallback-shell-upgrade', () => {
'no-gsp fallback shell should remain unupgraded' 'no-gsp fallback shell should remain unupgraded'
) )
}) })
// TODO: Re-enable once infra supports multiple layers of fallbacks
if (!isNextDeploy) {
it('should upgrade a generic shell into the most specific prerendered 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.static$('#two-fallback').length).toBe(0)
expect(firstResult.static$('#two').length).toBe(0)
expect(firstResult.dynamicPart).toContain('<div id="one">c</div>')
expect(firstResult.dynamicPart).toContain('<div id="two">foo</div>')
await retry(async () => {
const secondResult = await fetchSplitHTML('/prefix/c/bar')
expect(secondResult.response.status).toBe(200)
expect(secondResult.static$('#one').text()).toBe('c')
expect(secondResult.static$('#one-fallback').length).toBe(0)
expect(secondResult.static$('#two-fallback').text()).toBe(
'loading two...'
)
expect(secondResult.static$('#two').length).toBe(0)
expect(secondResult.dynamicPart).toContain('<div id="two">bar</div>')
expect(secondResult.dynamicPart).not.toContain(
'<div id="two">foo</div>'
)
})
})
it('should not keep upgrading once only fully dynamic params remain', async () => {
const firstResult = await fetchSplitHTML('/prefix/b/foo')
const start = Date.now()
expect(firstResult.response.status).toBe(200)
expect(firstResult.static$('#one').text()).toBe('b')
expect(firstResult.static$('#one-fallback').length).toBe(0)
expect(firstResult.static$('#two-fallback').text()).toBe('loading two...')
expect(firstResult.static$('#two').length).toBe(0)
expect(firstResult.dynamicPart).toContain('<div id="two">foo</div>')
await retry(
async () => {
const secondResult = await fetchSplitHTML('/prefix/b/bar')
expect(secondResult.response.status).toBe(200)
expect(secondResult.static$('#one').text()).toBe('b')
expect(secondResult.static$('#one-fallback').length).toBe(0)
expect(secondResult.static$('#two-fallback').text()).toBe(
'loading two...'
)
expect(secondResult.static$('#two').length).toBe(0)
expect(secondResult.dynamicPart).toContain('<div id="two">bar</div>')
expect(secondResult.dynamicPart).not.toContain(
'<div id="two">foo</div>'
)
if (Date.now() - start < 5000) {
throw new Error('continue polling more complete shell')
}
},
6000,
500,
'shell should remain partial when remaining params are dynamic'
)
})
}
}) })
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