Unverified Commit f09aa18f authored by Andrew Clark's avatar Andrew Clark Committed by GitHub

Refactor fetchStrategy -> stage and completeness (#99706)

This is a refactor of the FetchStrategy type.

As the Partial Prefetching design has evolved, FetchStrategy has come to
represent two independent concepts, which we now model separately: the
_stage_ (AppStage) of the navigation that an entry was rendered through
(shell, prefetch, or navigation), and the _completeness_ (Completeness)
of the rendering through that stage (needs runtime request, cache
complete but with dynamic holes, or fully complete with no dynamic
holes). Everywhere that used to accept a FetchStrategy now accepts
either one or both of these types.

(Note: I've called the type AppStage to distinguish it from the internal
stages used on the server as part of the rendering algorithm. The stages
used on the client are the ones we document publicly as part of
`ensureStatic` and the `prefetch()` and `navigation()` APIs.)

The `completeness` field also replaces the `isPartial` field.

It's possible to express much of the logic using a single enum, as in
the FetchStrategy model. To prove this, I've extracted most of the
behavioral changes into earlier PRs, to make this one easier to review.
But the resulting logic in the new model should be easier to follow. So
on net, we have the same number of fields but expressed in a way that
better fits the underlying design:

- Every prefetch task (e.g. a visible Link) has a target stage and level
of completeness. The task finishes when the cache has entries that match
_both_ targets.
- When deciding whether to overwrite an existing entry, a more less
complete entry must never overwrite a less complete one, even if it
represents a later rendering stage. For example, a response rendered at
the Navigation stage cannot overwrite a response written at the Prefetch
stage if it does not include cookie-dependent data; we must discard it
and perform a new request.

---------
Co-authored-by: 's avatarsparkly-dev <338975655+sparkly-dev@users.noreply.github.com>
parent 76ddf785
...@@ -19,7 +19,7 @@ import { ...@@ -19,7 +19,7 @@ import {
mountFormInstance, mountFormInstance,
unmountPrefetchableInstance, unmountPrefetchableInstance,
} from '../components/links' } from '../components/links'
import { FetchStrategy } from '../components/segment-cache/types' import { AppStage } from '../components/segment-cache/types'
export type { FormProps } export type { FormProps }
...@@ -100,13 +100,7 @@ export default function Form({ ...@@ -100,13 +100,7 @@ export default function Form({
const observeFormVisibilityOnMount = useCallback( const observeFormVisibilityOnMount = useCallback(
(element: HTMLFormElement) => { (element: HTMLFormElement) => {
if (isPrefetchEnabled && router !== null) { if (isPrefetchEnabled && router !== null) {
mountFormInstance( mountFormInstance(element, actionProp, router, AppStage.Shell)
element,
actionProp,
router,
// We default to PPR. We'll discover whether or not the route supports it with the initial prefetch.
FetchStrategy.PPR
)
} }
return () => { return () => {
unmountPrefetchableInstance(element) unmountPrefetchableInstance(element)
......
...@@ -18,10 +18,7 @@ import { ...@@ -18,10 +18,7 @@ import {
type LinkInstance, type LinkInstance,
} from '../components/links' } from '../components/links'
import { isLocalURL } from '../../shared/lib/router/utils/is-local-url' import { isLocalURL } from '../../shared/lib/router/utils/is-local-url'
import { import { AppStage } from '../components/segment-cache/types'
FetchStrategy,
type PrefetchTaskFetchStrategy,
} from '../components/segment-cache/types'
import type { RouterTransitionPrefetchIntent } from '../router-transition-types' import type { RouterTransitionPrefetchIntent } from '../router-transition-types'
type Url = string | UrlObject type Url = string | UrlObject
...@@ -382,11 +379,9 @@ export default function LinkComponent( ...@@ -382,11 +379,9 @@ export default function LinkComponent(
const prefetchIntent: RouterTransitionPrefetchIntent = const prefetchIntent: RouterTransitionPrefetchIntent =
prefetchProp === false ? 'none' : prefetchProp === true ? 'full' : 'auto' prefetchProp === false ? 'none' : prefetchProp === true ? 'full' : 'auto'
const fetchStrategy = // TODO: it makes no sense to assign a stage when prefetching is disabled.
prefetchIntent !== 'none' const prefetchStage =
? getFetchStrategyFromPrefetchIntent(prefetchIntent) prefetchProp === true ? AppStage.Prefetch : AppStage.Shell
: // TODO: it makes no sense to assign a fetchStrategy when prefetching is disabled.
FetchStrategy.PPR
if (process.env.NODE_ENV !== 'production') { if (process.env.NODE_ENV !== 'production') {
function createPropError(args: { function createPropError(args: {
...@@ -610,11 +605,11 @@ export default function LinkComponent( ...@@ -610,11 +605,11 @@ export default function LinkComponent(
// Only capture when a warning might actually need it. Otherwise leave // Only capture when a warning might actually need it. Otherwise leave
// it `undefined` so consumers can detect the opt-out and degrade // it `undefined` so consumers can detect the opt-out and degrade
// gracefully. // gracefully.
if (fetchStrategy === FetchStrategy.Full) { if (prefetchStage !== AppStage.Shell) {
return React.captureOwnerStack() return React.captureOwnerStack()
} }
return undefined return undefined
}, [fetchStrategy]) }, [prefetchStage])
: undefined : undefined
// Use a callback ref to attach an IntersectionObserver to the anchor tag on // Use a callback ref to attach an IntersectionObserver to the anchor tag on
...@@ -628,7 +623,7 @@ export default function LinkComponent( ...@@ -628,7 +623,7 @@ export default function LinkComponent(
element, element,
formattedHref, formattedHref,
router, router,
fetchStrategy, prefetchStage,
prefetchEnabled, prefetchEnabled,
setOptimisticLinkStatus, setOptimisticLinkStatus,
ownerStack ownerStack
...@@ -647,7 +642,7 @@ export default function LinkComponent( ...@@ -647,7 +642,7 @@ export default function LinkComponent(
prefetchEnabled, prefetchEnabled,
formattedHref, formattedHref,
router, router,
fetchStrategy, prefetchStage,
setOptimisticLinkStatus, setOptimisticLinkStatus,
ownerStack, ownerStack,
] ]
...@@ -804,24 +799,3 @@ const LinkStatusContext = createContext< ...@@ -804,24 +799,3 @@ const LinkStatusContext = createContext<
export const useLinkStatus = () => { export const useLinkStatus = () => {
return useContext(LinkStatusContext) return useContext(LinkStatusContext)
} }
function getFetchStrategyFromPrefetchIntent(
prefetchIntent: Exclude<RouterTransitionPrefetchIntent, 'none'>
): PrefetchTaskFetchStrategy {
if (process.env.__NEXT_CACHE_COMPONENTS) {
if (prefetchIntent === 'full') {
return FetchStrategy.Full
}
// `"auto"`: the default mode, where we will prefetch partially if the link is in the viewport.
prefetchIntent satisfies 'auto'
return FetchStrategy.PPR
} else {
return prefetchIntent === 'auto'
? // We default to PPR, and we'll discover whether or not the route supports it with the initial prefetch.
FetchStrategy.PPR
: // In the old implementation without runtime prefetches, `prefetch={true}` (`'full'`) forces all dynamic
// data to be prefetched, preserving backwards-compatibility.
FetchStrategy.Full
}
}
...@@ -33,7 +33,7 @@ import { ...@@ -33,7 +33,7 @@ import {
} from './segment-cache/cache-key' } from './segment-cache/cache-key'
import type { CacheMap } from './segment-cache/cache-map' import type { CacheMap } from './segment-cache/cache-map'
import { schedulePrefetchTask } from './segment-cache/scheduler' import { schedulePrefetchTask } from './segment-cache/scheduler'
import { PrefetchPriority, FetchStrategy } from './segment-cache/types' import { PrefetchPriority, AppStage } from './segment-cache/types'
import { getLinkForCurrentNavigation } from './links' import { getLinkForCurrentNavigation } from './links'
import type { AppRouterState } from './router-reducer/router-reducer-types' import type { AppRouterState } from './router-reducer/router-reducer-types'
import { ScrollBehavior } from './router-reducer/router-reducer-types' import { ScrollBehavior } from './router-reducer/router-reducer-types'
...@@ -277,7 +277,7 @@ export function navigateToKnownRoute( ...@@ -277,7 +277,7 @@ export function navigateToKnownRoute(
const link = getLinkForCurrentNavigation() const link = getLinkForCurrentNavigation()
if ( if (
link !== null && link !== null &&
link.fetchStrategy === FetchStrategy.Full && link.prefetchStage !== AppStage.Shell &&
(navigationSeed.root.tree.prefetchHints & (navigationSeed.root.tree.prefetchHints &
(PrefetchHint.SubtreeHasPartialPrefetching | (PrefetchHint.SubtreeHasPartialPrefetching |
PrefetchHint.SubtreeHasInstantFalse)) === PrefetchHint.SubtreeHasInstantFalse)) ===
...@@ -313,7 +313,7 @@ export function navigateToKnownRoute( ...@@ -313,7 +313,7 @@ export function navigateToKnownRoute(
const link = getLinkForCurrentNavigation() const link = getLinkForCurrentNavigation()
restrictToShell = shouldRestrictNavigationToShell( restrictToShell = shouldRestrictNavigationToShell(
navigationSeed.root.tree.prefetchHints, navigationSeed.root.tree.prefetchHints,
link !== null ? link.fetchStrategy : FetchStrategy.PPR link !== null ? link.prefetchStage : AppStage.Shell
) )
} }
...@@ -833,7 +833,7 @@ async function ensurePrefetchThenNavigate( ...@@ -833,7 +833,7 @@ async function ensurePrefetchThenNavigate(
navigationLock: NavigationLock | null navigationLock: NavigationLock | null
): Promise<AppRouterState> { ): Promise<AppRouterState> {
const link = getLinkForCurrentNavigation() const link = getLinkForCurrentNavigation()
const fetchStrategy = link !== null ? link.fetchStrategy : FetchStrategy.PPR const prefetchStage = link !== null ? link.prefetchStage : AppStage.Shell
const cacheKey = createCacheKey(url.href, nextUrl) const cacheKey = createCacheKey(url.href, nextUrl)
...@@ -848,7 +848,7 @@ async function ensurePrefetchThenNavigate( ...@@ -848,7 +848,7 @@ async function ensurePrefetchThenNavigate(
const prefetchTask = schedulePrefetchTask( const prefetchTask = schedulePrefetchTask(
cacheKey, cacheKey,
currentRoot, currentRoot,
fetchStrategy, prefetchStage,
PrefetchPriority.Default, PrefetchPriority.Default,
null, // onInvalidate null, // onInvalidate
navigationLockPrefetch navigationLockPrefetch
......
import type { RootRouteTree } from './segment-cache/cache' import type { RootRouteTree } from './segment-cache/cache'
import type { CacheNode } from '../../shared/lib/app-router-types' import type { CacheNode } from '../../shared/lib/app-router-types'
import type { AppRouterInstance } from '../../shared/lib/app-router-context.shared-runtime' import type { AppRouterInstance } from '../../shared/lib/app-router-context.shared-runtime'
import { import { AppStage, PrefetchPriority } from './segment-cache/types'
FetchStrategy,
type PrefetchTaskFetchStrategy,
PrefetchPriority,
} from './segment-cache/types'
import { createCacheKey } from './segment-cache/cache-key' import { createCacheKey } from './segment-cache/cache-key'
import { import {
type PrefetchTask, type PrefetchTask,
...@@ -24,7 +20,7 @@ type Element = LinkElement | HTMLFormElement ...@@ -24,7 +20,7 @@ type Element = LinkElement | HTMLFormElement
// shape for both to prevent a polymorphic de-opt in the VM. // shape for both to prevent a polymorphic de-opt in the VM.
type LinkOrFormInstanceShared = { type LinkOrFormInstanceShared = {
router: AppRouterInstance router: AppRouterInstance
fetchStrategy: PrefetchTaskFetchStrategy prefetchStage: AppStage
isVisible: boolean isVisible: boolean
...@@ -172,7 +168,7 @@ export function mountLinkInstance( ...@@ -172,7 +168,7 @@ export function mountLinkInstance(
element: LinkElement, element: LinkElement,
href: string, href: string,
router: AppRouterInstance, router: AppRouterInstance,
fetchStrategy: PrefetchTaskFetchStrategy, prefetchStage: AppStage,
prefetchEnabled: boolean, prefetchEnabled: boolean,
setOptimisticLinkStatus: (status: { pending: boolean }) => void, setOptimisticLinkStatus: (status: { pending: boolean }) => void,
ownerStack: string | null | undefined ownerStack: string | null | undefined
...@@ -182,7 +178,7 @@ export function mountLinkInstance( ...@@ -182,7 +178,7 @@ export function mountLinkInstance(
if (prefetchURL !== null) { if (prefetchURL !== null) {
const instance: PrefetchableLinkInstance = { const instance: PrefetchableLinkInstance = {
router, router,
fetchStrategy, prefetchStage,
isVisible: false, isVisible: false,
prefetchTask: null, prefetchTask: null,
prefetchHref: prefetchURL.href, prefetchHref: prefetchURL.href,
...@@ -199,7 +195,7 @@ export function mountLinkInstance( ...@@ -199,7 +195,7 @@ export function mountLinkInstance(
// track its optimistic state (i.e. useLinkStatus). // track its optimistic state (i.e. useLinkStatus).
const instance: NonPrefetchableLinkInstance = { const instance: NonPrefetchableLinkInstance = {
router, router,
fetchStrategy, prefetchStage,
isVisible: false, isVisible: false,
prefetchTask: null, prefetchTask: null,
prefetchHref: null, prefetchHref: null,
...@@ -213,7 +209,7 @@ export function mountFormInstance( ...@@ -213,7 +209,7 @@ export function mountFormInstance(
element: HTMLFormElement, element: HTMLFormElement,
href: string, href: string,
router: AppRouterInstance, router: AppRouterInstance,
fetchStrategy: PrefetchTaskFetchStrategy prefetchStage: AppStage
): void { ): void {
const prefetchURL = coercePrefetchableUrl(href) const prefetchURL = coercePrefetchableUrl(href)
if (prefetchURL === null) { if (prefetchURL === null) {
...@@ -225,7 +221,7 @@ export function mountFormInstance( ...@@ -225,7 +221,7 @@ export function mountFormInstance(
} }
const instance: FormInstance = { const instance: FormInstance = {
router, router,
fetchStrategy, prefetchStage,
isVisible: false, isVisible: false,
prefetchTask: null, prefetchTask: null,
prefetchHref: prefetchURL.href, prefetchHref: prefetchURL.href,
...@@ -305,7 +301,7 @@ export function onNavigationIntent( ...@@ -305,7 +301,7 @@ export function onNavigationIntent(
unstable_upgradeToDynamicPrefetch unstable_upgradeToDynamicPrefetch
) { ) {
// Switch to a full prefetch // Switch to a full prefetch
instance.fetchStrategy = FetchStrategy.Full instance.prefetchStage = AppStage.Navigation
} }
rescheduleLinkPrefetch(instance, PrefetchPriority.Intent) rescheduleLinkPrefetch(instance, PrefetchPriority.Intent)
} }
...@@ -346,7 +342,7 @@ function rescheduleLinkPrefetch( ...@@ -346,7 +342,7 @@ function rescheduleLinkPrefetch(
instance.prefetchTask = scheduleSegmentPrefetchTask( instance.prefetchTask = scheduleSegmentPrefetchTask(
cacheKey, cacheKey,
appRouterState.root, appRouterState.root,
instance.fetchStrategy, instance.prefetchStage,
priority, priority,
null, null,
null // navigationLockPrefetch null // navigationLockPrefetch
...@@ -357,7 +353,7 @@ function rescheduleLinkPrefetch( ...@@ -357,7 +353,7 @@ function rescheduleLinkPrefetch(
reschedulePrefetchTask( reschedulePrefetchTask(
existingPrefetchTask, existingPrefetchTask,
appRouterState.root, appRouterState.root,
instance.fetchStrategy, instance.prefetchStage,
priority priority
) )
} }
...@@ -392,7 +388,7 @@ export function pingVisibleLinks( ...@@ -392,7 +388,7 @@ export function pingVisibleLinks(
instance.prefetchTask = scheduleSegmentPrefetchTask( instance.prefetchTask = scheduleSegmentPrefetchTask(
cacheKey, cacheKey,
root, root,
instance.fetchStrategy, instance.prefetchStage,
PrefetchPriority.Default, PrefetchPriority.Default,
null, null,
null // navigationLockPrefetch null // navigationLockPrefetch
......
...@@ -6,15 +6,11 @@ import { getCurrentAppRouterState } from './app-router-instance' ...@@ -6,15 +6,11 @@ import { getCurrentAppRouterState } from './app-router-instance'
import { isJavaScriptURLString } from '../lib/javascript-url' import { isJavaScriptURLString } from '../lib/javascript-url'
import { createCacheKey } from './segment-cache/cache-key' import { createCacheKey } from './segment-cache/cache-key'
import { schedulePrefetchTask } from './segment-cache/scheduler' import { schedulePrefetchTask } from './segment-cache/scheduler'
import { import { AppStage, PrefetchPriority } from './segment-cache/types'
FetchStrategy,
PrefetchPriority,
type PrefetchTaskFetchStrategy,
} from './segment-cache/types'
/** /**
* The public prefetch operation, exposed through `router.prefetch`. Converts * The public prefetch operation, exposed through `router.prefetch`. Converts
* the public options into a fetch strategy, reads the current router state, * the public options into the stage to prefetch up to, reads the current router state,
* and drives the Segment Cache. * and drives the Segment Cache.
* *
* Unlike the old implementation, the Segment Cache doesn't store its data in * Unlike the old implementation, the Segment Cache doesn't store its data in
...@@ -36,15 +32,14 @@ export function prefetchRoute(href: string, options?: PrefetchOptions): void { ...@@ -36,15 +32,14 @@ export function prefetchRoute(href: string, options?: PrefetchOptions): void {
const prefetchKind = options?.kind ?? 'auto' const prefetchKind = options?.kind ?? 'auto'
// We don't currently offer a way to issue a runtime prefetch via `router.prefetch()`. // We don't currently offer a way to issue a runtime prefetch via `router.prefetch()`.
let fetchStrategy: PrefetchTaskFetchStrategy let prefetchStage: AppStage
switch (prefetchKind) { switch (prefetchKind) {
case 'auto': { case 'auto': {
// We default to PPR. We'll discover whether or not the route supports it with the initial prefetch. prefetchStage = AppStage.Shell
fetchStrategy = FetchStrategy.PPR
break break
} }
case 'full': { case 'full': {
fetchStrategy = FetchStrategy.Full prefetchStage = AppStage.Prefetch
break break
} }
default: { default: {
...@@ -53,7 +48,7 @@ export function prefetchRoute(href: string, options?: PrefetchOptions): void { ...@@ -53,7 +48,7 @@ export function prefetchRoute(href: string, options?: PrefetchOptions): void {
// we might get an unexpected value from user code. // we might get an unexpected value from user code.
// We don't know what they want, but we know they want a prefetch, // We don't know what they want, but we know they want a prefetch,
// so use the default. // so use the default.
fetchStrategy = FetchStrategy.PPR prefetchStage = AppStage.Shell
} }
} }
...@@ -61,7 +56,7 @@ export function prefetchRoute(href: string, options?: PrefetchOptions): void { ...@@ -61,7 +56,7 @@ export function prefetchRoute(href: string, options?: PrefetchOptions): void {
href, href,
state.nextUrl, state.nextUrl,
state.root, state.root,
fetchStrategy, prefetchStage,
options?.onInvalidate ?? null options?.onInvalidate ?? null
) )
} }
...@@ -74,8 +69,7 @@ export function prefetchRoute(href: string, options?: PrefetchOptions): void { ...@@ -74,8 +69,7 @@ export function prefetchRoute(href: string, options?: PrefetchOptions): void {
* Roughly corresponds to the current URL. * Roughly corresponds to the current URL.
* @param renderTreeAtTimeOfPrefetch - The active render tree and head, and * @param renderTreeAtTimeOfPrefetch - The active render tree and head, and
* their vary paths. * their vary paths.
* @param fetchStrategy - Whether to prefetch dynamic data, in addition to * @param prefetchStage - The stage to prefetch up to.
* static data. This is used by `<Link prefetch={true}>`.
* @param onInvalidate - A callback that will be called when the prefetch cache * @param onInvalidate - A callback that will be called when the prefetch cache
* When called, it signals to the listener that the data associated with the * When called, it signals to the listener that the data associated with the
* prefetch may have been invalidated from the cache. This is not a live * prefetch may have been invalidated from the cache. This is not a live
...@@ -90,7 +84,7 @@ export function prefetch( ...@@ -90,7 +84,7 @@ export function prefetch(
href: string, href: string,
nextUrl: string | null, nextUrl: string | null,
renderTreeAtTimeOfPrefetch: RootRouteTree<CacheNode>, renderTreeAtTimeOfPrefetch: RootRouteTree<CacheNode>,
fetchStrategy: PrefetchTaskFetchStrategy, prefetchStage: AppStage,
onInvalidate: null | (() => void) onInvalidate: null | (() => void)
) { ) {
const url = createPrefetchURL(href) const url = createPrefetchURL(href)
...@@ -102,7 +96,7 @@ export function prefetch( ...@@ -102,7 +96,7 @@ export function prefetch(
schedulePrefetchTask( schedulePrefetchTask(
cacheKey, cacheKey,
renderTreeAtTimeOfPrefetch, renderTreeAtTimeOfPrefetch,
fetchStrategy, prefetchStage,
PrefetchPriority.Default, PrefetchPriority.Default,
onInvalidate, onInvalidate,
null // navigationLockPrefetch null // navigationLockPrefetch
......
...@@ -39,6 +39,7 @@ import { ...@@ -39,6 +39,7 @@ import {
MetadataOnlyRequestTree, MetadataOnlyRequestTree,
} from './segment-cache/cache' } from './segment-cache/cache'
import { discoverKnownRoute } from './segment-cache/optimistic-routes' import { discoverKnownRoute } from './segment-cache/optimistic-routes'
import { Completeness } from './segment-cache/types'
import type { NormalizedSearch } from './segment-cache/cache-key' import type { NormalizedSearch } from './segment-cache/cache-key'
import type { CacheMap } from './segment-cache/cache-map' import type { CacheMap } from './segment-cache/cache-map'
import { import {
...@@ -1137,7 +1138,8 @@ function createRenderTreeForSegment( ...@@ -1137,7 +1138,8 @@ function createRenderTreeForSegment(
case EntryStatus.Fulfilled: { case EntryStatus.Fulfilled: {
// Happy path: a cache hit // Happy path: a cache hit
cachedRsc = segmentEntry.rsc cachedRsc = segmentEntry.rsc
isCachedRscPartial = segmentEntry.isPartial isCachedRscPartial =
segmentEntry.completeness !== Completeness.FullyComplete
cachedVaryParams = segmentEntry.varyParams cachedVaryParams = segmentEntry.varyParams
break break
} }
...@@ -1157,11 +1159,11 @@ function createRenderTreeForSegment( ...@@ -1157,11 +1159,11 @@ function createRenderTreeForSegment(
// do yet another request to fill in the remaining data, creating // do yet another request to fill in the remaining data, creating
// a waterfall. // a waterfall.
// //
// The one exception is if this segment is being fetched with via // The exception is a request we expect to return the segment fully
// prefetch={true} (i.e. the "force stale" or "full" strategy). If so, // complete, like a legacy prefetch. If so, we can assume the response
// we can assume the response will be full. This field is set to `false` // will have nothing left to request.
// for such segments. isCachedRscPartial =
isCachedRscPartial = segmentEntry.isPartial segmentEntry.completeness !== Completeness.FullyComplete
break break
} }
case EntryStatus.Empty: case EntryStatus.Empty:
......
...@@ -15,7 +15,7 @@ ...@@ -15,7 +15,7 @@
import type { FlightRouterState } from '../../../shared/lib/app-router-types' import type { FlightRouterState } from '../../../shared/lib/app-router-types'
import type { SegmentCacheEntry } from './cache' import type { SegmentCacheEntry } from './cache'
import type { CacheMap } from './cache-map' import type { CacheMap } from './cache-map'
import type { FetchStrategy } from './types' import type { AppStage } from './types'
import type { NavigationLockPrefetch } from './navigation-testing-lock' import type { NavigationLockPrefetch } from './navigation-testing-lock'
export type { export type {
...@@ -62,7 +62,7 @@ export function resetNavigationLockToPending(): void {} ...@@ -62,7 +62,7 @@ export function resetNavigationLockToPending(): void {}
export function shouldRestrictNavigationToShell( export function shouldRestrictNavigationToShell(
_rootPrefetchHints: number, _rootPrefetchHints: number,
_linkFetchStrategy: FetchStrategy _linkPrefetchStage: AppStage
): boolean { ): boolean {
return false return false
} }
...@@ -25,10 +25,9 @@ import { ...@@ -25,10 +25,9 @@ import {
} from '../../../shared/lib/app-router-types' } from '../../../shared/lib/app-router-types'
import { NEXT_INSTANT_TEST_COOKIE } from '../app-router-headers' import { NEXT_INSTANT_TEST_COOKIE } from '../app-router-headers'
import { refreshOnInstantNavigationUnlock } from '../use-action-queue' import { refreshOnInstantNavigationUnlock } from '../use-action-queue'
import { needsSpeculativePrefetch } from './scheduler'
import type { SegmentCacheEntry } from './cache' import type { SegmentCacheEntry } from './cache'
import { createCacheMap, type CacheMap } from './cache-map' import { createCacheMap, type CacheMap } from './cache-map'
import type { PrefetchTaskFetchStrategy } from './types' import { AppStage } from './types'
type InstantNavCookieState = 'empty' | 'pending' | 'mpa' | 'spa' type InstantNavCookieState = 'empty' | 'pending' | 'mpa' | 'spa'
...@@ -543,11 +542,11 @@ export function getCurrentNavigationGate(): Promise<void> | null { ...@@ -543,11 +542,11 @@ export function getCurrentNavigationGate(): Promise<void> | null {
*/ */
export function shouldRestrictNavigationToShell( export function shouldRestrictNavigationToShell(
rootPrefetchHints: number, rootPrefetchHints: number,
linkFetchStrategy: PrefetchTaskFetchStrategy linkPrefetchStage: AppStage
): boolean { ): boolean {
return ( return (
isNavigationLocked() && isNavigationLocked() &&
(rootPrefetchHints & PrefetchHint.SubtreeHasPartialPrefetching) !== 0 && (rootPrefetchHints & PrefetchHint.SubtreeHasPartialPrefetching) !== 0 &&
!needsSpeculativePrefetch(linkFetchStrategy, rootPrefetchHints) linkPrefetchStage === AppStage.Shell
) )
} }
...@@ -31,44 +31,40 @@ export const enum PrefetchPriority { ...@@ -31,44 +31,40 @@ export const enum PrefetchPriority {
Background = 0, Background = 0,
} }
export const enum FetchStrategy { /**
// Deliberately ordered so we can easily compare two segments * How far a render went, in the app's public stages (not the server's
// and determine if one segment is "more specific" than another * render stages). Each stage includes everything before it. A link asks for a
// (i.e. if it's likely that it contains more data). See * stage; a cache entry records the stage its payload reached.
// canNewFetchStrategyProvideMoreContent in cache.ts for what each tier can *
// contain relative to the others. * Ordered, so two stages can be compared. Never compare a stage with a
// * `Completeness`.
// Full and LoadingBoundary belong to the non-Partial-Prefetching regime: */
// they're only relevant in modes where the staging concepts (shell tiers, export const enum AppStage {
// runtime prefetches) don't apply. They sit on this single ordered ladder // The app shell: shared by every link to the route, so param-dependent
// as an accepted convenience, because cross-regime comparisons exist // content is reduced to fallbacks.
// (e.g. canNewFetchStrategyProvideMoreContent). Shell = 0,
// // Up to where `prefetch()` resolves.
// These numeric values are client-internal and never cross the wire — the Prefetch = 1,
// `next-router-prefetch` request header values are mapped explicitly in // Up to where `navigation()` resolves: what a navigation renders,
// fetchSegmentPrefetchesUsingRuntimeRequest (cache.ts) — so the members can // minus dynamic holes.
// be renumbered freely as long as the relative order is preserved. Navigation = 2,
LoadingBoundary = 0,
// The shell-stage variant extracted from a static per-segment prefetch
// response: every segment's param-dependent content is reduced to pending
// references that render as the param fallback, keyed at the shell vary
// paths (only root params kept concrete). The Shell PHASE that issues
// these requests targets the conceptual App Shell; the strategy itself is
// just this mechanical truncation and keying. Less complete than
// RuntimeShell — a static response can't include content that depends on
// session data (cookies, headers) — and less complete than PPR at concrete
// paths, which includes prerendered param-dependent content.
StaticShell = 1,
RuntimeShell = 2,
PPR = 3,
PPRRuntime = 4,
Full = 5,
} }
/** /**
* A subset of fetch strategies used for prefetch tasks. * What's still missing at an entry's stage. Each level promises everything
* A prefetch task can't know if it should use `PPR` or `LoadingBoundary` * the previous one does.
* until we complete the initial tree prefetch request, so we use `PPR` to signal both cases *
* and adjust it based on the route when actually fetching. * Ordered, so two values can be compared. Never compare it with an
* */ * `AppStage`.
export type PrefetchTaskFetchStrategy = FetchStrategy.PPR | FetchStrategy.Full */
export const enum Completeness {
// Static content only. A runtime prefetch at this stage could add content.
NeedsRuntime = 0,
// Everything cacheable up to this stage is present. Only dynamic holes are
// left, which prefetches never fill.
CacheComplete = 1,
// Nothing extra to request during a navigation: a segment with no holes, a
// legacy full or loading-boundary prefetch, or a back/forward cache entry.
// Implies the navigation stage.
FullyComplete = 2,
}
import { FetchStrategy } from './types' import { AppStage } from './types'
import type { import type {
NormalizedPathname, NormalizedPathname,
NormalizedSearch, NormalizedSearch,
...@@ -210,17 +210,17 @@ export function getPartialVaryPath( ...@@ -210,17 +210,17 @@ export function getPartialVaryPath(
} }
export function getSegmentVaryPathForRequest<TData>( export function getSegmentVaryPathForRequest<TData>(
fetchStrategy: FetchStrategy, stage: AppStage,
tree: RouteTree<TData> tree: RouteTree<TData>
): VaryPath { ): VaryPath {
// This is used for storing pending requests in the cache. We want to choose // This is used for storing pending requests in the cache. We want to choose
// the most generic vary path based on the strategy used to fetch it, so // the most generic vary path the request's expected output allows, so that
// that it can be reused as much as possible. // it can be reused as much as possible.
// //
// We may be able to re-key the response to something even more generic once // We may be able to re-key the response to something even more generic once
// we receive it — for example, if the server tells us that the response // we receive it — for example, if the server tells us that the response
// doesn't vary on a particular param — but even before we send the request, // doesn't vary on a particular param — but even before we send the request,
// we know some params are reusable based on the fetch strategy alone. // we know some params are reusable based on the request alone.
// //
// The original vary path with all the params filled in is stored on the // The original vary path with all the params filled in is stored on the
// route tree object. The shell vary path is precomputed there too. // route tree object. The shell vary path is precomputed there too.
...@@ -231,36 +231,28 @@ export function getSegmentVaryPathForRequest<TData>( ...@@ -231,36 +231,28 @@ export function getSegmentVaryPathForRequest<TData>(
// TODO: Rather than create a new list object just to access the cache, the // TODO: Rather than create a new list object just to access the cache, the
// plan is to add the concept of a "vary mask". This will represent all the // plan is to add the concept of a "vary mask". This will represent all the
// params that can be treated as Fallback. (Or perhaps the inverse.) // params that can be treated as Fallback. (Or perhaps the inverse.)
if ( if (stage === AppStage.Shell) {
fetchStrategy === FetchStrategy.RuntimeShell || // The shell reduces param-dependent content to fallbacks, whether a
fetchStrategy === FetchStrategy.StaticShell // runtime render produced it or we cut it from a static response. So we
) { // can reuse it for any value of the non-root params, and we key it at the
// Both shell strategies produce the App Shell variant of a segment — // shell vary path. That's the vary path with every non-root param
// RuntimeShell via a runtime render with non-root params omitted, // replaced by Fallback. Root params keep their values.
// StaticShell by truncating a static per-segment response at the shell
// byte boundary. Either way, the resulting entry is reusable across all
// concrete values of the non-root params, so we key it at the precomputed
// shell vary path (every non-root param substituted with Fallback; root
// params keep their concrete value).
return tree.shellVaryPath return tree.shellVaryPath
} }
return tree.varyPath return tree.varyPath
} }
/** /**
* The vary path a pending entry is stored under when its response never * The vary path a static request's pending entry is stored under. Like
* varies on search params: every strategy except Full and PPRRuntime. Like * getSegmentVaryPathForRequest, except that a static request's expected vary
* getSegmentVaryPathForRequest, except that the entry can be reused across * params never include search params (search params are runtime data), so
* all possible search param values. * its entry can be reused across all possible search param values.
*/ */
export function getStaticSegmentVaryPathForRequest<TData>( export function getStaticSegmentVaryPathForRequest<TData>(
fetchStrategy: FetchStrategy, stage: AppStage,
tree: RouteTree<TData> tree: RouteTree<TData>
): VaryPath { ): VaryPath {
if ( if (stage === AppStage.Shell) {
fetchStrategy === FetchStrategy.RuntimeShell ||
fetchStrategy === FetchStrategy.StaticShell
) {
return tree.shellVaryPath return tree.shellVaryPath
} }
// The vary path includes a search params entry only when the segment varies // The vary path includes a search params entry only when the segment varies
......
...@@ -446,12 +446,11 @@ function trackRuntimeDataAccessed( ...@@ -446,12 +446,11 @@ function trackRuntimeDataAccessed(
// static prefetch would hit) so it does not indicate the need for a runtime // static prefetch would hit) so it does not indicate the need for a runtime
// request and thus does not affect the static hints. // request and thus does not affect the static hints.
// //
// If runtime prefetches are not disallowed by `ensureStatic`, then we still // If `ensureStatic` doesn't disallow runtime prefetches, we still
// set `runtimeDataAccessed` (while keeping the hints static). This means that // set `runtimeDataAccessed`, but keep the hints static. So if we
// if the concrete prerender isn't ready yet and we served the fallback, then // serve the fallback, the client knows it needs more. It waits for
// the client knows it can use a *runtime* prefetch for speculative links -- // the concrete prerender first, and only sends a runtime request
// a runtime prefetch can provide the same content (or more) as the concrete // if that still needs runtime data, or if it gives up waiting.
// prerender would.
if (ensureStaticLevel < EnsureStaticLevel.Prefetch) { if (ensureStaticLevel < EnsureStaticLevel.Prefetch) {
markRuntimeDataAccessWhenStageReached( markRuntimeDataAccessWhenStageReached(
prerenderDataTracking, prerenderDataTracking,
......
...@@ -463,10 +463,10 @@ export type InitialRSCPayload = { ...@@ -463,10 +463,10 @@ export type InitialRSCPayload = {
*/ */
u?: Promise<boolean> u?: Promise<boolean>
/** /**
* shellByteLength - Resolves when the shell stage ends. * stageByteLengths - Where each stage ends; see
* If it resolves to null, then the shell is the same as the main response. * NavigationFlightResponse['a'].
* */ */
a?: Promise<number | null> a?: Promise<Array<number>>
/** runtimePrefetchStream — Embedded runtime prefetch Flight stream. */ /** runtimePrefetchStream — Embedded runtime prefetch Flight stream. */
p?: ReadableStream<Uint8Array> p?: ReadableStream<Uint8Array>
/** /**
...@@ -531,46 +531,34 @@ type NavigationFlightResponseBase = { ...@@ -531,46 +531,34 @@ type NavigationFlightResponseBase = {
* TransportSegmentData). */ * TransportSegmentData). */
s?: AsyncIterable<number> s?: AsyncIterable<number>
/** /**
* shellByteLength - Resolves when the shell stage ends. * stageByteLengths - The byte offset where each stage ends, in stage order
* If it resolves to null, then the shell is the same as the main response. * starting with the shell. A stage is listed only when a later stage added
* bytes; an unlisted stage ends at the end of the response, and so does the
* last stage, which is never listed. Absent when the response wasn't
* staged.
* *
* In a per-segment prefetch response this is the shell byte boundary the * Decoding the response up to a stage's offset reads it as of that stage.
* client uses for the shell double-decode: re-decoding the buffered * The shell prefix is the shell variant of every segment (param-dependent
* response truncated at the offset yields the shell variant of every * content reduced to still-pending references). In a per-segment prefetch
* segment (param-dependent content reduced to still-pending references). * response the offsets are the segment response's own, measured against a
* `0` means no shell exists (the page wasn't produced by staged * staged decode of the page. The resolution row flushes past every offset,
* rendering) — never a valid offset, so it doubles as the "none" * so a truncated decode reads it as pending, which is harmless.
* sentinel. The resolution row flushes past the boundary, so a truncated
* shell decode reads it as pending, which is harmless. The client's
* buffered read leans on the same fact from the other side: 0 read from
* an unfulfilled `a` implies a bug — see the shell-extraction comment in
* fetchAndWritePerSegmentPrefetchResponse (segment-cache/cache.ts).
*/ */
a?: Promise<number | null> a?: Promise<Array<number>>
/** /**
* needsRuntimeRequest — presence means the response carries a stage-scoped * Whether rendering this response read runtime data, like cookies or
* runtime-data verdict. Per-segment prefetch responses always emit one, * headers. Per-segment prefetch responses always send it, and so do pages
* and so does any prerendered page payload, which embeds the prerender's * served from a Cache Components prerender. Live renders never do. `true`
* runtime-data probe — that covers navigation responses served from * means a runtime request would return more than this response.
* prerender output and the truncated initial payload alike. Live renders *
* emit none. Only per-segment responses additionally promise-encode the * It's a promise so it rewinds with the stages. The row that resolves it
* head's partiality (see TransportSegmentData). The value is the page's * lands in the same stage as the access it records, so a decode cut off at
* runtime-data-access flag (the page payload's own `u`; per-segment * an earlier stage (see `a`) reads it as pending, which counts as `false`.
* responses forward it from the staged decode of the page data). * Segment responses for a page rendered without stages send it already
* Fulfilled `true` means a runtime prefetch would return more * resolved to `true`, so we never skip a runtime request we need.
* than this static response; pending or fulfilled `false` means it *
* wouldn't. Promise-encoded so the answer rewinds with a truncated * It's tracked for the whole page, not per segment, and it describes this
* decode: the fulfillment row lands on the same side of the shell byte * response, not the build.
* boundary (`a`) as the access it records. Tracking is page-global, so it
* lives on the response, not on each segment; per-segment granularity
* comes from combining it with each segment's partiality:
* needsRuntimeRequest(segment) = (settled true) && (isPartial pending).
* The derived value must never falsely claim that no runtime request is
* needed, so every fallback is conservative: pages that carry no `u`
* (legacy render paths) forward an already-resolved `true`. Unlike the
* build-constant prefetch hints, this is computed per render and may
* change between responses for the same build — it reflects THIS
* response.
*/ */
u?: Promise<boolean> u?: Promise<boolean>
/** /**
......
...@@ -145,6 +145,46 @@ describe('force stale', () => { ...@@ -145,6 +145,46 @@ describe('force stale', () => {
} }
) )
it(
'during a navigation, request the segments that a default prefetch ' +
'still in flight leaves out',
async () => {
let act: ReturnType<typeof createRouterAct>
const browser = await next.browser('/', {
beforePageLoad(p: Playwright.Page) {
act = createRouterAct(p)
},
})
await act(
async () => {
// Reveal a default link, and hold the prefetch response, so the
// navigation starts while it's still in flight. (Without Cache
// Components, this is a prefetch up to the loading boundary, so it
// leaves out the page below it.)
await act(
async () => {
const toggle = await browser.elementByCss(
'input[data-link-accordion="partially-static-default"]'
)
await toggle.click()
},
{ includes: 'Static layout content', block: true }
)
const link = await browser.elementById('partially-static-default')
await link.click()
},
// The navigation requests the page, instead of waiting for a
// prefetch that won't have it.
{ includes: 'Partially static page content' }
)
expect(await browser.elementById('partially-static-page').text()).toBe(
'Partially static page content'
)
}
)
it( it(
'a default link does not re-request data already fetched by a ' + 'a default link does not re-request data already fetched by a ' +
'prefetch={true} link to the same URL', 'prefetch={true} link to the same URL',
......
import type { Metadata } from 'next'
import type { ReactNode } from 'react'
export const metadata: Metadata = {
title: 'Home',
}
export default function Root({ children }: { children: ReactNode }) {
return (
<html>
<body>{children}</body>
</html>
)
}
import type { Metadata } from 'next'
import { connection } from 'next/server'
export const metadata: Metadata = {
title: 'Detail title',
}
// /shared/destination/loading.tsx is the nearest loading boundary.
export default async function Page() {
await connection()
return <p id="detail">Detail content</p>
}
export default function Loading() {
return <p id="loading">Loading destination...</p>
}
import type { Metadata } from 'next'
import { connection } from 'next/server'
export const metadata: Metadata = {
title: 'Destination title',
}
export default async function Page() {
await connection()
return <p id="destination">Destination content</p>
}
import type { Metadata } from 'next'
import { connection } from 'next/server'
import { LinkAccordion } from '../../components/link-accordion'
export const metadata: Metadata = {
title: 'Shared title',
}
// A dynamic layout that stays mounted while navigating between its children.
export default async function SharedLayout({
children,
}: {
children: React.ReactNode
}) {
await connection()
return (
<>
<ul>
<li>
<LinkAccordion href="/shared/destination">Destination</LinkAccordion>
</li>
<li>
<LinkAccordion href="/shared/destination/detail">
Detail
</LinkAccordion>
</li>
</ul>
<div>{children}</div>
</>
)
}
export default function Page() {
return <p id="index">Index content</p>
}
'use client'
import Link from 'next/link'
import { useState } from 'react'
export function LinkAccordion({
href,
children,
}: {
href: string
children: React.ReactNode
}) {
const [isVisible, setIsVisible] = useState(false)
return (
<>
<input
type="checkbox"
checked={isVisible}
onChange={() => setIsVisible(!isVisible)}
data-link-accordion={href}
/>
{isVisible ? (
<Link href={href}>{children}</Link>
) : (
<>{children} (link is hidden)</>
)}
</>
)
}
import { nextTestSetup } from 'e2e-utils'
import type * as Playwright from 'playwright'
import { createRouterAct } from 'router-act'
import { retry } from 'next-test-utils'
// A prefetch up to a loading boundary doesn't deliver the segments below the
// boundary. A navigation that starts during that prefetch still shows the
// boundary, and gets those segments itself.
// @force-gate prefetching
describe('navigating while a loading boundary prefetch is in flight', () => {
const { next } = nextTestSetup({
files: __dirname,
})
it('shows the loading boundary when the prefetch lands before the navigation', async () => {
let act: ReturnType<typeof createRouterAct>
const browser = await next.browser('/shared', {
beforePageLoad(p: Playwright.Page) {
act = createRouterAct(p)
},
})
await act(async () => {
await act(
async () => {
// Reveal the link, and hold its prefetch.
await act(
async () => {
await browser
.elementByCss(
'input[data-link-accordion="/shared/destination"]'
)
.click()
},
{ includes: 'Loading destination...', block: true }
)
// Navigate while the prefetch is in flight, and hold the
// navigation's own response.
await browser.elementByCss('a[href="/shared/destination"]').click()
},
{ includes: 'Destination content', block: true }
)
// The prefetch has landed, but the navigation's response hasn't.
expect(await browser.elementById('loading').text()).toBe(
'Loading destination...'
)
})
expect(await browser.elementById('destination').text()).toBe(
'Destination content'
)
await retry(async () => {
expect(await browser.eval('document.title')).toBe('Destination title')
})
})
it('keeps the title when navigating twice while prefetches are in flight', async () => {
let act: ReturnType<typeof createRouterAct>
const browser = await next.browser('/shared', {
beforePageLoad(p: Playwright.Page) {
act = createRouterAct(p)
},
})
await act(async () => {
await act(
async () => {
// Reveal both links, and hold their prefetches. The second link's
// segments above the loading boundary are already on their way, so
// its prefetch may contain nothing but its route tree. Its route
// tree prefetch carries the same tree, so claim that one first.
await act(async () => {
await browser
.elementByCss('input[data-link-accordion="/shared/destination"]')
.click()
await browser
.elementByCss(
'input[data-link-accordion="/shared/destination/detail"]'
)
.click()
}, [
{ includes: '"detail"', kind: 'static' },
{ includes: 'Loading destination...', block: true },
{ includes: '"detail"', block: true },
])
// Navigate twice in a row while those prefetches are in flight. The
// second navigation starts before the first one commits. Hold the
// second navigation's own response.
await browser.elementByCss('a[href="/shared/destination"]').click()
await browser
.elementByCss('a[href="/shared/destination/detail"]')
.click()
},
{ includes: 'Detail content', block: true }
)
})
expect(await browser.elementById('detail').text()).toBe('Detail content')
await retry(async () => {
expect(await browser.eval('document.title')).toBe('Detail title')
})
})
})
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