Unverified Commit 4df1a08f authored by Andrew Clark's avatar Andrew Clark Committed by GitHub

Add onInvalidate option to router.prefetch (#77880)

This commit adds an `onInvalidate` callback to `router.prefetch()` so
custom `<Link>` implementations can re-prefetch data when it becomes
stale.

The callback is invoked when the data associated with the prefetch may
have been invalidated (e.g. by `revalidatePath` or `revalidateTag`).

This is not a live subscription and should not be treated as one. It's a
one-time callback per prefetch request that acts as a signal: "If you
care about the freshness of this data, now would be a good time to
re-prefetch."

The supported use case is for advanced clients who opt out of rendering
the built-in `<Link>` component (e.g. to customize visibility tracking
or polling behavior) but still want to retain proper cache integration.
When the callback is fired, the component can trigger a new call to
`router.prefetch()` with the same parameters, including a new
`onInvalidate` callback to continue the cycle.

(For reference, `<Link>` handles this automatically. This API exists to
give custom implementations access to the same underlying behavior.)

Note that the callback *may* be invoked even if the prefetched data is
still cached. This is intentional—prefetching in the app router is a
pull-based mechanism, not a push-based one. Rather than subscribing to
the lifecycle of specific cache entries, the app occasionally polls the
prefetch layer to check for missing or stale data.

Calling `router.prefetch()` does not necessarily result in a network
request. If the data is already cached, the call is a no-op. This makes
polling a practical way to check cache freshness over time without
incurring unnecessary requests.
parent 21d2a32d
...@@ -321,7 +321,8 @@ export const publicAppRouterInstance: AppRouterInstance = { ...@@ -321,7 +321,8 @@ export const publicAppRouterInstance: AppRouterInstance = {
href, href,
actionQueue.state.nextUrl, actionQueue.state.nextUrl,
actionQueue.state.tree, actionQueue.state.tree,
options?.kind === PrefetchKind.FULL options?.kind === PrefetchKind.FULL,
options?.onInvalidate ?? null
) )
} }
: (href: string, options?: PrefetchOptions) => { : (href: string, options?: PrefetchOptions) => {
......
...@@ -3,7 +3,7 @@ import type { AppRouterInstance } from '../../shared/lib/app-router-context.shar ...@@ -3,7 +3,7 @@ import type { AppRouterInstance } from '../../shared/lib/app-router-context.shar
import { getCurrentAppRouterState } from './app-router-instance' import { getCurrentAppRouterState } from './app-router-instance'
import { createPrefetchURL } from './app-router' import { createPrefetchURL } from './app-router'
import { PrefetchKind } from './router-reducer/router-reducer-types' import { PrefetchKind } from './router-reducer/router-reducer-types'
import { getCurrentCacheVersion } from './segment-cache' import { isPrefetchTaskDirty } from './segment-cache'
import { createCacheKey } from './segment-cache' import { createCacheKey } from './segment-cache'
import { import {
type PrefetchTask, type PrefetchTask,
...@@ -28,13 +28,9 @@ type LinkOrFormInstanceShared = { ...@@ -28,13 +28,9 @@ type LinkOrFormInstanceShared = {
wasHoveredOrTouched: boolean wasHoveredOrTouched: boolean
// The most recently initiated prefetch task. It may or may not have // The most recently initiated prefetch task. It may or may not have
// already completed. The same prefetch task object can be reused across // already completed. The same prefetch task object can be reused across
// multiple prefetches of the same link. // multiple prefetches of the same link.
prefetchTask: PrefetchTask | null prefetchTask: PrefetchTask | null
// The cache version at the time the task was initiated. This is used to
// determine if the cache was invalidated since the task was initiated.
cacheVersion: number
} }
export type FormInstance = LinkOrFormInstanceShared & { export type FormInstance = LinkOrFormInstanceShared & {
...@@ -158,7 +154,6 @@ export function mountLinkInstance( ...@@ -158,7 +154,6 @@ export function mountLinkInstance(
isVisible: false, isVisible: false,
wasHoveredOrTouched: false, wasHoveredOrTouched: false,
prefetchTask: null, prefetchTask: null,
cacheVersion: -1,
prefetchHref: prefetchURL.href, prefetchHref: prefetchURL.href,
setOptimisticLinkStatus, setOptimisticLinkStatus,
} }
...@@ -176,7 +171,6 @@ export function mountLinkInstance( ...@@ -176,7 +171,6 @@ export function mountLinkInstance(
isVisible: false, isVisible: false,
wasHoveredOrTouched: false, wasHoveredOrTouched: false,
prefetchTask: null, prefetchTask: null,
cacheVersion: -1,
prefetchHref: null, prefetchHref: null,
setOptimisticLinkStatus, setOptimisticLinkStatus,
} }
...@@ -203,7 +197,6 @@ export function mountFormInstance( ...@@ -203,7 +197,6 @@ export function mountFormInstance(
isVisible: false, isVisible: false,
wasHoveredOrTouched: false, wasHoveredOrTouched: false,
prefetchTask: null, prefetchTask: null,
cacheVersion: -1,
prefetchHref: prefetchURL.href, prefetchHref: prefetchURL.href,
setOptimisticLinkStatus: null, setOptimisticLinkStatus: null,
} }
...@@ -322,7 +315,8 @@ function rescheduleLinkPrefetch(instance: PrefetchableInstance) { ...@@ -322,7 +315,8 @@ function rescheduleLinkPrefetch(instance: PrefetchableInstance) {
cacheKey, cacheKey,
treeAtTimeOfPrefetch, treeAtTimeOfPrefetch,
instance.kind === PrefetchKind.FULL, instance.kind === PrefetchKind.FULL,
priority priority,
null
) )
} else { } else {
// We already have an old task object that we can reschedule. This is // We already have an old task object that we can reschedule. This is
...@@ -334,10 +328,6 @@ function rescheduleLinkPrefetch(instance: PrefetchableInstance) { ...@@ -334,10 +328,6 @@ function rescheduleLinkPrefetch(instance: PrefetchableInstance) {
priority priority
) )
} }
// Keep track of the cache version at the time the prefetch was requested.
// This is used to check if the prefetch is stale.
instance.cacheVersion = getCurrentCacheVersion()
} }
} }
...@@ -352,15 +342,9 @@ export function pingVisibleLinks( ...@@ -352,15 +342,9 @@ export function pingVisibleLinks(
// This is called when the Next-Url or the base tree changes, since those // This is called when the Next-Url or the base tree changes, since those
// may affect the result of a prefetch task. It's also called after a // may affect the result of a prefetch task. It's also called after a
// cache invalidation. // cache invalidation.
const currentCacheVersion = getCurrentCacheVersion()
for (const instance of prefetchableAndVisible) { for (const instance of prefetchableAndVisible) {
const task = instance.prefetchTask const task = instance.prefetchTask
if ( if (task !== null && !isPrefetchTaskDirty(task, nextUrl, tree)) {
task !== null &&
instance.cacheVersion === currentCacheVersion &&
task.key.nextUrl === nextUrl &&
task.treeAtTimeOfPrefetch === tree
) {
// The cache has not been invalidated, and none of the inputs have // The cache has not been invalidated, and none of the inputs have
// changed. Bail out. // changed. Bail out.
continue continue
...@@ -378,9 +362,9 @@ export function pingVisibleLinks( ...@@ -378,9 +362,9 @@ export function pingVisibleLinks(
cacheKey, cacheKey,
tree, tree,
instance.kind === PrefetchKind.FULL, instance.kind === PrefetchKind.FULL,
priority priority,
null
) )
instance.cacheVersion = getCurrentCacheVersion()
} }
} }
......
...@@ -28,6 +28,7 @@ import { ...@@ -28,6 +28,7 @@ import {
} from '../router-reducer/fetch-server-response' } from '../router-reducer/fetch-server-response'
import { import {
pingPrefetchTask, pingPrefetchTask,
isPrefetchTaskDirty,
type PrefetchTask, type PrefetchTask,
type PrefetchSubtaskResult, type PrefetchSubtaskResult,
} from './scheduler' } from './scheduler'
...@@ -245,6 +246,14 @@ let segmentCacheLru = createLRU<SegmentCacheEntry>( ...@@ -245,6 +246,14 @@ let segmentCacheLru = createLRU<SegmentCacheEntry>(
onSegmentLRUEviction onSegmentLRUEviction
) )
// All invalidation listeners for the whole cache are tracked in single set.
// Since we don't yet support tag or path-based invalidation, there's no point
// tracking them any more granularly than this. Once we add granular
// invalidation, that may change, though generally the model is to just notify
// the listeners and allow the caller to poll the prefetch cache with a new
// prefetch task if desired.
let invalidationListeners: Set<PrefetchTask> | null = null
// Incrementing counter used to track cache invalidations. // Incrementing counter used to track cache invalidations.
let currentCacheVersion = 0 let currentCacheVersion = 0
...@@ -276,6 +285,65 @@ export function revalidateEntireCache( ...@@ -276,6 +285,65 @@ export function revalidateEntireCache(
// Prefetch all the currently visible links again, to re-fill the cache. // Prefetch all the currently visible links again, to re-fill the cache.
pingVisibleLinks(nextUrl, tree) pingVisibleLinks(nextUrl, tree)
// Similarly, notify all invalidation listeners (i.e. those passed to
// `router.prefetch(onInvalidate)`), so they can trigger a new prefetch
// if needed.
pingInvalidationListeners(nextUrl, tree)
}
function attachInvalidationListener(task: PrefetchTask): void {
// This function is called whenever a prefetch task reads a cache entry. If
// the task has an onInvalidate function associated with it — i.e. the one
// optionally passed to router.prefetch(onInvalidate) — then we attach that
// listener to the every cache entry that the task reads. Then, if an entry
// is invalidated, we call the function.
if (task.onInvalidate !== null) {
if (invalidationListeners === null) {
invalidationListeners = new Set([task])
} else {
invalidationListeners.add(task)
}
}
}
function notifyInvalidationListener(task: PrefetchTask): void {
const onInvalidate = task.onInvalidate
if (onInvalidate !== null) {
// Clear the callback from the task object to guarantee it's not called more
// than once.
task.onInvalidate = null
// This is a user-space function, so we must wrap in try/catch.
try {
onInvalidate()
} catch (error) {
if (typeof reportError === 'function') {
reportError(error)
} else {
console.error(error)
}
}
}
}
export function pingInvalidationListeners(
nextUrl: string | null,
tree: FlightRouterState
): void {
// The rough equivalent of pingVisibleLinks, but for onInvalidate callbacks.
// This is called when the Next-Url or the base tree changes, since those
// may affect the result of a prefetch task. It's also called after a
// cache invalidation.
if (invalidationListeners !== null) {
const tasks = invalidationListeners
invalidationListeners = null
for (const task of tasks) {
if (isPrefetchTaskDirty(task, nextUrl, tree)) {
notifyInvalidationListener(task)
}
}
}
} }
export function readExactRouteCacheEntry( export function readExactRouteCacheEntry(
...@@ -445,6 +513,8 @@ export function readOrCreateRouteCacheEntry( ...@@ -445,6 +513,8 @@ export function readOrCreateRouteCacheEntry(
now: number, now: number,
task: PrefetchTask task: PrefetchTask
): RouteCacheEntry { ): RouteCacheEntry {
attachInvalidationListener(task)
const key = task.key const key = task.key
const existingEntry = readRouteCacheEntry(now, key) const existingEntry = readRouteCacheEntry(now, key)
if (existingEntry !== null) { if (existingEntry !== null) {
......
...@@ -9,17 +9,27 @@ import { PrefetchPriority } from '../segment-cache' ...@@ -9,17 +9,27 @@ import { PrefetchPriority } from '../segment-cache'
* @param href - The URL to prefetch. Typically this will come from a <Link>, * @param href - The URL to prefetch. Typically this will come from a <Link>,
* or router.prefetch. It must be validated before we attempt to prefetch it. * or router.prefetch. It must be validated before we attempt to prefetch it.
* @param nextUrl - A special header used by the server for interception routes. * @param nextUrl - A special header used by the server for interception routes.
* Roughly corresponds to the current URL. * Roughly corresponds to the current URL.
* @param treeAtTimeOfPrefetch - The FlightRouterState at the time the prefetch * @param treeAtTimeOfPrefetch - The FlightRouterState at the time the prefetch
* was requested. This is only used when PPR is disabled. * was requested. This is only used when PPR is disabled.
* @param includeDynamicData - Whether to prefetch dynamic data, in addition to * @param includeDynamicData - Whether to prefetch dynamic data, in addition to
* static data. This is used by <Link prefetch={true}>. * static data. This is used by <Link prefetch={true}>.
* @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
* subscription — it's called at most once per `prefetch` call. The only
* supported use case is to trigger a new prefetch inside the listener, if
* desired. It also may be called even in cases where the associated data is
* still cached. Prefetching is a poll-based (pull) operation, not an event-
* based (push) one. Rather than subscribe to specific cache entries, you
* occasionally poll the prefetch cache to check if anything is missing.
*/ */
export function prefetch( export function prefetch(
href: string, href: string,
nextUrl: string | null, nextUrl: string | null,
treeAtTimeOfPrefetch: FlightRouterState, treeAtTimeOfPrefetch: FlightRouterState,
includeDynamicData: boolean includeDynamicData: boolean,
onInvalidate: null | (() => void)
) { ) {
const url = createPrefetchURL(href) const url = createPrefetchURL(href)
if (url === null) { if (url === null) {
...@@ -31,6 +41,7 @@ export function prefetch( ...@@ -31,6 +41,7 @@ export function prefetch(
cacheKey, cacheKey,
treeAtTimeOfPrefetch, treeAtTimeOfPrefetch,
includeDynamicData, includeDynamicData,
PrefetchPriority.Default PrefetchPriority.Default,
onInvalidate
) )
} }
...@@ -26,7 +26,7 @@ import { ...@@ -26,7 +26,7 @@ import {
getSegmentKeypathForTask, getSegmentKeypathForTask,
} from './cache' } from './cache'
import type { RouteCacheKey } from './cache-key' import type { RouteCacheKey } from './cache-key'
import { PrefetchPriority } from '../segment-cache' import { getCurrentCacheVersion, PrefetchPriority } from '../segment-cache'
const scheduleMicrotask = const scheduleMicrotask =
typeof queueMicrotask === 'function' typeof queueMicrotask === 'function'
...@@ -50,6 +50,12 @@ export type PrefetchTask = { ...@@ -50,6 +50,12 @@ export type PrefetchTask = {
*/ */
treeAtTimeOfPrefetch: FlightRouterState treeAtTimeOfPrefetch: FlightRouterState
/**
* The cache version at the time the task was initiated. This is used to
* determine if the cache was invalidated since the task was initiated.
*/
cacheVersion: number
/** /**
* Whether to prefetch dynamic data, in addition to static data. This is * Whether to prefetch dynamic data, in addition to static data. This is
* used by <Link prefetch={true}>. * used by <Link prefetch={true}>.
...@@ -105,6 +111,11 @@ export type PrefetchTask = { ...@@ -105,6 +111,11 @@ export type PrefetchTask = {
*/ */
isCanceled: boolean isCanceled: boolean
/**
* The callback passed to `router.prefetch`, if given.
*/
onInvalidate: null | (() => void)
/** /**
* The index of the task in the heap's backing array. Used to efficiently * The index of the task in the heap's backing array. Used to efficiently
* change the priority of a task by re-sifting it, which requires knowing * change the priority of a task by re-sifting it, which requires knowing
...@@ -182,18 +193,21 @@ export function schedulePrefetchTask( ...@@ -182,18 +193,21 @@ export function schedulePrefetchTask(
key: RouteCacheKey, key: RouteCacheKey,
treeAtTimeOfPrefetch: FlightRouterState, treeAtTimeOfPrefetch: FlightRouterState,
includeDynamicData: boolean, includeDynamicData: boolean,
priority: PrefetchPriority priority: PrefetchPriority,
onInvalidate: null | (() => void)
): PrefetchTask { ): PrefetchTask {
// Spawn a new prefetch task // Spawn a new prefetch task
const task: PrefetchTask = { const task: PrefetchTask = {
key, key,
treeAtTimeOfPrefetch, treeAtTimeOfPrefetch,
cacheVersion: getCurrentCacheVersion(),
priority, priority,
phase: PrefetchPhase.RouteTree, phase: PrefetchPhase.RouteTree,
hasBackgroundWork: false, hasBackgroundWork: false,
includeDynamicData, includeDynamicData,
sortId: sortIdCounter++, sortId: sortIdCounter++,
isCanceled: false, isCanceled: false,
onInvalidate,
_heapIndex: -1, _heapIndex: -1,
} }
heapPush(taskHeap, task) heapPush(taskHeap, task)
...@@ -254,6 +268,24 @@ export function reschedulePrefetchTask( ...@@ -254,6 +268,24 @@ export function reschedulePrefetchTask(
ensureWorkIsScheduled() ensureWorkIsScheduled()
} }
export function isPrefetchTaskDirty(
task: PrefetchTask,
nextUrl: string | null,
tree: FlightRouterState
): boolean {
// This is used to quickly bail out of a prefetch task if the result is
// guaranteed to not have changed since the task was initiated. This is
// strictly an optimization — theoretically, if it always returned true, no
// behavior should change because a full prefetch task will effectively
// perform the same checks.
const currentCacheVersion = getCurrentCacheVersion()
return (
task.cacheVersion !== currentCacheVersion ||
task.treeAtTimeOfPrefetch !== tree ||
task.key.nextUrl !== nextUrl
)
}
function ensureWorkIsScheduled() { function ensureWorkIsScheduled() {
if (didScheduleMicrotask || !hasNetworkBandwidth()) { if (didScheduleMicrotask || !hasNetworkBandwidth()) {
// Either we already scheduled a task to process the queue, or there are // Either we already scheduled a task to process the queue, or there are
...@@ -344,6 +376,8 @@ function processQueueInMicrotask() { ...@@ -344,6 +376,8 @@ function processQueueInMicrotask() {
// Process the task queue until we run out of network bandwidth. // Process the task queue until we run out of network bandwidth.
let task = heapPeek(taskHeap) let task = heapPeek(taskHeap)
while (task !== null && hasNetworkBandwidth()) { while (task !== null && hasNetworkBandwidth()) {
task.cacheVersion = getCurrentCacheVersion()
const route = readOrCreateRouteCacheEntry(now, task) const route = readOrCreateRouteCacheEntry(now, task)
const exitStatus = pingRootRouteTree(now, task, route) const exitStatus = pingRootRouteTree(now, task, route)
......
...@@ -85,6 +85,15 @@ export const reschedulePrefetchTask: typeof import('./segment-cache-impl/schedul ...@@ -85,6 +85,15 @@ export const reschedulePrefetchTask: typeof import('./segment-cache-impl/schedul
} }
: notEnabled : notEnabled
export const isPrefetchTaskDirty: typeof import('./segment-cache-impl/scheduler').isPrefetchTaskDirty =
process.env.__NEXT_CLIENT_SEGMENT_CACHE
? function (...args) {
return require('./segment-cache-impl/scheduler').isPrefetchTaskDirty(
...args
)
}
: notEnabled
export const createCacheKey: typeof import('./segment-cache-impl/cache-key').createCacheKey = export const createCacheKey: typeof import('./segment-cache-impl/cache-key').createCacheKey =
process.env.__NEXT_CLIENT_SEGMENT_CACHE process.env.__NEXT_CLIENT_SEGMENT_CACHE
? function (...args) { ? function (...args) {
......
...@@ -122,6 +122,7 @@ export interface NavigateOptions { ...@@ -122,6 +122,7 @@ export interface NavigateOptions {
export interface PrefetchOptions { export interface PrefetchOptions {
kind: PrefetchKind kind: PrefetchKind
onInvalidate?: () => void
} }
export interface AppRouterInstance { export interface AppRouterInstance {
......
import { revalidatePath, revalidateTag } from 'next/cache' import { revalidatePath, revalidateTag } from 'next/cache'
import { LinkAccordion, FormAccordion } from '../components/link-accordion' import {
LinkAccordion,
FormAccordion,
ManualPrefetchLinkAccordion,
} from '../components/link-accordion'
import Link from 'next/link' import Link from 'next/link'
export default async function Page() { export default async function Page() {
...@@ -36,6 +40,12 @@ export default async function Page() { ...@@ -36,6 +40,12 @@ export default async function Page() {
Form pointing to target page with prefetching enabled Form pointing to target page with prefetching enabled
</FormAccordion> </FormAccordion>
</li> </li>
<li>
<ManualPrefetchLinkAccordion href="/greeting">
Manual link (router.prefetch) to target page with prefetching
enabled
</ManualPrefetchLinkAccordion>
</li>
<li> <li>
<Link prefetch={false} href="/greeting"> <Link prefetch={false} href="/greeting">
Link to target with prefetching disabled Link to target with prefetching disabled
......
...@@ -2,7 +2,8 @@ ...@@ -2,7 +2,8 @@
import Link from 'next/link' import Link from 'next/link'
import Form from 'next/form' import Form from 'next/form'
import { useState } from 'react' import { useEffect, useState } from 'react'
import { useRouter } from 'next/navigation'
export function LinkAccordion({ export function LinkAccordion({
href, href,
...@@ -61,3 +62,74 @@ export function FormAccordion({ ...@@ -61,3 +62,74 @@ export function FormAccordion({
</> </>
) )
} }
export function ManualPrefetchLinkAccordion({
href,
children,
prefetch,
}: {
href: string
children: React.ReactNode
prefetch?: boolean
}) {
const [isVisible, setIsVisible] = useState(false)
return (
<>
<input
type="checkbox"
checked={isVisible}
onChange={() => setIsVisible(!isVisible)}
data-manual-prefetch-link-accordion={href}
/>
{isVisible ? (
<ManualPrefetchLink href={href} prefetch={prefetch}>
{children}
</ManualPrefetchLink>
) : (
<>{children} (form is hidden)</>
)}
</>
)
}
function ManualPrefetchLink({
href,
children,
prefetch,
}: {
href: string
children: React.ReactNode
prefetch?: boolean
}) {
const router = useRouter()
useEffect(() => {
if (prefetch !== false) {
// For as long as the link is mounted, poll the prefetch cache whenever
// it's invalidated to ensure the data is fresh.
let didUnmount = false
const pollPrefetch = () => {
if (!didUnmount) {
// @ts-expect-error: onInvalidate is not yet part of public types
router.prefetch(href, {
onInvalidate: pollPrefetch,
})
}
}
pollPrefetch()
return () => {
didUnmount = true
}
}
}, [href, prefetch, router])
return (
<a
onClick={(event) => {
event.preventDefault()
router.push(href)
}}
href={href}
>
{children}
</a>
)
}
...@@ -149,6 +149,57 @@ describe('segment cache (revalidation)', () => { ...@@ -149,6 +149,57 @@ describe('segment cache (revalidation)', () => {
}, 'no-requests') }, 'no-requests')
}) })
it('call router.prefetch(..., {onInvalidate}) after cache is revalidated', async () => {
// This is the similar to the previous tests, but uses a custom Link
// implementation that calls router.prefetch manually. It demonstrates it's
// possible to simulate the revalidating behavior of Link using the manual
// prefetch API.
let act: ReturnType<typeof createRouterAct>
const browser = await next.browser('/', {
beforePageLoad(page) {
act = createRouterAct(page)
},
})
const linkVisibilityToggle = await browser.elementByCss(
'input[data-manual-prefetch-link-accordion="/greeting"]'
)
// Reveal the link that points to the target page to trigger a prefetch
await act(
async () => {
await linkVisibilityToggle.click()
},
{
includes: 'random-greeting',
}
)
// Perform an action that calls revalidatePath. This should cause the
// corresponding entry to be evicted from the client cache, and a new
// prefetch to be requested.
await act(
async () => {
const revalidateByPath = await browser.elementById('revalidate-by-path')
await revalidateByPath.click()
},
{
includes: 'random-greeting [1]',
}
)
TestLog.assert(['REQUEST: random-greeting'])
// Navigate to the target page.
await act(async () => {
const link = await browser.elementByCss('a[href="/greeting"]')
await link.click()
// Navigation should finish immedately because the page is
// fully prefetched.
const greeting = await browser.elementById('greeting')
expect(await greeting.innerHTML()).toBe('random-greeting [1]')
}, 'no-requests')
})
it('evict client cache when Server Action calls revalidateTag', async () => { it('evict client cache when Server Action calls revalidateTag', async () => {
let act: ReturnType<typeof createRouterAct> let act: ReturnType<typeof createRouterAct>
const browser = await next.browser('/', { const browser = await next.browser('/', {
......
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