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 {
mountFormInstance,
unmountPrefetchableInstance,
} from '../components/links'
import { FetchStrategy } from '../components/segment-cache/types'
import { AppStage } from '../components/segment-cache/types'
export type { FormProps }
......@@ -100,13 +100,7 @@ export default function Form({
const observeFormVisibilityOnMount = useCallback(
(element: HTMLFormElement) => {
if (isPrefetchEnabled && router !== null) {
mountFormInstance(
element,
actionProp,
router,
// We default to PPR. We'll discover whether or not the route supports it with the initial prefetch.
FetchStrategy.PPR
)
mountFormInstance(element, actionProp, router, AppStage.Shell)
}
return () => {
unmountPrefetchableInstance(element)
......
......@@ -18,10 +18,7 @@ import {
type LinkInstance,
} from '../components/links'
import { isLocalURL } from '../../shared/lib/router/utils/is-local-url'
import {
FetchStrategy,
type PrefetchTaskFetchStrategy,
} from '../components/segment-cache/types'
import { AppStage } from '../components/segment-cache/types'
import type { RouterTransitionPrefetchIntent } from '../router-transition-types'
type Url = string | UrlObject
......@@ -382,11 +379,9 @@ export default function LinkComponent(
const prefetchIntent: RouterTransitionPrefetchIntent =
prefetchProp === false ? 'none' : prefetchProp === true ? 'full' : 'auto'
const fetchStrategy =
prefetchIntent !== 'none'
? getFetchStrategyFromPrefetchIntent(prefetchIntent)
: // TODO: it makes no sense to assign a fetchStrategy when prefetching is disabled.
FetchStrategy.PPR
// TODO: it makes no sense to assign a stage when prefetching is disabled.
const prefetchStage =
prefetchProp === true ? AppStage.Prefetch : AppStage.Shell
if (process.env.NODE_ENV !== 'production') {
function createPropError(args: {
......@@ -610,11 +605,11 @@ export default function LinkComponent(
// Only capture when a warning might actually need it. Otherwise leave
// it `undefined` so consumers can detect the opt-out and degrade
// gracefully.
if (fetchStrategy === FetchStrategy.Full) {
if (prefetchStage !== AppStage.Shell) {
return React.captureOwnerStack()
}
return undefined
}, [fetchStrategy])
}, [prefetchStage])
: undefined
// Use a callback ref to attach an IntersectionObserver to the anchor tag on
......@@ -628,7 +623,7 @@ export default function LinkComponent(
element,
formattedHref,
router,
fetchStrategy,
prefetchStage,
prefetchEnabled,
setOptimisticLinkStatus,
ownerStack
......@@ -647,7 +642,7 @@ export default function LinkComponent(
prefetchEnabled,
formattedHref,
router,
fetchStrategy,
prefetchStage,
setOptimisticLinkStatus,
ownerStack,
]
......@@ -804,24 +799,3 @@ const LinkStatusContext = createContext<
export const useLinkStatus = () => {
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 {
} from './segment-cache/cache-key'
import type { CacheMap } from './segment-cache/cache-map'
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 type { AppRouterState } from './router-reducer/router-reducer-types'
import { ScrollBehavior } from './router-reducer/router-reducer-types'
......@@ -277,7 +277,7 @@ export function navigateToKnownRoute(
const link = getLinkForCurrentNavigation()
if (
link !== null &&
link.fetchStrategy === FetchStrategy.Full &&
link.prefetchStage !== AppStage.Shell &&
(navigationSeed.root.tree.prefetchHints &
(PrefetchHint.SubtreeHasPartialPrefetching |
PrefetchHint.SubtreeHasInstantFalse)) ===
......@@ -313,7 +313,7 @@ export function navigateToKnownRoute(
const link = getLinkForCurrentNavigation()
restrictToShell = shouldRestrictNavigationToShell(
navigationSeed.root.tree.prefetchHints,
link !== null ? link.fetchStrategy : FetchStrategy.PPR
link !== null ? link.prefetchStage : AppStage.Shell
)
}
......@@ -833,7 +833,7 @@ async function ensurePrefetchThenNavigate(
navigationLock: NavigationLock | null
): Promise<AppRouterState> {
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)
......@@ -848,7 +848,7 @@ async function ensurePrefetchThenNavigate(
const prefetchTask = schedulePrefetchTask(
cacheKey,
currentRoot,
fetchStrategy,
prefetchStage,
PrefetchPriority.Default,
null, // onInvalidate
navigationLockPrefetch
......
import type { RootRouteTree } from './segment-cache/cache'
import type { CacheNode } from '../../shared/lib/app-router-types'
import type { AppRouterInstance } from '../../shared/lib/app-router-context.shared-runtime'
import {
FetchStrategy,
type PrefetchTaskFetchStrategy,
PrefetchPriority,
} from './segment-cache/types'
import { AppStage, PrefetchPriority } from './segment-cache/types'
import { createCacheKey } from './segment-cache/cache-key'
import {
type PrefetchTask,
......@@ -24,7 +20,7 @@ type Element = LinkElement | HTMLFormElement
// shape for both to prevent a polymorphic de-opt in the VM.
type LinkOrFormInstanceShared = {
router: AppRouterInstance
fetchStrategy: PrefetchTaskFetchStrategy
prefetchStage: AppStage
isVisible: boolean
......@@ -172,7 +168,7 @@ export function mountLinkInstance(
element: LinkElement,
href: string,
router: AppRouterInstance,
fetchStrategy: PrefetchTaskFetchStrategy,
prefetchStage: AppStage,
prefetchEnabled: boolean,
setOptimisticLinkStatus: (status: { pending: boolean }) => void,
ownerStack: string | null | undefined
......@@ -182,7 +178,7 @@ export function mountLinkInstance(
if (prefetchURL !== null) {
const instance: PrefetchableLinkInstance = {
router,
fetchStrategy,
prefetchStage,
isVisible: false,
prefetchTask: null,
prefetchHref: prefetchURL.href,
......@@ -199,7 +195,7 @@ export function mountLinkInstance(
// track its optimistic state (i.e. useLinkStatus).
const instance: NonPrefetchableLinkInstance = {
router,
fetchStrategy,
prefetchStage,
isVisible: false,
prefetchTask: null,
prefetchHref: null,
......@@ -213,7 +209,7 @@ export function mountFormInstance(
element: HTMLFormElement,
href: string,
router: AppRouterInstance,
fetchStrategy: PrefetchTaskFetchStrategy
prefetchStage: AppStage
): void {
const prefetchURL = coercePrefetchableUrl(href)
if (prefetchURL === null) {
......@@ -225,7 +221,7 @@ export function mountFormInstance(
}
const instance: FormInstance = {
router,
fetchStrategy,
prefetchStage,
isVisible: false,
prefetchTask: null,
prefetchHref: prefetchURL.href,
......@@ -305,7 +301,7 @@ export function onNavigationIntent(
unstable_upgradeToDynamicPrefetch
) {
// Switch to a full prefetch
instance.fetchStrategy = FetchStrategy.Full
instance.prefetchStage = AppStage.Navigation
}
rescheduleLinkPrefetch(instance, PrefetchPriority.Intent)
}
......@@ -346,7 +342,7 @@ function rescheduleLinkPrefetch(
instance.prefetchTask = scheduleSegmentPrefetchTask(
cacheKey,
appRouterState.root,
instance.fetchStrategy,
instance.prefetchStage,
priority,
null,
null // navigationLockPrefetch
......@@ -357,7 +353,7 @@ function rescheduleLinkPrefetch(
reschedulePrefetchTask(
existingPrefetchTask,
appRouterState.root,
instance.fetchStrategy,
instance.prefetchStage,
priority
)
}
......@@ -392,7 +388,7 @@ export function pingVisibleLinks(
instance.prefetchTask = scheduleSegmentPrefetchTask(
cacheKey,
root,
instance.fetchStrategy,
instance.prefetchStage,
PrefetchPriority.Default,
null,
null // navigationLockPrefetch
......
......@@ -6,15 +6,11 @@ import { getCurrentAppRouterState } from './app-router-instance'
import { isJavaScriptURLString } from '../lib/javascript-url'
import { createCacheKey } from './segment-cache/cache-key'
import { schedulePrefetchTask } from './segment-cache/scheduler'
import {
FetchStrategy,
PrefetchPriority,
type PrefetchTaskFetchStrategy,
} from './segment-cache/types'
import { AppStage, PrefetchPriority } from './segment-cache/types'
/**
* 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.
*
* 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 {
const prefetchKind = options?.kind ?? 'auto'
// We don't currently offer a way to issue a runtime prefetch via `router.prefetch()`.
let fetchStrategy: PrefetchTaskFetchStrategy
let prefetchStage: AppStage
switch (prefetchKind) {
case 'auto': {
// We default to PPR. We'll discover whether or not the route supports it with the initial prefetch.
fetchStrategy = FetchStrategy.PPR
prefetchStage = AppStage.Shell
break
}
case 'full': {
fetchStrategy = FetchStrategy.Full
prefetchStage = AppStage.Prefetch
break
}
default: {
......@@ -53,7 +48,7 @@ export function prefetchRoute(href: string, options?: PrefetchOptions): void {
// we might get an unexpected value from user code.
// We don't know what they want, but we know they want a prefetch,
// so use the default.
fetchStrategy = FetchStrategy.PPR
prefetchStage = AppStage.Shell
}
}
......@@ -61,7 +56,7 @@ export function prefetchRoute(href: string, options?: PrefetchOptions): void {
href,
state.nextUrl,
state.root,
fetchStrategy,
prefetchStage,
options?.onInvalidate ?? null
)
}
......@@ -74,8 +69,7 @@ export function prefetchRoute(href: string, options?: PrefetchOptions): void {
* Roughly corresponds to the current URL.
* @param renderTreeAtTimeOfPrefetch - The active render tree and head, and
* their vary paths.
* @param fetchStrategy - Whether to prefetch dynamic data, in addition to
* static data. This is used by `<Link prefetch={true}>`.
* @param prefetchStage - The stage to prefetch up to.
* @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
* prefetch may have been invalidated from the cache. This is not a live
......@@ -90,7 +84,7 @@ export function prefetch(
href: string,
nextUrl: string | null,
renderTreeAtTimeOfPrefetch: RootRouteTree<CacheNode>,
fetchStrategy: PrefetchTaskFetchStrategy,
prefetchStage: AppStage,
onInvalidate: null | (() => void)
) {
const url = createPrefetchURL(href)
......@@ -102,7 +96,7 @@ export function prefetch(
schedulePrefetchTask(
cacheKey,
renderTreeAtTimeOfPrefetch,
fetchStrategy,
prefetchStage,
PrefetchPriority.Default,
onInvalidate,
null // navigationLockPrefetch
......
......@@ -39,6 +39,7 @@ import {
MetadataOnlyRequestTree,
} from './segment-cache/cache'
import { discoverKnownRoute } from './segment-cache/optimistic-routes'
import { Completeness } from './segment-cache/types'
import type { NormalizedSearch } from './segment-cache/cache-key'
import type { CacheMap } from './segment-cache/cache-map'
import {
......@@ -1137,7 +1138,8 @@ function createRenderTreeForSegment(
case EntryStatus.Fulfilled: {
// Happy path: a cache hit
cachedRsc = segmentEntry.rsc
isCachedRscPartial = segmentEntry.isPartial
isCachedRscPartial =
segmentEntry.completeness !== Completeness.FullyComplete
cachedVaryParams = segmentEntry.varyParams
break
}
......@@ -1157,11 +1159,11 @@ function createRenderTreeForSegment(
// do yet another request to fill in the remaining data, creating
// a waterfall.
//
// The one exception is if this segment is being fetched with via
// prefetch={true} (i.e. the "force stale" or "full" strategy). If so,
// we can assume the response will be full. This field is set to `false`
// for such segments.
isCachedRscPartial = segmentEntry.isPartial
// The exception is a request we expect to return the segment fully
// complete, like a legacy prefetch. If so, we can assume the response
// will have nothing left to request.
isCachedRscPartial =
segmentEntry.completeness !== Completeness.FullyComplete
break
}
case EntryStatus.Empty:
......
......@@ -15,7 +15,7 @@
import type { FlightRouterState } from '../../../shared/lib/app-router-types'
import type { SegmentCacheEntry } from './cache'
import type { CacheMap } from './cache-map'
import type { FetchStrategy } from './types'
import type { AppStage } from './types'
import type { NavigationLockPrefetch } from './navigation-testing-lock'
export type {
......@@ -62,7 +62,7 @@ export function resetNavigationLockToPending(): void {}
export function shouldRestrictNavigationToShell(
_rootPrefetchHints: number,
_linkFetchStrategy: FetchStrategy
_linkPrefetchStage: AppStage
): boolean {
return false
}
......@@ -25,10 +25,9 @@ import {
} from '../../../shared/lib/app-router-types'
import { NEXT_INSTANT_TEST_COOKIE } from '../app-router-headers'
import { refreshOnInstantNavigationUnlock } from '../use-action-queue'
import { needsSpeculativePrefetch } from './scheduler'
import type { SegmentCacheEntry } from './cache'
import { createCacheMap, type CacheMap } from './cache-map'
import type { PrefetchTaskFetchStrategy } from './types'
import { AppStage } from './types'
type InstantNavCookieState = 'empty' | 'pending' | 'mpa' | 'spa'
......@@ -543,11 +542,11 @@ export function getCurrentNavigationGate(): Promise<void> | null {
*/
export function shouldRestrictNavigationToShell(
rootPrefetchHints: number,
linkFetchStrategy: PrefetchTaskFetchStrategy
linkPrefetchStage: AppStage
): boolean {
return (
isNavigationLocked() &&
(rootPrefetchHints & PrefetchHint.SubtreeHasPartialPrefetching) !== 0 &&
!needsSpeculativePrefetch(linkFetchStrategy, rootPrefetchHints)
linkPrefetchStage === AppStage.Shell
)
}
......@@ -31,44 +31,40 @@ export const enum PrefetchPriority {
Background = 0,
}
export const enum FetchStrategy {
// Deliberately ordered so we can easily compare two segments
// and determine if one segment is "more specific" than another
// (i.e. if it's likely that it contains more data). See
// canNewFetchStrategyProvideMoreContent in cache.ts for what each tier can
// contain relative to the others.
//
// Full and LoadingBoundary belong to the non-Partial-Prefetching regime:
// they're only relevant in modes where the staging concepts (shell tiers,
// runtime prefetches) don't apply. They sit on this single ordered ladder
// as an accepted convenience, because cross-regime comparisons exist
// (e.g. canNewFetchStrategyProvideMoreContent).
//
// These numeric values are client-internal and never cross the wire — the
// `next-router-prefetch` request header values are mapped explicitly in
// fetchSegmentPrefetchesUsingRuntimeRequest (cache.ts) — so the members can
// be renumbered freely as long as the relative order is preserved.
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,
/**
* How far a render went, in the app's public stages (not the server's
* render stages). Each stage includes everything before it. A link asks for a
* stage; a cache entry records the stage its payload reached.
*
* Ordered, so two stages can be compared. Never compare a stage with a
* `Completeness`.
*/
export const enum AppStage {
// The app shell: shared by every link to the route, so param-dependent
// content is reduced to fallbacks.
Shell = 0,
// Up to where `prefetch()` resolves.
Prefetch = 1,
// Up to where `navigation()` resolves: what a navigation renders,
// minus dynamic holes.
Navigation = 2,
}
/**
* A subset of fetch strategies used for prefetch tasks.
* A prefetch task can't know if it should use `PPR` or `LoadingBoundary`
* 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.
* */
export type PrefetchTaskFetchStrategy = FetchStrategy.PPR | FetchStrategy.Full
* What's still missing at an entry's stage. Each level promises everything
* the previous one does.
*
* Ordered, so two values can be compared. Never compare it with an
* `AppStage`.
*/
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 {
NormalizedPathname,
NormalizedSearch,
......@@ -210,17 +210,17 @@ export function getPartialVaryPath(
}
export function getSegmentVaryPathForRequest<TData>(
fetchStrategy: FetchStrategy,
stage: AppStage,
tree: RouteTree<TData>
): VaryPath {
// 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
// that it can be reused as much as possible.
// the most generic vary path the request's expected output allows, so that
// it can be reused as much as possible.
//
// 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
// 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
// route tree object. The shell vary path is precomputed there too.
......@@ -231,36 +231,28 @@ export function getSegmentVaryPathForRequest<TData>(
// 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
// params that can be treated as Fallback. (Or perhaps the inverse.)
if (
fetchStrategy === FetchStrategy.RuntimeShell ||
fetchStrategy === FetchStrategy.StaticShell
) {
// Both shell strategies produce the App Shell variant of a segment —
// RuntimeShell via a runtime render with non-root params omitted,
// 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).
if (stage === AppStage.Shell) {
// The shell reduces param-dependent content to fallbacks, whether a
// 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
// shell vary path. That's the vary path with every non-root param
// replaced by Fallback. Root params keep their values.
return tree.shellVaryPath
}
return tree.varyPath
}
/**
* The vary path a pending entry is stored under when its response never
* varies on search params: every strategy except Full and PPRRuntime. Like
* getSegmentVaryPathForRequest, except that the entry can be reused across
* all possible search param values.
* The vary path a static request's pending entry is stored under. Like
* getSegmentVaryPathForRequest, except that a static request's expected vary
* params never include search params (search params are runtime data), so
* its entry can be reused across all possible search param values.
*/
export function getStaticSegmentVaryPathForRequest<TData>(
fetchStrategy: FetchStrategy,
stage: AppStage,
tree: RouteTree<TData>
): VaryPath {
if (
fetchStrategy === FetchStrategy.RuntimeShell ||
fetchStrategy === FetchStrategy.StaticShell
) {
if (stage === AppStage.Shell) {
return tree.shellVaryPath
}
// The vary path includes a search params entry only when the segment varies
......
......@@ -446,12 +446,11 @@ function trackRuntimeDataAccessed(
// static prefetch would hit) so it does not indicate the need for a runtime
// request and thus does not affect the static hints.
//
// If runtime prefetches are not disallowed by `ensureStatic`, then we still
// set `runtimeDataAccessed` (while keeping the hints static). This means that
// if the concrete prerender isn't ready yet and we served the fallback, then
// the client knows it can use a *runtime* prefetch for speculative links --
// a runtime prefetch can provide the same content (or more) as the concrete
// prerender would.
// If `ensureStatic` doesn't disallow runtime prefetches, we still
// set `runtimeDataAccessed`, but keep the hints static. So if we
// serve the fallback, the client knows it needs more. It waits for
// the concrete prerender first, and only sends a runtime request
// if that still needs runtime data, or if it gives up waiting.
if (ensureStaticLevel < EnsureStaticLevel.Prefetch) {
markRuntimeDataAccessWhenStageReached(
prerenderDataTracking,
......
......@@ -463,10 +463,10 @@ export type InitialRSCPayload = {
*/
u?: Promise<boolean>
/**
* shellByteLength - Resolves when the shell stage ends.
* If it resolves to null, then the shell is the same as the main response.
* */
a?: Promise<number | null>
* stageByteLengths - Where each stage ends; see
* NavigationFlightResponse['a'].
*/
a?: Promise<Array<number>>
/** runtimePrefetchStream — Embedded runtime prefetch Flight stream. */
p?: ReadableStream<Uint8Array>
/**
......@@ -531,46 +531,34 @@ type NavigationFlightResponseBase = {
* TransportSegmentData). */
s?: AsyncIterable<number>
/**
* shellByteLength - Resolves when the shell stage ends.
* If it resolves to null, then the shell is the same as the main response.
* stageByteLengths - The byte offset where each stage ends, in stage order
* 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
* client uses for the shell double-decode: re-decoding the buffered
* response truncated at the offset yields the shell variant of every
* segment (param-dependent content reduced to still-pending references).
* `0` means no shell exists (the page wasn't produced by staged
* rendering) — never a valid offset, so it doubles as the "none"
* 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).
* Decoding the response up to a stage's offset reads it as of that stage.
* The shell prefix is the shell variant of every segment (param-dependent
* content reduced to still-pending references). In a per-segment prefetch
* response the offsets are the segment response's own, measured against a
* staged decode of the page. The resolution row flushes past every offset,
* so a truncated decode reads it as pending, which is harmless.
*/
a?: Promise<number | null>
a?: Promise<Array<number>>
/**
* needsRuntimeRequest — presence means the response carries a stage-scoped
* runtime-data verdict. Per-segment prefetch responses always emit one,
* and so does any prerendered page payload, which embeds the prerender's
* runtime-data probe — that covers navigation responses served from
* prerender output and the truncated initial payload alike. Live renders
* emit none. Only per-segment responses additionally promise-encode the
* head's partiality (see TransportSegmentData). The value is the page's
* runtime-data-access flag (the page payload's own `u`; per-segment
* responses forward it from the staged decode of the page data).
* Fulfilled `true` means a runtime prefetch would return more
* than this static response; pending or fulfilled `false` means it
* wouldn't. Promise-encoded so the answer rewinds with a truncated
* decode: the fulfillment row lands on the same side of the shell byte
* 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.
* Whether rendering this response read runtime data, like cookies or
* headers. Per-segment prefetch responses always send it, and so do pages
* served from a Cache Components prerender. Live renders never do. `true`
* means a runtime request would return more than this response.
*
* It's a promise so it rewinds with the stages. The row that resolves it
* lands in the same stage as the access it records, so a decode cut off at
* an earlier stage (see `a`) reads it as pending, which counts as `false`.
* Segment responses for a page rendered without stages send it already
* resolved to `true`, so we never skip a runtime request we need.
*
* It's tracked for the whole page, not per segment, and it describes this
* response, not the build.
*/
u?: Promise<boolean>
/**
......
......@@ -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(
'a default link does not re-request data already fetched by a ' +
'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