Commit 8719a85b authored by Janka Uryga's avatar Janka Uryga

runtime prefetches: client side

parent 8aee5cc8
......@@ -769,5 +769,6 @@
"768": "createPrerenderSearchParamsForClientPage should not be called in a runtime prerender.",
"769": "createSearchParamsFromClient should not be called in a runtime prerender.",
"770": "createParamsFromClient should not be called in a runtime prerender.",
"771": "\\`%s\\` was called during a runtime prerender. Next.js should be preventing %s from being included in server components statically, but did not in this case."
"771": "\\`%s\\` was called during a runtime prerender. Next.js should be preventing %s from being included in server components statically, but did not in this case.",
"772": "FetchStrategy.PPRRuntime should never be used when `experimental.clientSegmentCache` is disabled"
}
......@@ -61,6 +61,7 @@ export default function Form({
}
}
// TODO(runtime-ppr): allow runtime prefetches in Form
const prefetch =
prefetchProp === false || prefetchProp === null ? prefetchProp : null
......
......@@ -20,7 +20,10 @@ import {
import { isLocalURL } from '../../shared/lib/router/utils/is-local-url'
import { dispatchNavigateAction } from '../components/app-router-instance'
import { errorOnce } from '../../shared/lib/utils/error-once'
import { FetchStrategy } from '../components/segment-cache'
import {
FetchStrategy,
type PrefetchTaskFetchStrategy,
} from '../components/segment-cache'
type Url = string | UrlObject
type RequiredKeys<T> = {
......@@ -151,10 +154,10 @@ type InternalLinkProps = {
* </Link>
* ```
*/
prefetch?: boolean | 'auto' | null
prefetch?: boolean | 'auto' | null | 'unstable_forceStale'
/**
* (unstable) Switch to a dynamic prefetch on hover. Effectively the same as
* (unstable) Switch to a full prefetch on hover. Effectively the same as
* updating the prefetch prop to `true` in a mouse event.
*/
unstable_dynamicOnHover?: boolean
......@@ -356,18 +359,12 @@ export default function LinkComponent(
const router = React.useContext(AppRouterContext)
const prefetchEnabled = prefetchProp !== false
/**
* The possible states for prefetch are:
* - null: this is the default "auto" mode, where we will prefetch partially if the link is in the viewport
* - true: we will prefetch if the link is visible and prefetch the full page, not just partially
* - false: we will not prefetch if in the viewport at all
* - 'unstable_dynamicOnHover': this starts in "auto" mode, but switches to "full" when the link is hovered
*/
const fetchStrategy =
prefetchProp === null || prefetchProp === 'auto'
? // We default to PPR. We'll discover whether or not the route supports it with the initial prefetch.
prefetchProp !== false
? getFetchStrategyFromPrefetchProp(prefetchProp)
: // TODO: it makes no sense to assign a fetchStrategy when prefetching is disabled.
FetchStrategy.PPR
: FetchStrategy.Full
if (process.env.NODE_ENV !== 'production') {
function createPropError(args: {
......@@ -470,11 +467,12 @@ export default function LinkComponent(
if (
props[key] != null &&
valType !== 'boolean' &&
props[key] !== 'auto'
props[key] !== 'auto' &&
props[key] !== 'unstable_forceStale'
) {
throw createPropError({
key,
expected: '`boolean | "auto"`',
expected: '`boolean | "auto" | "unstable_forceStale"`',
actual: valType,
})
}
......@@ -745,3 +743,41 @@ const LinkStatusContext = createContext<
export const useLinkStatus = () => {
return useContext(LinkStatusContext)
}
function getFetchStrategyFromPrefetchProp(
prefetchProp: Exclude<LinkProps['prefetch'], undefined | false>
): PrefetchTaskFetchStrategy {
if (
process.env.__NEXT_CACHE_COMPONENTS &&
process.env.__NEXT_CLIENT_SEGMENT_CACHE
) {
// In the new implementation:
// - `prefetch={true}` is a runtime prefetch
// (includes cached IO + params + cookies, with dynamic holes for uncached IO).
// - `unstable_forceStale` is a "full" prefetch
// (forces inclusion of all dynamic data, i.e. the old behavior of `prefetch={true}`)
if (prefetchProp === true) {
return FetchStrategy.PPRRuntime
}
if (prefetchProp === 'unstable_forceStale') {
return FetchStrategy.Full
}
// `null` or `"auto"`: this is the default "auto" mode, where we will prefetch partially if the link is in the viewport.
// This will also include invalid prop values that don't match the types specified here.
// (although those should've been filtered out by prop validation in dev)
prefetchProp satisfies null | 'auto'
// In `clientSegmentCache`, we default to PPR, and we'll discover whether or not the route supports it with the initial prefetch.
// If we're not using `clientSegmentCache`, this will be converted into a `PrefetchKind.AUTO`.
return FetchStrategy.PPR
} else {
return prefetchProp === null || prefetchProp === 'auto'
? // In `clientSegmentCache`, we default to PPR, and we'll discover whether or not the route supports it with the initial prefetch.
// If we're not using `clientSegmentCache`, this will be converted into a `PrefetchKind.AUTO`.
FetchStrategy.PPR
: // In the old implementation without runtime prefetches, `prefetch={true}` forces all dynamic data to be prefetched.
// To preserve backwards-compatibility, anything other than `false`, `null`, or `"auto"` results in a full prefetch.
// (although invalid values should've been filtered out by prop validation in dev)
FetchStrategy.Full
}
}
......@@ -329,6 +329,8 @@ export const publicAppRouterInstance: AppRouterInstance = {
const actionQueue = getAppRouterActionQueue()
const prefetchKind = options?.kind ?? PrefetchKind.AUTO
// We don't currently offer a way to issue a runtime prefetch via `router.prefetch()`.
// This will be possible when we update its API to not take a PrefetchKind.
let fetchStrategy: PrefetchTaskFetchStrategy
switch (prefetchKind) {
case PrefetchKind.AUTO: {
......
......@@ -17,6 +17,7 @@ import {
} from './segment-cache'
import { startTransition } from 'react'
import { PrefetchKind } from './router-reducer/router-reducer-types'
import { InvariantError } from '../../shared/lib/invariant-error'
type LinkElement = HTMLAnchorElement | SVGAElement
......@@ -264,7 +265,7 @@ export function onNavigationIntent(
process.env.__NEXT_DYNAMIC_ON_HOVER &&
unstable_upgradeToDynamicPrefetch
) {
// Switch to a full, dynamic prefetch
// Switch to a full prefetch
instance.fetchStrategy = FetchStrategy.Full
}
rescheduleLinkPrefetch(instance, PrefetchPriority.Intent)
......@@ -378,6 +379,13 @@ function prefetchWithOldCacheImplementation(instance: PrefetchableInstance) {
prefetchKind = PrefetchKind.FULL
break
}
case FetchStrategy.PPRRuntime: {
// We can only get here if Client Segment Cache is off, and in that case
// it shouldn't be possible for a link to request a runtime prefetch.
throw new InvariantError(
'FetchStrategy.PPRRuntime should never be used when `experimental.clientSegmentCache` is disabled'
)
}
default: {
instance.fetchStrategy satisfies never
// Unreachable, but otherwise typescript will consider the variable unassigned
......
......@@ -414,7 +414,9 @@ export function getSegmentKeypathForTask(
// the cache key, because the search params are treated as dynamic data. The
// cache entry is valid for all possible search param values.
const isDynamicTask =
task.fetchStrategy === FetchStrategy.Full || !route.isPPREnabled
task.fetchStrategy === FetchStrategy.Full ||
task.fetchStrategy === FetchStrategy.PPRRuntime ||
!route.isPPREnabled
return isDynamicTask && path.endsWith('/' + PAGE_SEGMENT_KEY)
? [path, route.renderedSearch]
: [path]
......@@ -639,11 +641,21 @@ export function upsertSegmentEntry(
// this function and confirming it's the same as `existingEntry`.
const existingEntry = readExactSegmentCacheEntry(now, keypath)
if (existingEntry !== null) {
if (candidateEntry.isPartial && !existingEntry.isPartial) {
// Don't replace a full segment with a partial one. A case where this
// might happen is if the existing segment was fetched via
// <Link prefetch={true}>.
// Don't replace a more specific segment with a less-specific one. A case where this
// might happen is if the existing segment was fetched via
// `<Link prefetch={true}>`.
if (
// We fetched the new segment using a different, less specific fetch strategy
// than the segment we already have in the cache, so it can't have more content.
(candidateEntry.fetchStrategy !== existingEntry.fetchStrategy &&
!canNewFetchStrategyProvideMoreContent(
existingEntry.fetchStrategy,
candidateEntry.fetchStrategy
)) ||
// The existing entry isn't partial, but the new one is.
// (TODO: can this be true if `candidateEntry.fetchStrategy >= existingEntry.fetchStrategy`?)
(!existingEntry.isPartial && candidateEntry.isPartial)
) {
// We're going to leave the entry on the owner's `revalidating` field
// so that it doesn't get revalidated again unnecessarily. Downgrade the
// Fulfilled entry to Rejected and null out the data so it can be garbage
......@@ -655,6 +667,7 @@ export function upsertSegmentEntry(
rejectedEntry.rsc = null
return null
}
// Evict the existing entry from the cache.
deleteSegmentFromCache(existingEntry, keypath)
}
......@@ -1355,7 +1368,10 @@ export async function fetchSegmentOnCacheMiss(
export async function fetchSegmentPrefetchesUsingDynamicRequest(
task: PrefetchTask,
route: FulfilledRouteCacheEntry,
fetchStrategy: FetchStrategy.LoadingBoundary | FetchStrategy.Full,
fetchStrategy:
| FetchStrategy.LoadingBoundary
| FetchStrategy.PPRRuntime
| FetchStrategy.Full,
dynamicRequestTree: FlightRouterState,
spawnedEntries: Map<string, PendingSegmentCacheEntry>
): Promise<PrefetchSubtaskResult<null> | null> {
......@@ -1370,13 +1386,26 @@ export async function fetchSegmentPrefetchesUsingDynamicRequest(
if (nextUrl !== null) {
headers[NEXT_URL] = nextUrl
}
// Only set the prefetch header if we're not doing a "full" prefetch. We
// omit the prefetch header from a full prefetch because it's essentially
// just a navigation request that happens ahead of time — it should include
// all the same data in the response.
if (fetchStrategy !== FetchStrategy.Full) {
headers[NEXT_ROUTER_PREFETCH_HEADER] = '1'
switch (fetchStrategy) {
case FetchStrategy.Full: {
// We omit the prefetch header from a full prefetch because it's essentially
// just a navigation request that happens ahead of time — it should include
// all the same data in the response.
break
}
case FetchStrategy.PPRRuntime: {
headers[NEXT_ROUTER_PREFETCH_HEADER] = '2'
break
}
case FetchStrategy.LoadingBoundary: {
headers[NEXT_ROUTER_PREFETCH_HEADER] = '1'
break
}
default: {
fetchStrategy satisfies never
}
}
try {
const response = await fetchPrefetchResponse(url, headers)
if (!response || !response.ok || !response.body) {
......@@ -1425,9 +1454,13 @@ export async function fetchSegmentPrefetchesUsingDynamicRequest(
prefetchStream
) as Promise<NavigationFlightResponse>)
// Since we did not set the prefetch header, the response from the server
// will never contain dynamic holes.
const isResponsePartial = false
const isResponsePartial =
fetchStrategy === FetchStrategy.PPRRuntime
? // A runtime prefetch may have holes.
!!response.headers.get(NEXT_DID_POSTPONE_HEADER)
: // Full and LoadingBoundary prefetches cannot have holes.
// (even if we did set the prefetch header, we only use this codepath for non-PPR-enabled routes)
false
// Aside from writing the data into the cache, this function also returns
// the entries that were fulfilled, so we can streamingly update their sizes
......@@ -1455,7 +1488,10 @@ export async function fetchSegmentPrefetchesUsingDynamicRequest(
function writeDynamicTreeResponseIntoCache(
now: number,
task: PrefetchTask,
fetchStrategy: FetchStrategy.LoadingBoundary | FetchStrategy.Full,
fetchStrategy:
| FetchStrategy.LoadingBoundary
| FetchStrategy.PPRRuntime
| FetchStrategy.Full,
response: RSCResponse,
serverData: NavigationFlightResponse,
entry: PendingRouteCacheEntry,
......@@ -1553,7 +1589,10 @@ function rejectSegmentEntriesIfStillPending(
function writeDynamicRenderResponseIntoCache(
now: number,
task: PrefetchTask,
fetchStrategy: FetchStrategy.LoadingBoundary | FetchStrategy.Full,
fetchStrategy:
| FetchStrategy.LoadingBoundary
| FetchStrategy.PPRRuntime
| FetchStrategy.Full,
response: RSCResponse,
serverData: NavigationFlightResponse,
isResponsePartial: boolean,
......@@ -1661,7 +1700,10 @@ function writeDynamicRenderResponseIntoCache(
function writeSeedDataIntoCache(
now: number,
task: PrefetchTask,
fetchStrategy: FetchStrategy.LoadingBoundary | FetchStrategy.Full,
fetchStrategy:
| FetchStrategy.LoadingBoundary
| FetchStrategy.PPRRuntime
| FetchStrategy.Full,
route: FulfilledRouteCacheEntry,
staleAt: number,
seedData: CacheNodeSeedData,
......@@ -1855,3 +1897,31 @@ function createPromiseWithResolvers<T>(): PromiseWithResolvers<T> {
})
return { resolve: resolve!, reject: reject!, promise }
}
/**
* Checks whether the new fetch strategy is likely to provide more content than the old one.
*
* Generally, when an app uses dynamic data, a "more specific" fetch strategy is expected to provide more content:
* - `LoadingBoundary` only provides static layouts
* - `PPR` can provide shells for each segment (even for segments that use dynamic data)
* - `PPRRuntime` can additionally include content that uses searchParams, params, or cookies
* - `Full` includes all the content, even if it uses dynamic data
*
* However, it's possible that a more specific fetch strategy *won't* give us more content if:
* - a segment is fully static
* (then, `PPR`/`PPRRuntime`/`Full` will all yield equivalent results)
* - providing searchParams/params/cookies doesn't reveal any more content, e.g. because of an `await connection()`
* (then, `PPR` and `PPRRuntime` will yield equivalent results, only `Full` will give us more)
* Because of this, when comparing two segments, we should also check if the existing segment is partial.
* If it's not partial, then there's no need to prefetch it again, even using a "more specific" strategy.
* There's currently no way to know if `PPRRuntime` will yield more data that `PPR`, so we have to assume it will.
*
* Also note that, in practice, we don't expect to be comparing `LoadingBoundary` to `PPR`/`PPRRuntime`,
* because a non-PPR-enabled route wouldn't ever use the latter strategies. It might however use `Full`.
*/
export function canNewFetchStrategyProvideMoreContent(
currentStrategy: FetchStrategy,
newStrategy: FetchStrategy
): boolean {
return currentStrategy < newStrategy
}
......@@ -142,9 +142,13 @@ export const enum PrefetchPriority {
}
export const enum FetchStrategy {
PPR,
Full,
LoadingBoundary,
// 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)
LoadingBoundary = 0,
PPR = 1,
PPRRuntime = 2,
Full = 3,
}
/**
......@@ -153,4 +157,7 @@ export const enum FetchStrategy {
* 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
export type PrefetchTaskFetchStrategy =
| FetchStrategy.PPR
| FetchStrategy.PPRRuntime
| FetchStrategy.Full
......@@ -82,7 +82,7 @@ type InternalLinkProps = {
* - `false`: Prefetching will not happen when entering the viewport, but will still happen on hover.
* @defaultValue `true` (pages router) or `null` (app router)
*/
prefetch?: boolean | 'auto' | null
prefetch?: boolean | 'auto' | null | 'unstable_forceStale'
/**
* The active locale is automatically prepended. `locale` allows for providing a different locale.
* When `false` `href` has to include the locale as the default behavior is disabled.
......
......@@ -86,7 +86,7 @@ describe('next-link', () => {
if (isNextDev) {
await expect(browser).toDisplayRedbox(`
{
"description": "Failed prop type: The prop \`prefetch\` expects a \`boolean | "auto"\` in \`<Link>\`, but got \`string\` instead.
"description": "Failed prop type: The prop \`prefetch\` expects a \`boolean | "auto" | "unstable_forceStale"\` in \`<Link>\`, but got \`string\` instead.
Open your browser's console to view the Component stack trace.",
"environmentLabel": null,
"label": "Runtime Error",
......
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