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

partial fallbacks: adapter support for intermediate shells (#91902)

Previously, `partialFallback` was only emitted when all dynamic params
could become fully concrete after upgrade. For a route like
`/prefix/[one]/[two]` where only `[one]` has generateStaticParams, the
feature was disabled entirely.

This relaxes the guard to allow adapters to produce an intermediate
shell for not fully known params, and tweaks the handling to support
when both known and unknown params are provided to the render.
Concretely:

- When partial `nxtP*` params are provided during background
revalidation but `normalizeDynamicRouteParams `rejects them (missing
params), merge the provided params into the existing params to override
placeholders.
- Compute `effectiveFallbackRouteParams` by filtering to only params
that still have placeholder values. Use this filtered set for
`fallbackRouteParams` so intermediate shells render resolved params in
the static shell and only suspend for truly unknown params
parent faa4b992
......@@ -1638,16 +1638,8 @@ export async function handleBuildComplete({
typeof fallback === 'string' &&
Boolean(meta.postponed)
// Today, consumers of this build output can only upgrade a fallback shell
// when all remaining route params become concrete in the upgraded entry.
// They cannot yet represent intermediate shells like `/[foo]/[bar] -> /foo/[bar]`,
// because we do not emit which fallback params should remain deferred after
// the upgrade. Until that contract exists, only emit `partialFallback` for
// the conservative case where the upgraded entry can become fully concrete.
const canEmitPartialFallback =
partialFallback &&
fallbackRootParams?.length === 0 &&
allowQuery.length === remainingPrerenderableParams?.length
partialFallback && fallbackRootParams?.length === 0
let htmlAllowQuery = allowQuery
// We only want to vary on the shell contents if there is a fallback
......
......@@ -1338,6 +1338,21 @@ export async function handler(
}
}
// When route-module.ts resolved partial nxtP* params during
// background revalidation, filter fallbackRouteParams to only the
// params that are still unresolved. This lets doRender produce an
// intermediate PPR shell that suspends only for those params.
let effectiveFallbackRouteParams: FallbackRouteParam[] | null = null
if (nextConfig.cacheComponents && prerenderInfo?.fallbackRouteParams) {
const resolvedKeys = getRequestMeta(req, 'resolvedRouteParamKeys')
if (resolvedKeys && resolvedKeys.size > 0) {
effectiveFallbackRouteParams =
prerenderInfo.fallbackRouteParams.filter(
(param) => !resolvedKeys.has(param.paramName)
)
}
}
const fallbackRouteParams =
// In production or when debugging the static shell for a
// non-prerendered URL, use the prerender manifest's fallback route
......@@ -1346,9 +1361,17 @@ export async function handler(
(isDebugStaticShell && !isPrerendered)) &&
prerenderInfo?.fallbackRouteParams
? createOpaqueFallbackRouteParams(prerenderInfo.fallbackRouteParams)
: isDebugFallbackShell
? getFallbackRouteParams(normalizedSrcPage, routeModule)
: null
: // For intermediate shells where some params are resolved and
// others still have placeholders, use the filtered subset so the
// prerender suspends only for the unresolved params.
effectiveFallbackRouteParams &&
effectiveFallbackRouteParams.length > 0 &&
effectiveFallbackRouteParams.length <
(prerenderInfo?.fallbackRouteParams?.length ?? 0)
? createOpaqueFallbackRouteParams(effectiveFallbackRouteParams)
: isDebugFallbackShell
? getFallbackRouteParams(normalizedSrcPage, routeModule)
: null
// For staged dynamic rendering (Cached Navigations) and debug static
// shell rendering, pass the fallback params via request meta so the
......
......@@ -220,6 +220,14 @@ export interface RequestMeta {
*/
renderFallbackShell?: boolean
/**
* Route param keys that were explicitly resolved from partial nxtP*
* query params during background revalidation. Used by app-page.ts to
* determine which fallback params should remain deferred vs resolved
* in intermediate PPR shells.
*/
resolvedRouteParamKeys?: Set<string>
/**
* Whether the request is for the custom error page.
*/
......
......@@ -916,6 +916,26 @@ export abstract class RouteModule<
}
}
}
// When partial nxtP* params are provided (e.g. background
// revalidation for intermediate PPR shells), both
// normalizeDynamicRouteParams calls above fail because not all
// route params are present. Merge the normalized query params
// (from nxtP*) into the current params to override placeholders
// with concrete values.
if (
params &&
routeParamKeys.size > 0 &&
!paramsResult.hasValidParams &&
!queryResult.hasValidParams
) {
for (const key of routeParamKeys) {
if (query[key] !== undefined) {
params[key] = query[key]
}
}
addRequestMeta(req, 'resolvedRouteParamKeys', routeParamKeys)
}
}
// Remove any normalized params from the query if they
......
......@@ -6,7 +6,7 @@ import { retry } from 'next-test-utils'
const isAdapterTest = Boolean(process.env.NEXT_ENABLE_ADAPTER)
describe('partial-fallback-shell-upgrade', () => {
const { next, isNextDev, isNextDeploy } = nextTestSetup({
const { next, isNextDev } = 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
......@@ -74,24 +74,49 @@ describe('partial-fallback-shell-upgrade', () => {
)
})
// 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')
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>')
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')
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('c')
expect(secondResult.static$('#one').text()).toBe('b')
expect(secondResult.static$('#one-fallback').length).toBe(0)
expect(secondResult.static$('#two-fallback').text()).toBe(
'loading two...'
......@@ -101,44 +126,14 @@ describe('partial-fallback-shell-upgrade', () => {
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'
)
})
}
if (Date.now() - start < 5000) {
throw new Error('continue polling more complete shell')
}
},
6000,
500,
'shell should remain partial when remaining params are dynamic'
)
})
})
......@@ -42,14 +42,14 @@ describe('adapter-partial-fallback', () => {
expect(withoutGspPrerender.config.partialFallback).toBeUndefined()
expect(withoutGspPrerender.config.allowQuery).toEqual([])
expect(genericPrefixPrerender.config.partialFallback).toBeUndefined()
expect(genericPrefixPrerender.config.allowQuery).toEqual([])
expect(genericPrefixPrerender.config.partialFallback).toBe(true)
expect(genericPrefixPrerender.config.allowQuery).toEqual(['nxtPone'])
expect(generatedPrefixPrerender.config.partialFallback).toBeUndefined()
expect(generatedPrefixPrerender.config.allowQuery).toEqual([])
expect(genericDashedPrerender.config.partialFallback).toBeUndefined()
expect(genericDashedPrerender.config.allowQuery).toEqual([])
expect(genericDashedPrerender.config.partialFallback).toBe(true)
expect(genericDashedPrerender.config.allowQuery).toEqual(['nxtPmy-slug'])
expect(generatedDashedPrerender.config.partialFallback).toBeUndefined()
expect(generatedDashedPrerender.config.allowQuery).toEqual([])
......
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