Unverified Commit 2690ad49 authored by Andrew Clark's avatar Andrew Clark Committed by GitHub

Record fallback cache lifetime for blocking PPR routes (#97821)

A dynamic route that can't serve an HTML fallback (`fallback: null`,
e.g. because its cached shell is keyed on the route params) still
produces cacheable fallback artifacts during the build: the per-segment
prefetch payloads served to the client Segment Cache, and the RSC
template. Previously the prerender manifest only recorded
fallbackRevalidate/fallbackExpire when the HTML fallback itself was
servable, so these routes shipped their segment and .rsc outputs with no
lifetime at all.

Cache layers interpret a missing revalidate as a 1-second lifetime —
both deployment infrastructure and the self-hosted incremental cache
(calculateRevalidate). The result is that every segment entry for such a
route goes stale one second after it's written, so nearly every prefetch
of a non-prerendered URL serves stale, triggers a background
revalidation, and writes a new cache entry. On a site with dynamic
product/listing routes and default viewport prefetching, this amplifies
into millions of cache writes per hour.

The build already computes the correct lifetime: the export's collected
cache control, which describes exactly the caches that completed into
the fallback artifacts. The manifest now records it for every PPR route
regardless of fallback mode, and the adapter's segment and RSC template
outputs fall back to the manifest values when there's no HTML fallback
output to inherit them from. When the export collected no cache control,
the lifetime is `false` (keep until invalidated), matching how servable
fallbacks are already treated.

