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

fix: preserve cache behavior for PPR fallback shells with root params (#88556)

When generating PPR fallback shells, a cache miss during warmup was
being treated as a dynamic hole, so the warmup render never filled new
cache entries. This caused root‑param fallback shells (e.g.
`/en/blog/[slug]`) to suspend even though root params were already
known.

This change always creates a fresh prerender RDC for warmup and copies
any seed hits into it. The final render then uses the warmed cache, so
fallback shells can reuse populated entries without short‑circuiting. On
the export side, we now choose a seed RDC by matching known params (e.g.
locale) so /en/... fallback shells don’t get seeded with /fr/... data.
(Previously, the RDC seed was "last-write-wins".

Fixes NAR-716
parent 3fe7d63f
...@@ -979,5 +979,6 @@ ...@@ -979,5 +979,6 @@
"978": "Next.js has blocked a javascript: URL as a security precaution.", "978": "Next.js has blocked a javascript: URL as a security precaution.",
"979": "invariant: expected %s bytes of postponed state but only received %s bytes", "979": "invariant: expected %s bytes of postponed state but only received %s bytes",
"980": "Failed to load client middleware manifest", "980": "Failed to load client middleware manifest",
"981": "resolvedPathname must be set in request metadata" "981": "resolvedPathname must be set in request metadata",
"982": "`serializeResumeDataCache` should not be called in edge runtime."
} }
...@@ -69,11 +69,125 @@ import type { ActionManifest } from '../build/webpack/plugins/flight-client-entr ...@@ -69,11 +69,125 @@ import type { ActionManifest } from '../build/webpack/plugins/flight-client-entr
import { extractInfoFromServerReferenceId } from '../shared/lib/server-reference-info' import { extractInfoFromServerReferenceId } from '../shared/lib/server-reference-info'
import { convertSegmentPathToStaticExportFilename } from '../shared/lib/segment-cache/segment-value-encoding' import { convertSegmentPathToStaticExportFilename } from '../shared/lib/segment-cache/segment-value-encoding'
import { getNextBuildDebuggerPortOffset } from '../lib/worker' import { getNextBuildDebuggerPortOffset } from '../lib/worker'
import { getParams } from './helpers/get-params'
import { isDynamicRoute } from '../shared/lib/router/utils/is-dynamic'
import { normalizeAppPath } from '../shared/lib/router/utils/app-paths'
import type { Params } from '../server/request/params'
export class ExportError extends Error { export class ExportError extends Error {
code = 'NEXT_EXPORT_ERROR' code = 'NEXT_EXPORT_ERROR'
} }
/**
* Picks an RDC seed by matching on the params that are
* already known, so fallback shells use a seed that has already
* computed those known params.
*/
function buildRDCCacheByPage(
results: ExportPagesResult,
finalPhaseExportPaths: ExportPathEntry[]
): Record<string, string> {
const renderResumeDataCachesByPage: Record<string, string> = {}
const seedCandidatesByPage = new Map<
string,
Array<{ path: string; renderResumeDataCache: string }>
>()
for (const { page, path, result } of results) {
if (!result) {
continue
}
if ('renderResumeDataCache' in result && result.renderResumeDataCache) {
// Collect all RDC seeds for this page so we can pick the best match
// for each fallback shell later (e.g. locale-specific variants).
const candidates = seedCandidatesByPage.get(page) ?? []
candidates.push({
path,
renderResumeDataCache: result.renderResumeDataCache,
})
seedCandidatesByPage.set(page, candidates)
// Remove the RDC string from the result so that it can be garbage
// collected, when there are more results for the same page.
result.renderResumeDataCache = undefined
}
}
const getKnownParamsKey = (
normalizedPage: string,
path: string,
fallbackParamNames: Set<string>
): string | null => {
let params: Params
try {
params = getParams(normalizedPage, path)
} catch {
return null
}
// Only keep params that are known, then sort
// for a stable key so we can match a compatible seed.
const entries = Object.entries(params).filter(
([key]) => !fallbackParamNames.has(key)
)
entries.sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))
return JSON.stringify(entries)
}
for (const exportPath of finalPhaseExportPaths) {
const { page, path, _fallbackRouteParams = [] } = exportPath
if (!isDynamicRoute(page)) {
continue
}
// Normalize app pages before param matching.
const normalizedPage = normalizeAppPath(page)
const pageKey = page !== path ? `${page}: ${path}` : path
const fallbackParamNames = new Set(
_fallbackRouteParams.map((param) => param.paramName)
)
// Build a key from the known params for this fallback shell so we can
// select a seed from a compatible prerendered route.
const targetKey = getKnownParamsKey(
normalizedPage,
path,
fallbackParamNames
)
if (!targetKey) {
continue
}
const candidates = seedCandidatesByPage.get(page)
// No suitable candidates, so there's no RDC seed to select
if (!candidates || candidates.length === 0) {
continue
}
let selected: string | null = null
for (const candidate of candidates) {
// Pick the seed whose known params match this fallback shell.
const candidateKey = getKnownParamsKey(
normalizedPage,
candidate.path,
fallbackParamNames
)
if (candidateKey === targetKey) {
selected = candidate.renderResumeDataCache
break
}
}
if (selected) {
renderResumeDataCachesByPage[pageKey] = selected
}
}
return renderResumeDataCachesByPage
}
async function exportAppImpl( async function exportAppImpl(
dir: string, dir: string,
options: Readonly<ExportAppOptions>, options: Readonly<ExportAppOptions>,
...@@ -664,23 +778,10 @@ async function exportAppImpl( ...@@ -664,23 +778,10 @@ async function exportAppImpl(
results = await exportPagesInBatches(worker, initialPhaseExportPaths) results = await exportPagesInBatches(worker, initialPhaseExportPaths)
if (finalPhaseExportPaths.length > 0) { if (finalPhaseExportPaths.length > 0) {
const renderResumeDataCachesByPage: Record<string, string> = {} const renderResumeDataCachesByPage = buildRDCCacheByPage(
results,
for (const { page, result } of results) { finalPhaseExportPaths
if (!result) { )
continue
}
if ('renderResumeDataCache' in result && result.renderResumeDataCache) {
// The last RDC for each page is used. We only need one. It should have
// all the entries that the fallback shell also needs. We don't need to
// merge them per page.
renderResumeDataCachesByPage[page] = result.renderResumeDataCache
// Remove the RDC string from the result so that it can be garbage
// collected, when there are more results for the same page.
result.renderResumeDataCache = undefined
}
}
const finalPhaseResults = await exportPagesInBatches( const finalPhaseResults = await exportPagesInBatches(
worker, worker,
......
...@@ -388,9 +388,9 @@ export async function exportPages( ...@@ -388,9 +388,9 @@ export async function exportPages(
// Also tests for `inspect-brk` // Also tests for `inspect-brk`
process.env.NODE_OPTIONS?.includes('--inspect') process.env.NODE_OPTIONS?.includes('--inspect')
const renderResumeDataCache = renderResumeDataCachesByPage[page] const renderResumeDataCache = renderResumeDataCachesByPage[pageKey]
? createRenderResumeDataCache( ? createRenderResumeDataCache(
renderResumeDataCachesByPage[page], renderResumeDataCachesByPage[pageKey],
renderOpts.experimental.maxPostponedStateSizeBytes renderOpts.experimental.maxPostponedStateSizeBytes
) )
: undefined : undefined
......
...@@ -4276,22 +4276,11 @@ async function prerenderToStream( ...@@ -4276,22 +4276,11 @@ async function prerenderToStream(
// to cut the render off. // to cut the render off.
const cacheSignal = new CacheSignal() const cacheSignal = new CacheSignal()
let resumeDataCache: RenderResumeDataCache | PrerenderResumeDataCache // Always start with a fresh prerender RDC so warmup can fill misses,
let renderResumeDataCache: RenderResumeDataCache | null = null // even when we have a prefilled render RDC to seed from.
let prerenderResumeDataCache: PrerenderResumeDataCache | null = null const prerenderResumeDataCache = createPrerenderResumeDataCache()
let renderResumeDataCache: RenderResumeDataCache | null =
if (renderOpts.renderResumeDataCache) { renderOpts.renderResumeDataCache ?? null
// If a prefilled immutable render resume data cache is provided, e.g.
// when prerendering an optional fallback shell after having prerendered
// pages with defined params, we use this instead of a prerender resume
// data cache.
resumeDataCache = renderResumeDataCache =
renderOpts.renderResumeDataCache
} else {
// Otherwise we create a new mutable prerender resume data cache.
resumeDataCache = prerenderResumeDataCache =
createPrerenderResumeDataCache()
}
const initialServerPayloadPrerenderStore: PrerenderStore = { const initialServerPayloadPrerenderStore: PrerenderStore = {
type: 'prerender', type: 'prerender',
...@@ -4561,6 +4550,13 @@ async function prerenderToStream( ...@@ -4561,6 +4550,13 @@ async function prerenderToStream(
initialClientReactController.abort() initialClientReactController.abort()
} }
if (renderOpts.renderResumeDataCache) {
// Swap to the warmed cache so the final render uses entries produced during warmup.
renderResumeDataCache = createRenderResumeDataCache(
prerenderResumeDataCache
)
}
const finalServerReactController = new AbortController() const finalServerReactController = new AbortController()
const finalServerRenderController = new AbortController() const finalServerRenderController = new AbortController()
...@@ -4827,13 +4823,13 @@ async function prerenderToStream( ...@@ -4827,13 +4823,13 @@ async function prerenderToStream(
? DynamicHTMLPreludeState.Empty ? DynamicHTMLPreludeState.Empty
: DynamicHTMLPreludeState.Full, : DynamicHTMLPreludeState.Full,
fallbackRouteParams, fallbackRouteParams,
resumeDataCache, prerenderResumeDataCache,
cacheComponents cacheComponents
) )
} else { } else {
// Dynamic Data case // Dynamic Data case
metadata.postponed = await getDynamicDataPostponedState( metadata.postponed = await getDynamicDataPostponedState(
resumeDataCache, prerenderResumeDataCache,
cacheComponents cacheComponents
) )
} }
...@@ -4855,7 +4851,9 @@ async function prerenderToStream( ...@@ -4855,7 +4851,9 @@ async function prerenderToStream(
collectedExpire: finalServerPrerenderStore.expire, collectedExpire: finalServerPrerenderStore.expire,
collectedStale: selectStaleTime(finalServerPrerenderStore.stale), collectedStale: selectStaleTime(finalServerPrerenderStore.stale),
collectedTags: finalServerPrerenderStore.tags, collectedTags: finalServerPrerenderStore.tags,
renderResumeDataCache: createRenderResumeDataCache(resumeDataCache), renderResumeDataCache: createRenderResumeDataCache(
prerenderResumeDataCache
),
} }
} else { } else {
// Static case // Static case
...@@ -4972,7 +4970,9 @@ async function prerenderToStream( ...@@ -4972,7 +4970,9 @@ async function prerenderToStream(
collectedExpire: finalServerPrerenderStore.expire, collectedExpire: finalServerPrerenderStore.expire,
collectedStale: selectStaleTime(finalServerPrerenderStore.stale), collectedStale: selectStaleTime(finalServerPrerenderStore.stale),
collectedTags: finalServerPrerenderStore.tags, collectedTags: finalServerPrerenderStore.tags,
renderResumeDataCache: createRenderResumeDataCache(resumeDataCache), renderResumeDataCache: createRenderResumeDataCache(
prerenderResumeDataCache
),
} }
} }
} else if (experimental.isRoutePPREnabled) { } else if (experimental.isRoutePPREnabled) {
......
...@@ -620,7 +620,6 @@ async function generateCacheEntryImpl( ...@@ -620,7 +620,6 @@ async function generateCacheEntryImpl(
case 'prerender-runtime': case 'prerender-runtime':
case 'prerender': case 'prerender':
const timeoutAbortController = new AbortController() const timeoutAbortController = new AbortController()
// If we're prerendering, we give you 50 seconds to fill a cache entry. // If we're prerendering, we give you 50 seconds to fill a cache entry.
// Otherwise we assume you stalled on hanging input and de-opt. This needs // Otherwise we assume you stalled on hanging input and de-opt. This needs
// to be lower than just the general timeout of 60 seconds. // to be lower than just the general timeout of 60 seconds.
...@@ -1385,6 +1384,10 @@ export async function cache( ...@@ -1385,6 +1384,10 @@ export async function cache(
if (existingEntry !== undefined) { if (existingEntry !== undefined) {
debug?.('Resume Data Cache entry found', serializedCacheKey) debug?.('Resume Data Cache entry found', serializedCacheKey)
if (prerenderResumeDataCache) {
prerenderResumeDataCache.cache.set(serializedCacheKey, cachedEntry)
}
// We want to make sure we only propagate cache life & tags if the // We want to make sure we only propagate cache life & tags if the
// entry was *not* omitted from the prerender. So we only do this // entry was *not* omitted from the prerender. So we only do this
// after the above early returns. // after the above early returns.
......
import { Suspense } from 'react'
import { cookies } from 'next/headers'
import Link from 'next/link'
async function getBlogPost(locale: string, slug: string) {
'use cache'
await new Promise((resolve) => setTimeout(resolve, 700))
return {
title: `Blog Post: ${slug}`,
locale,
content: 'This content was fetched from the CMS...',
relatedPosts: ['Related Post 1', 'Related Post 2', 'Related Post 3'],
}
}
export default async function BlogPost({
params,
}: {
params: Promise<{ locale: string; slug: string }>
}) {
return (
<main>
<div id="static-blog-header">Blog Article</div>
<div id="static-reading-time">Estimated reading time: 5 minutes</div>
<Suspense fallback={<div id="blog-loading">Loading article...</div>}>
<BlogContent params={params} />
</Suspense>
<Suspense fallback={<div id="dynamic-loading">Loading comments...</div>}>
<DynamicComments />
</Suspense>
</main>
)
}
// This component depends on locale and slug, so it's in Suspense
async function BlogContent({
params,
}: {
params: Promise<{ locale: string; slug: string }>
}) {
const { locale, slug } = await params
const post = await getBlogPost(locale, slug)
return (
<>
<article id="blog-content">
<h1>{post.title}</h1>
<p>Locale: {post.locale}</p>
<p>{post.content}</p>
</article>
<aside id="related-posts">
<h2>Related Posts ({post.locale})</h2>
<ul>
{post.relatedPosts.map((title, i) => (
<li key={i}>
<Link href={`/en/blog/${i}`}>{title}</Link>
</li>
))}
</ul>
</aside>
</>
)
}
async function DynamicComments() {
const cookieStore = await cookies()
const user = cookieStore.get('user')?.value || 'anonymous'
return (
<section id="comments">
<h3>Comments</h3>
<p>Viewing as: {user}</p>
</section>
)
}
export function generateStaticParams() {
return [{ slug: 'hello-world' }, { slug: 'getting-started' }]
}
import { Suspense } from 'react'
import { cookies } from 'next/headers'
async function getLocaleConfig(localeParam: string) {
'use cache'
await new Promise((resolve) => setTimeout(resolve, 800))
return {
locale: localeParam,
translations: {
home: `Home (${localeParam})`,
blog: `Blog (${localeParam})`,
about: `About (${localeParam})`,
},
}
}
export default async function LocaleLayout({
children,
params,
}: {
children: React.ReactNode
params: Promise<{ locale: string }>
}) {
return (
<html>
<body>
<div id="static-header">Welcome to our Blog Platform</div>
<nav id="static-nav">
<ul>
<li>Home</li>
<li>Blog</li>
<li>About</li>
</ul>
</nav>
<Suspense
fallback={<div id="locale-loading">Loading locale info...</div>}
>
<LocaleInfo params={params} />
</Suspense>
<Suspense fallback={<div id="dynamic-loading">Loading user...</div>}>
<UserInfo />
</Suspense>
{children}
</body>
</html>
)
}
// This component depends on locale, so it's in Suspense
async function LocaleInfo({ params }: { params: Promise<{ locale: string }> }) {
const { locale } = await params
const config = await getLocaleConfig(locale)
return (
<header id="locale-header">
<span>Locale: {config.locale}</span>
<div id="translations">
{config.translations.home} | {config.translations.blog} |{' '}
{config.translations.about}
</div>
</header>
)
}
async function UserInfo() {
const cookieStore = await cookies()
const user = cookieStore.get('user')?.value || 'anonymous'
return <div id="user-info">Logged in as: {user}</div>
}
export function generateStaticParams() {
return [{ locale: 'en' }, { locale: 'fr' }]
}
export default function Home() {
return (
<main>
<div id="home-content">
<h1>Home</h1>
<p>Welcome!</p>
</div>
</main>
)
}
/**
* @type {import('next').NextConfig}
*/
const nextConfig = {
cacheComponents: true,
}
module.exports = nextConfig
import { nextTestSetup } from 'e2e-utils'
describe('ppr-root-param-fallback', () => {
const { next } = nextTestSetup({
files: __dirname,
})
it('should have use-cache content in fallback shells for all pregenerated locales', async () => {
// Setup: The app has a [locale] param with generateStaticParams returning
// ['en', 'fr'], and a nested /[locale]/blog/[slug] route. The layout uses
// a 'use cache' function to fetch locale-specific translations.
//
// This test ensures that we generate fallback shells with the correct locale
// filled in for all pregenerated locales.
for (const locale of ['en', 'fr']) {
// next.render$ doesn't stream, so we get just the shell content
const $ = await next.render$(`/${locale}/blog/new-post`)
// The shell should have the locale-header with cached content,
// NOT the locale-loading Suspense fallback
expect($('#locale-header').length).toBe(1)
expect($('#locale-header').text()).toContain(`Locale: ${locale}`)
expect($('#translations').text()).toContain(`Home (${locale})`)
// The Suspense fallback should NOT be in the shell
expect($('#locale-loading').length).toBe(0)
}
})
})
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