Unverified Commit 70407f12 authored by Andrew Clark's avatar Andrew Clark Committed by GitHub

Serve ISR fallback shells in response to prefetch requests (#94534)

Previously, a static segment prefetch that hit a route with an
unresolved ISR entry could not be served a fallback shell, so the
prefetch cache was left cold until the entry regenerated. This enables
prefetch requests to be served the ISR fallback shell immediately, so
the prefetch cache can be warmed right away instead of waiting.

Because the shell is only a partial response, the client retries the
prefetch a bounded number of times so it eventually warms the cache with
the full (concrete) response once the server finishes regenerating in
the background. Only shells that can actually be upgraded are retried —
a route with no generateStaticParams never upgrades, so its shell isn't
flagged and the client doesn't waste retries on it.

The new serving behavior is gated behind the experimental `appShells`
flag, so existing behavior is unchanged when it's off.

<!-- NEXT_JS_LLM_PR -->
parent 8b53fd61
......@@ -2955,6 +2955,10 @@ export default async function build(
_isDynamicError: isDynamicError,
_isAppDir: true,
_allowEmptyStaticShell: !route.throwOnEmptyStaticShell,
// A fallback shell can only be upgraded if at least one of
// its fallback params is a `generateStaticParams` candidate.
_isFallbackUpgradeable:
(route.remainingPrerenderableParams?.length ?? 0) > 0,
}
})
})
......
......@@ -891,6 +891,11 @@ export async function handler(
: {}),
cacheComponents: Boolean(nextConfig.cacheComponents),
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,
validationLevel:
nextConfig.experimental.instantInsights.validationLevel,
experimental: {
......
......@@ -137,6 +137,26 @@ export type PrefetchTask = {
*/
isCanceled: boolean
/**
* Tracks whether the task has attempted to upgrade a fallback ISR response
* to one based on concrete params.
*
* When the server serves an upgradeable fallback shell (the page hadn't been
* prerendered with concrete params yet, but the route can be upgraded), we
* poll the server a few times until the upgrade is complete, or until we
* reach a limit and give up.
*
* - `Empty`: no loop has run yet.
* - `Pending`: a loop is currently running.
* - `Fulfilled`: a loop completed and obtained the upgraded version.
* - `Rejected`: a loop ran but gave up (exhausted its retries, hit an error,
* or the task was canceled).
*
* To prevent against unbounded upgrade attempts, the loop is only attempted
* once per task, even a Link's prefetch is rescheduled many times.
*/
fallbackRetryStatus: EntryStatus
/**
* The callback passed to `router.prefetch`, if given.
*/
......@@ -289,6 +309,7 @@ export function schedulePrefetchTask(
fetchStrategy,
sortId: sortIdCounter++,
isCanceled: false,
fallbackRetryStatus: EntryStatus.Empty,
onInvalidate,
_heapIndex: -1,
}
......@@ -319,6 +340,8 @@ export function cancelPrefetchTask(task: PrefetchTask): void {
// We must also explicitly mark the task as canceled so that a blocked task
// does not get added back to the queue when it's pinged by the network.
task.isCanceled = true
// A running fallback-retry loop notices `isCanceled` when it next wakes and
// bails (settling its status to Rejected), so there's nothing to clean up here.
heapDelete(taskHeap, task)
if (process.env.__NEXT_EXPOSE_TESTING_API) {
// Call completion callback. In practice this shouldn't be reached for
......@@ -351,6 +374,11 @@ export function reschedulePrefetchTask(
task.isCanceled = false
task.phase = PrefetchPhase.RouteTree
// Note: fallback-retry state is deliberately NOT reset here. A retry loop runs
// at most once per task, even across reschedules, so a re-hover never starts a
// second loop. A loop already running simply continues (it only stops on
// cancel); `fallbackRetryStatus` never returns to `Empty` once it leaves it.
// Assign a new sort ID to move it ahead of all other tasks at the same
// priority level. (Higher sort IDs are processed first.)
task.sortId = sortIdCounter++
......@@ -967,7 +995,7 @@ function pingStaticHead(
),
parent: null,
}
pingSegmentBundle(now, route, task.key, route.metadata, segments)
pingSegmentBundle(now, task, route, task.key, route.metadata, segments)
}
function pingRuntimeHead(
......@@ -1639,6 +1667,7 @@ function pingRuntimePrefetches(
*/
function pingSegmentBundle(
now: number,
task: PrefetchTask,
route: FulfilledRouteCacheEntry,
routeKey: RouteCacheKey,
tree: RouteTree,
......@@ -1706,18 +1735,34 @@ function pingSegmentBundle(
node.entry = null
}
break
case EntryStatus.Fulfilled:
case EntryStatus.Fulfilled: {
// For shell entries (less specific than PPR), upgrade during the
// Speculative phase itself — no background deferral, since the
// whole point of the Speculative phase is to bring the cache up
// to the per-link-concrete tier. `isPartial` ensures a complete
// entry isn't re-fetched.
// Check if we should attempt to upgrade a fallback ISR response to
// a concrete version.
const isUpgradeableISRFallbackRetry =
nodeEntry.isUpgradeableISRFallback &&
// If the status is empty, then we haven't yet attempted to upgrade
// the fallback.
//
// If the status is fulfilled, then the fallback was
// successfully upgraded to a concrete version.
//
// Do not attempt to upgrade if the status is Pending or Rejected.
(task.fallbackRetryStatus === EntryStatus.Empty ||
task.fallbackRetryStatus === EntryStatus.Fulfilled)
if (
nodeEntry.isPartial &&
canNewFetchStrategyProvideMoreContent(
nodeEntry.fetchStrategy,
FetchStrategy.PPR
)
(nodeEntry.isPartial &&
canNewFetchStrategyProvideMoreContent(
nodeEntry.fetchStrategy,
FetchStrategy.PPR
)) ||
isUpgradeableISRFallbackRetry
) {
const revalidatingEntry = readOrCreateRevalidatingSegmentEntry(
now,
......@@ -1729,12 +1774,17 @@ function pingSegmentBundle(
node.entry = revalidatingEntry
needsFetch = true
} else {
// A non-empty revalidating entry means a request is already in
// flight (or recently settled), so we dedupe and don't issue a
// competing one — including for ISR-fallback upgrades, which then
// share the same revalidation across tasks.
node.entry = null
}
} else {
node.entry = null
}
break
}
default:
nodeEntry satisfies never
}
......@@ -1744,7 +1794,14 @@ function pingSegmentBundle(
return
}
spawnPrefetchSubtask(
fetchSegmentsOnCacheMiss(route, routeKey, tree, segments, segmentCount)
fetchSegmentsOnCacheMiss(
task,
route,
routeKey,
tree,
segments,
segmentCount
)
)
}
......@@ -1822,7 +1879,7 @@ function accumulateSegmentBundle(
parent: effectiveParent,
}
pingSegmentBundle(now, route, task.key, tree, segments)
pingSegmentBundle(now, task, route, task.key, tree, segments)
return null
}
......
......@@ -115,6 +115,10 @@ async function exportPageImpl(
// When true, attempt to run build-time instant validation for this export path.
_runInstantValidation: runInstantValidation = false,
// When true, a fallback shell for this path could later be upgraded to a
// concrete version (it has a `generateStaticParams` candidate param).
_isFallbackUpgradeable: isFallbackUpgradeable = false,
// Pull the original query out.
query: originalQuery = {},
} = exportPath
......@@ -270,6 +274,7 @@ async function exportPageImpl(
serveStreamingMetadata: true,
allowEmptyStaticShell,
runInstantValidation,
isFallbackUpgradeable,
renderResumeDataCache,
}
......
......@@ -9035,6 +9035,25 @@ async function collectSegmentData(
}
}
// Whether this render is a fallback shell, i.e. it was prerendered with
// unknown (opaque) route params rather than concrete ones. The per-segment
// responses generated below are stamped with this so the client knows to
// retry the prefetch — a more complete version may become available once
// the server's background regeneration finishes.
//
// Only flag the shell when it could actually be upgraded
// (`isFallbackUpgradeable`): at least one fallback param is a candidate
// enumerated by `generateStaticParams`. A route with no `generateStaticParams`
// never upgrades, so flagging it would trigger pointless client retries.
const fallbackRouteParams =
'fallbackRouteParams' in prerenderStore
? prerenderStore.fallbackRouteParams
: null
const isUpgradeableISRFallback =
fallbackRouteParams != null &&
fallbackRouteParams.size > 0 &&
renderOpts.isFallbackUpgradeable === true
// Pass the resolved hints so collectSegmentData can union them into
// the TreePrefetch. During the initial build the FlightRouterState in
// the buffer doesn't have inlining hints yet (they were just computed
......@@ -9047,7 +9066,8 @@ async function collectSegmentData(
clientModules,
serverConsumerManifest,
Boolean(renderOpts.experimental.prefetchInlining),
hints
hints,
isUpgradeableISRFallback
)
}
......
......@@ -94,6 +94,19 @@ export type TreePrefetch = {
export type SegmentPrefetchResponse = {
buildId: string
data: Array<SegmentPrefetch | null>
/**
* True if this response was generated from a fallback shell render (i.e. the
* page had not yet been prerendered with concrete params, so it was rendered
* with `fallbackRouteParams`). The client uses this to schedule a retry,
* since a more complete version may become available once the server's
* background regeneration finishes.
*
* Note: this is distinct from per-segment `isPartial`. A fully-prerendered
* PPR page can have partial segments (dynamic holes filled by runtime
* requests); those should not be retried. `isUpgradeableISRFallback` specifically means a
* more complete *static* version may become available.
*/
isUpgradeableISRFallback: boolean
}
export type SegmentPrefetch = {
......@@ -187,7 +200,8 @@ export async function collectSegmentData(
clientModules: ManifestNode,
serverConsumerManifest: any,
prefetchInlining: boolean,
hints: PrefetchHints | null
hints: PrefetchHints | null,
isUpgradeableISRFallback: boolean
): Promise<Map<SegmentRequestKey, Buffer>> {
// Traverse the router tree and generate a prefetch response for each segment.
......@@ -237,6 +251,7 @@ export async function collectSegmentData(
onCompletedProcessingRouteTree={onCompletedProcessingRouteTree}
prefetchInlining={prefetchInlining}
hints={hints}
isUpgradeableISRFallback={isUpgradeableISRFallback}
/>,
clientModules,
{
......@@ -343,7 +358,10 @@ export async function collectPrefetchHints(
HEAD_REQUEST_KEY,
headVaryParams,
clientModules,
null
null,
// This pass only measures gzip sizes for inlining hints; fallback-ness
// doesn't affect size, so pass false.
false
)
const headGzipSize = await getGzipSize(headBuffer)
......@@ -456,7 +474,9 @@ async function collectPrefetchHintsImpl(
requestKey,
varyParams,
clientModules,
null
null,
// Size-measurement pass only; fallback-ness is irrelevant here.
false
)
currentGzipSize = await getGzipSize(buffer)
}
......@@ -673,6 +693,7 @@ async function PrefetchTreeData({
onCompletedProcessingRouteTree,
prefetchInlining,
hints,
isUpgradeableISRFallback,
}: {
isClientParamParsingEnabled: boolean
fullPageDataBuffer: Buffer
......@@ -683,6 +704,7 @@ async function PrefetchTreeData({
onCompletedProcessingRouteTree: () => void
prefetchInlining: boolean
hints: PrefetchHints | null
isUpgradeableISRFallback: boolean
}): Promise<RootTreePrefetch | null> {
// We're currently rendering a Flight response for the route tree prefetch.
// Inside this component, decode the Flight stream for the whole page. This is
......@@ -742,7 +764,8 @@ async function PrefetchTreeData({
hints,
null,
headBundle,
rootVaryParamsIterable
rootVaryParamsIterable,
isUpgradeableISRFallback
)
// Spawn a task to produce a prefetch response for the "head" segment,
......@@ -757,7 +780,8 @@ async function PrefetchTreeData({
HEAD_REQUEST_KEY,
headVaryParams,
clientModules,
null
null,
isUpgradeableISRFallback
)
)
)
......@@ -792,7 +816,8 @@ function collectSegmentDataImpl(
hintTree: PrefetchHints | null,
parentBundle: SegmentBundleNode | null,
headBundle: SegmentBundleNode | null,
rootVaryParamsIterable: VaryParamsIterable | null
rootVaryParamsIterable: VaryParamsIterable | null,
isUpgradeableISRFallback: boolean
): TreePrefetch {
// Union the hints already embedded in the FlightRouterState with the
// separately-computed build-time hints. During the initial build, the
......@@ -869,7 +894,8 @@ function collectSegmentDataImpl(
requestKey,
varyParams,
clientModules,
bundle
bundle,
isUpgradeableISRFallback
)
)
)
......@@ -913,7 +939,8 @@ function collectSegmentDataImpl(
childHintTree,
childBundle,
headBundle,
rootVaryParamsIterable
rootVaryParamsIterable,
isUpgradeableISRFallback
)
if (slotMetadata === null) {
slotMetadata = {}
......@@ -955,7 +982,8 @@ async function renderSegmentPrefetch(
requestKey: SegmentRequestKey,
varyParams: Set<string> | null,
clientModules: ManifestNode,
bundle: SegmentBundleNode | null
bundle: SegmentBundleNode | null,
isUpgradeableISRFallback: boolean
): Promise<[SegmentRequestKey, Buffer]> {
// Build the SegmentPrefetch for the terminal (requested) segment.
// The terminal always has non-null rsc data — disabled segments are
......@@ -992,9 +1020,13 @@ async function renderSegmentPrefetch(
}
// Wrap in the response envelope with the build ID at the top level.
// isUpgradeableISRFallback tells the client whether this came from a fallback shell
// render (so it knows to retry — a more complete version may become
// available once the server's background regeneration finishes).
const payload: SegmentPrefetchResponse = {
buildId: buildId ?? '',
data,
isUpgradeableISRFallback,
}
// Since all we're doing is decoding and re-encoding a cached prerender, if
// it takes longer than a microtask, it must because of hanging promises
......
......@@ -225,6 +225,15 @@ export interface RenderOptsPartial {
* instant.unstable_samples and is independent of actual route params.
*/
runInstantValidation?: boolean
/**
* When true, a fallback shell produced for this render could later be
* upgraded to a concrete version (at least one of its fallback params is a
* candidate enumerated by `generateStaticParams`). Only such shells are
* flagged `isUpgradeableISRFallback` so the client retries the prefetch; a route that
* can never upgrade (no `generateStaticParams`) is left unflagged.
*/
isFallbackUpgradeable?: boolean
}
export type RenderOpts = LoadComponentsReturnType<AppPageModule> &
......
......@@ -42,6 +42,7 @@ const zExportMap: zod.ZodType<ExportPathMap> = z.record(
_isAppDir: z.boolean().optional(),
_isDynamicError: z.boolean().optional(),
_allowEmptyStaticShell: z.boolean().optional(),
_isFallbackUpgradeable: z.boolean().optional(),
})
)
......
......@@ -1376,6 +1376,17 @@ export type ExportPathMap = {
* @internal
*/
_runInstantValidation?: boolean
/**
* When true, a fallback shell produced for this export path could later be
* upgraded to a concrete version (at least one fallback param is a
* `generateStaticParams` candidate). Threaded into
* `renderOpts.isFallbackUpgradeable` so the build-baked shell carries the
* gated `isUpgradeableISRFallback` value.
*
* @internal
*/
_isFallbackUpgradeable?: boolean
}
}
......
......@@ -204,6 +204,11 @@ export default class ResponseCache implements ResponseCacheBase {
routeKind: RouteKind
isOnDemandRevalidate?: boolean
isPrefetch?: boolean
/**
* Whether the `appShells` experimental flag is enabled. Gates the
* prefetch-miss-serves-fallback-shell behavior in `handleGet`.
*/
appShells?: boolean
incrementalCache: IncrementalResponseCache
isRoutePPREnabled?: boolean
isFallback?: boolean
......@@ -265,6 +270,7 @@ export default class ResponseCache implements ResponseCacheBase {
isFallback = false,
isRoutePPREnabled = false,
isPrefetch = false,
appShells = false,
waitUntil,
routeKind,
invocationID,
......@@ -282,6 +288,7 @@ export default class ResponseCache implements ResponseCacheBase {
isFallback,
isRoutePPREnabled,
isPrefetch,
appShells,
routeKind,
invocationID,
},
......@@ -324,6 +331,7 @@ export default class ResponseCache implements ResponseCacheBase {
isFallback: boolean
isRoutePPREnabled: boolean
isPrefetch: boolean
appShells: boolean
routeKind: RouteKind
invocationID: string | undefined
},
......@@ -362,16 +370,42 @@ export default class ResponseCache implements ResponseCacheBase {
}
}
// Revalidate the cache entry
const incrementalResponseCacheEntry = await this.revalidate(
key,
context.incrementalCache,
context.isRoutePPREnabled,
context.isFallback,
responseGenerator,
previousIncrementalCacheEntry,
resolved
)
// Revalidate the cache entry.
//
// A prefetch request that missed must run its own response generator
// rather than joining an in-flight revalidation through the batcher. A
// background revalidation may be regenerating the concrete (non-fallback)
// entry for this route — e.g. an ISR fallback-shell upgrade scheduled by
// an earlier prefetch sub-request. Joining it would serve that concrete
// result to the prefetch instead of the fallback shell, and which segment
// wins would depend purely on request timing. Running the generator
// directly lets every prefetch segment take the same fallback-shell path,
// independent of any concurrent background upgrade.
//
// Gated on `appShells`: with the flag off, prefetch misses keep the
// previous batch-join behavior so existing suites are unaffected.
const incrementalResponseCacheEntry =
context.isPrefetch &&
context.appShells &&
previousIncrementalCacheEntry === null
? await this.handleRevalidate(
key,
context.incrementalCache,
context.isRoutePPREnabled,
context.isFallback,
responseGenerator,
previousIncrementalCacheEntry,
resolved
)
: await this.revalidate(
key,
context.incrementalCache,
context.isRoutePPREnabled,
context.isFallback,
responseGenerator,
previousIncrementalCacheEntry,
resolved
)
// Handle null response
if (!incrementalResponseCacheEntry) {
......
......@@ -1136,12 +1136,28 @@ export abstract class RouteModule<
isMinimalMode: boolean
}) {
const responseCache = this.getResponseCache(req)
// The prefetch-serves-fallback-shell behavior is gated behind the
// `appShells` experimental flag. When it's off, Next.js Segment Cache
// prefetches keep the previous (non-prefetch) response-cache behavior so
// existing suites that incidentally depend on it are unaffected.
const appShells = nextConfig.experimental.appShells === true
const cacheEntry = await responseCache.get(cacheKey, responseGenerator, {
routeKind,
isFallback,
isRoutePPREnabled,
isOnDemandRevalidate,
isPrefetch: req.headers.purpose === 'prefetch',
appShells,
// A Next.js Segment Cache prefetch uses the `Next-Router-Prefetch`
// header (surfaced as the `isPrefetchRSCRequest` request meta), not the
// standard browser `purpose: prefetch` header. Recognize both so the
// response cache treats segment prefetches as prefetches — most
// importantly, so a prefetch that misses serves a fallback shell rather
// than joining an in-flight background (concrete) revalidation. The
// Next.js-prefetch arm is gated on `appShells`; with the flag off, only
// the standard browser prefetch header is recognized (unchanged).
isPrefetch:
req.headers.purpose === 'prefetch' ||
(appShells && getRequestMeta(req, 'isPrefetchRSCRequest') === true),
// Use x-invocation-id header to scope the in-memory cache to a single
// revalidation request in minimal mode.
invocationID: req.headers['x-invocation-id'] as string | undefined,
......
import { ReactNode } from 'react'
export default function RootLayout({ children }: { children: ReactNode }) {
return (
<html>
<body>{children}</body>
</html>
)
}
import { Suspense } from 'react'
type Params = { id: string }
// No generateStaticParams: this route's fallback shell can never be upgraded to
// a concrete version, so a prefetch that receives the shell must NOT be flagged
// as a fallback (no client retry).
export default function Page({ params }: { params: Promise<Params> }) {
return (
<main>
<Suspense
fallback={<p id="no-gsp-shell">App shell for no-static-params</p>}
>
<ParamsDependent params={params} />
</Suspense>
</main>
)
}
async function ParamsDependent({ params }: { params: Promise<Params> }) {
const { id } = await params
return <p id="no-gsp-content">{`No-GSP post body for ${id}`}</p>
}
import { LinkAccordion } from '../components/link-accordion'
export default function Page() {
return (
<ul>
<li>
{/* Prerendered at build time via generateStaticParams — the prefetch
receives the concrete version, never a fallback. */}
<LinkAccordion href="/static-posts/1">
Static post 1 (concrete)
</LinkAccordion>
</li>
<li>
{/* Has generateStaticParams (for a different value), so this
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">
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">
No static params 1 (non-upgradeable fallback)
</LinkAccordion>
</li>
<li>
{/* Same upgradeable route as /posts/recovery, but with its own
un-enumerated param so its ISR entry is independent of the recovery
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">
Post retry-limit (upgradeable fallback)
</LinkAccordion>
</li>
</ul>
)
}
import { Suspense } from 'react'
type Params = { id: string }
export function generateStaticParams() {
return [{ id: 'prerendered' }]
}
export default function Page({ params }: { params: Promise<Params> }) {
return (
<main>
<Suspense fallback={<p id="shell">App shell for posts</p>}>
<ParamsDependent params={params} />
</Suspense>
</main>
)
}
async function ParamsDependent({ params }: { params: Promise<Params> }) {
const { id } = await params
return <p id="post-content">{`Post body for ${id}`}</p>
}
import { Suspense } from 'react'
type Params = { id: string }
// Fully prerendered at build time: the concrete params are known via
// generateStaticParams, so a prefetch receives the concrete version and is
// never marked as a fallback.
export async function generateStaticParams() {
return [{ id: '1' }]
}
export default function Page({ params }: { params: Promise<Params> }) {
return (
<main>
<Suspense fallback={<p id="static-shell">App shell for static posts</p>}>
<ParamsDependent params={params} />
</Suspense>
</main>
)
}
async function ParamsDependent({ params }: { params: Promise<Params> }) {
const { id } = await params
return <p id="static-post-content">{`Static post ${id}`}</p>
}
'use client'
import Link, { type LinkProps } from 'next/link'
import { useState } from 'react'
export function LinkAccordion({
href,
children,
prefetch,
}: {
href: string
children: React.ReactNode
prefetch?: LinkProps['prefetch']
}) {
const [isVisible, setIsVisible] = useState(false)
return (
<>
<input
type="checkbox"
checked={isVisible}
onChange={() => setIsVisible(!isVisible)}
data-link-accordion={href}
/>
{isVisible ? (
<Link href={href} prefetch={prefetch}>
{children}
</Link>
) : (
<>{children} (link is hidden)</>
)}
</>
)
}
import type { NextConfig } from 'next'
const nextConfig: NextConfig = {
cacheComponents: true,
experimental: {
// `appShells` gates the prefetch-serves-fallback-shell behavior that this
// suite exercises. It requires the following flags to also be enabled.
appShells: true,
prefetchInlining: true,
varyParams: true,
optimisticRouting: true,
cachedNavigations: true,
},
}
export default nextConfig
import { nextTestSetup } from 'e2e-utils'
import type * as Playwright from 'playwright'
import { createRouterAct } from 'router-act'
import { retry, waitFor } from 'next-test-utils'
describe('segment cache prefetch fallback retry', () => {
const { next, isNextDev, isNextDeploy } = nextTestSetup({
files: __dirname,
})
if (isNextDev || isNextDeploy) {
// Prefetching is disabled in dev, and the recovery test relies on
// observing ISR cache state and background regeneration, which aren't
// controllable in minimal/deploy mode.
it('disabled in development / deployment', () => {})
return
}
async function startBrowserWithFakeClock(url: string) {
let page!: Playwright.Page
const startDate = Date.now()
const browser = await next.browser(url, {
async beforePageLoad(p: Playwright.Page) {
page = p
await page.clock.install()
await page.clock.setFixedTime(startDate)
},
})
const act = createRouterAct(page)
return { browser, page, act }
}
it('does not retry a prefetch that received a concrete (non-fallback) response', async () => {
const { browser, page, act } = await startBrowserWithFakeClock('/')
// The static route is prerendered at build time (generateStaticParams
// enumerates `1`), so the prefetch receives a concrete response that is
// not marked as a fallback.
await act(async () => {
await browser
.elementByCss('input[data-link-accordion="/static-posts/1"]')
.click()
})
// No retry should fire for a concrete response, even after advancing well
// past the retry interval.
await act(async () => {
await page.clock.fastForward(5000)
}, 'no-requests')
})
it('does not retry a fallback shell for a route that can never be upgraded', async () => {
const { browser, page, act } = await startBrowserWithFakeClock('/')
// This route has no generateStaticParams, so its fallback shell can never
// be upgraded to a concrete version. The prefetch still serves the shell,
// but it must NOT be flagged as a fallback — so the client never retries.
await act(async () => {
await browser
.elementByCss('input[data-link-accordion="/no-static-params/1"]')
.click()
})
// Because the shell wasn't flagged as an upgradeable fallback, no retry
// fires even after advancing past the retry interval.
await act(async () => {
await page.clock.fastForward(5000)
}, 'no-requests')
})
it('picks up the upgraded version on retry once the server regenerates the ISR entry', async () => {
const { browser, page, act } = await startBrowserWithFakeClock('/')
// 1. Prefetch the un-enumerated param. The route has generateStaticParams
// (for a different value), so this param is upgradeable: the server
// serves a fallback shell, flagged so the client knows to retry.
await act(async () => {
await browser
.elementByCss('input[data-link-accordion="/posts/recovery"]')
.click()
})
// 2. The client clock is frozen, so no retry has fired yet. Drive the
// server to upgrade the ISR entry from a fallback shell to the concrete
// version, and wait until it's observable. There is an inherent race
// here — the background regeneration is asynchronous — so we poll until
// it completes before letting the client continue.
//
// A normal navigation request triggers the background regeneration. We
// observe completion via the *static prefetch* response (RSC +
// Next-Router-Prefetch), which is served from the cached prerender
// rather than re-rendered per request: the concrete param content is
// absent from the fallback shell and only appears once the entry has
// been upgraded. (A normal navigation always streams the concrete
// content dynamically, so it can't be used to observe the upgrade.)
await retry(async () => {
// Trigger (and, until it completes, re-trigger) background regeneration.
await next.fetch('/posts/recovery')
const res = await next.fetch('/posts/recovery', {
headers: {
RSC: '1',
'Next-Router-Prefetch': '1',
'Next-Router-Segment-Prefetch': '/_full',
},
})
const body = await res.text()
expect(body).toContain('Post body for recovery')
})
// 3. Now let the client retry fire. It re-fetches the segment and receives
// the upgraded (concrete) version.
await act(
async () => {
await page.clock.fastForward(2000)
},
{ includes: 'Post body for recovery' }
)
})
it('retries a static fallback prefetch a bounded number of times, then stops', async () => {
const { browser, page } = await startBrowserWithFakeClock('/')
// Pin the server so it can never upgrade this route's ISR fallback to a
// concrete version — the client keeps receiving the fallback shell on every
// retry. (Uses its own un-enumerated param so it doesn't share an ISR entry
// with the recovery test above.)
const getRequestCount = await simulateNeverUpgradingIsrEntries(
page,
'/posts/retry-limit'
)
await browser
.elementByCss('input[data-link-accordion="/posts/retry-limit"]')
.click()
// Advance the clock far past any number of retry intervals. The retry loop
// is bounded, so even though we pump the clock much more than it could ever
// need, only a handful of requests are ever issued.
for (let i = 0; i < 20; i++) {
await page.clock.fastForward(1000)
// Let any in-flight retry settle and re-arm its next timer before the
// next advance.
await waitFor(100)
}
// The initial prefetch plus a small, fixed number of retries — never a
// runaway loop.
expect(getRequestCount()).toBeLessThan(5)
})
})
/**
* Intercepts the per-segment prefetch requests for `pathname` and, after the
* first response for a given segment, replays that same response for every
* later request to it — without contacting the server again.
*
* This simulates a deployment whose server never upgrades its ISR fallback
* entries to concrete versions: the client keeps receiving the fallback shell
* no matter how many times it retries. (Normally an upgradeable route
* regenerates in the background, so a retry would eventually pick up the
* concrete version — which is exactly what we want to prevent when testing the
* retry *limit*.)
*
* Returns a getter for the number of intercepted segment-bundle requests.
*/
async function simulateNeverUpgradingIsrEntries(
page: Playwright.Page,
pathname: string
): Promise<() => number> {
const cachedResponses = new Map<
string,
{ body: Buffer; headers: Record<string, string>; status: number }
>()
let requestCount = 0
await page.route('**/*', async (route) => {
const request = route.request()
const headers = request.headers()
const segmentKey = headers['next-router-segment-prefetch']
const isSegmentBundlePrefetch =
headers['next-router-prefetch'] !== undefined &&
segmentKey !== undefined &&
// The route-tree request (`/_tree`) is not a segment bundle.
segmentKey !== '/_tree' &&
new URL(request.url()).pathname === pathname
if (!isSegmentBundlePrefetch) {
route.continue()
return
}
requestCount++
let cached = cachedResponses.get(segmentKey)
if (cached === undefined) {
// First request for this segment: capture the real (fallback) response.
// Mirrors router-act's internal fetch pattern.
const original = await page.request.fetch(request, { maxRedirects: 0 })
const responseHeaders = original.headers()
// Buffered replay doesn't stream; drop the chunked-encoding header to
// avoid net::ERR_INCOMPLETE_CHUNKED_ENCODING (see router-act).
delete responseHeaders['transfer-encoding']
cached = {
body: await original.body(),
headers: responseHeaders,
status: original.status(),
}
cachedResponses.set(segmentKey, cached)
}
await route.fulfill(cached)
})
return () => requestCount
}
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