fallbackStatus and fallbackHeaders remain gated on the PRERENDER
fallback mode because they describe the prerendered fallback response
itself, which doesn't exist for blocking routes.
parent 9480f67d
...@@ -1261,6 +1261,14 @@ export async function handleBuildComplete({ ...@@ -1261,6 +1261,14 @@ export async function handleBuildComplete({
ctx: { ctx: {
htmlAllowQuery?: string[] htmlAllowQuery?: string[]
dataAllowQuery?: string[] dataAllowQuery?: string[]
// The cache lifetime of the route's fallback artifacts, from the
// prerender manifest. Segment outputs attach this when the route
// has no HTML fallback output to inherit it from (a blocking
// route): the segment payloads are cached and served even then,
// and platforms interpret a missing revalidate as a 1-second
// lifetime, so segment outputs must always carry one.
fallbackRevalidate?: Revalidate
fallbackExpire?: number
} }
) => { ) => {
if (meta.postponed && initialOutput.fallback) { if (meta.postponed && initialOutput.fallback) {
...@@ -1326,8 +1334,12 @@ export async function handleBuildComplete({ ...@@ -1326,8 +1334,12 @@ export async function handleBuildComplete({
fallback: { fallback: {
filePath: fallbackPathname, filePath: fallbackPathname,
postponedState: undefined, postponedState: undefined,
initialExpiration: initialOutput.fallback?.initialExpiration, initialExpiration:
initialRevalidate: initialOutput.fallback?.initialRevalidate, initialOutput.fallback?.initialExpiration ??
ctx.fallbackExpire,
initialRevalidate:
initialOutput.fallback?.initialRevalidate ??
ctx.fallbackRevalidate,
initialHeaders: { initialHeaders: {
...meta.headers, ...meta.headers,
...@@ -1927,6 +1939,8 @@ export async function handleBuildComplete({ ...@@ -1927,6 +1939,8 @@ export async function handleBuildComplete({
await handleAppMeta(dynamicRoute, initialOutput, meta, { await handleAppMeta(dynamicRoute, initialOutput, meta, {
htmlAllowQuery, htmlAllowQuery,
dataAllowQuery, dataAllowQuery,
fallbackRevalidate,
fallbackExpire,
}) })
} }
...@@ -1940,6 +1954,15 @@ export async function handleBuildComplete({ ...@@ -1940,6 +1954,15 @@ export async function handleBuildComplete({
filePath: undefined, filePath: undefined,
postponedState: meta.postponed, postponedState: meta.postponed,
initialStatus: undefined, initialStatus: undefined,
// A blocking route has no HTML fallback to spread these
// from, but its on-demand RSC template renders are still
// cached, so give those entries the lifetime recorded in
// the prerender manifest.
initialExpiration:
initialOutput.fallback?.initialExpiration ?? fallbackExpire,
initialRevalidate:
initialOutput.fallback?.initialRevalidate ??
fallbackRevalidate,
initialHeaders: { initialHeaders: {
...initialOutput.fallback?.initialHeaders, ...initialOutput.fallback?.initialHeaders,
...dataInitialHeaders, ...dataInitialHeaders,
......
...@@ -3828,20 +3828,33 @@ export default async function build( ...@@ -3828,20 +3828,33 @@ export default async function build(
routeResult?.hasEmptyStaticShell routeResult?.hasEmptyStaticShell
) )
// When the route is configured to serve a prerender, we should // The cache lifetime collected while prerendering this route's
// use the cache control from the export result. If it can't be // fallback. It's recorded for every PPR route, not just those
// found, mark that we should keep the shell forever // that serve an HTML fallback: the fallback prerender runs
// (revalidate: `false` via `getCacheControl()`). // either way, and the artifacts it produces — the per-segment
const fallbackCacheControl = // prefetch payloads and the RSC template — are cached and
isRoutePPREnabled && fallbackMode === FallbackMode.PRERENDER // served even when the HTML fallback itself is not
? cacheControl // (`fallback: null`, blocking). Cache layers use this value to
: undefined // decide when entries for URLs without their own prerender go
// stale, and they interpret a missing value as a 1-second
// lifetime, so it must be present whenever such entries can
// exist. When the export collected no cache control,
// `getCacheControl()` returns revalidate: `false` (keep until
// invalidated).
const fallbackCacheControl = isRoutePPREnabled
? cacheControl
: undefined
const fallback: Fallback = fallbackModeToFallbackField( const fallback: Fallback = fallbackModeToFallbackField(
fallbackMode, fallbackMode,
route.pathname route.pathname
) )
// Unlike the cache lifetime above, the status and headers
// describe the prerendered fallback response itself, so they
// only apply when a fallback is actually served (PRERENDER
// mode). A blocking route's on-demand renders produce their
// own status and headers per request.
const meta = const meta =
metadata && metadata &&
isRoutePPREnabled && isRoutePPREnabled &&
......
...@@ -490,4 +490,65 @@ describe('adapter-prerender-metadata', () => { ...@@ -490,4 +490,65 @@ describe('adapter-prerender-metadata', () => {
expectUnclassified(segment) expectUnclassified(segment)
} }
}) })
it('records the fallback lifetime for blocking dynamic routes', async () => {
// A route whose cached shell is keyed on its params serves no HTML
// fallback (`fallback: null`), but its per-segment prefetch payloads and
// RSC template are still served and cached. The manifest must carry the
// shell's cache lifetime so consumers don't fall back to their
// 1-second default.
const manifest = await getPrerenderManifest()
expect(manifest.dynamicRoutes['/blocking-cached/[id]']).toMatchObject({
fallback: null,
fallbackRevalidate: 3600,
fallbackExpire: 86400,
})
})
it('gives segment outputs of a blocking route the shell cache lifetime', async () => {
const prerenders = await getPrerenders()
const segments = prerenders.filter((output) =>
output.pathname.startsWith('/blocking-cached/[id].segments/')
)
expect(segments.length).toBeGreaterThan(0)
for (const segment of segments) {
expect(segment.fallback.initialRevalidate).toBe(3600)
expect(segment.fallback.initialExpiration).toBe(86400)
}
const templateRsc = prerenders.find(
(output) => output.pathname === '/blocking-cached/[id].rsc'
)
expect(templateRsc).toBeDefined()
expect(templateRsc.fallback.initialRevalidate).toBe(3600)
expect(templateRsc.fallback.initialExpiration).toBe(86400)
// Concrete generated paths carry the same lifetime through the
// routes manifest.
const concreteSegments = prerenders.filter((output) =>
output.pathname.startsWith('/blocking-cached/known.segments/')
)
expect(concreteSegments.length).toBeGreaterThan(0)
for (const segment of concreteSegments) {
expect(segment.fallback.initialRevalidate).toBe(3600)
expect(segment.fallback.initialExpiration).toBe(86400)
}
})
it('never emits a segment output without a revalidate lifetime', async () => {
// Regression test: segment outputs used to inherit the revalidate of the
// route's HTML fallback, which doesn't exist for blocking routes. The
// resulting `undefined` was interpreted downstream as a 1-second TTL,
// causing an ISR cache write on nearly every prefetch of a
// non-prerendered URL.
const prerenders = await getPrerenders()
const segments = prerenders.filter((output) =>
output.pathname.includes('.segments/')
)
expect(segments.length).toBeGreaterThan(0)
for (const segment of segments) {
expect(segment.fallback.initialRevalidate).toBeDefined()
}
})
}) })
import { Suspense } from 'react'
import { cookies } from 'next/headers'
import { cacheLife } from 'next/cache'
// A dynamic route whose cached shell is keyed on its params. The fallback
// shell prerender suspends at the shell, so no HTML fallback is emitted
// (`fallback: null`, blocking) — but per-segment prefetch payloads are still
// written and served, and their lifetime must reflect the cache lifetimes
// collected during the fallback prerender (the layout's CachedBanner).
async function Shell({
params,
children,
}: {
params: Promise<{ id: string }>
children: React.ReactNode
}) {
'use cache'
// Same lifetime as the layout's CachedBanner, so the concrete generated
// path (which collects both caches) agrees with the fallback export
// (which only collects the banner).
cacheLife({ stale: 300, revalidate: 3600, expire: 86400 })
const { id } = await params
return (
<div>
<h1>Shell for {id}</h1>
{children}
</div>
)
}
async function Dynamic() {
const jar = await cookies()
return <p>session: {jar.get('session')?.value ?? 'anon'}</p>
}
export async function generateStaticParams() {
return [{ id: 'known' }]
}
export default async function Page({
params,
}: {
params: Promise<{ id: string }>
}) {
return (
<Shell params={params}>
<Suspense fallback={<p>loading…</p>}>
<Dynamic />
</Suspense>
</Shell>
)
}
import { ReactNode } from 'react'
import { cacheLife } from 'next/cache'
// A cached component that completes during the fallback shell prerender (it
// doesn't read params), so its cacheLife propagates to the collected cache
// control of the fallback export.
async function CachedBanner() {
'use cache'
cacheLife({ stale: 300, revalidate: 3600, expire: 86400 })
return <p>banner</p>
}
export default function Layout({ children }: { children: ReactNode }) {
return (
<>
<CachedBanner />
{children}
</>
)
}
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