Unverified Commit 4b56af9f authored by Hendrik Liebau's avatar Hendrik Liebau Committed by GitHub

Cached Navigations: Cache runtime stage data from navigation requests (#90666)

When navigating to a page with `unstable_instant: { prefetch: 'runtime'
}` and no prior prefetch (e.g. `prefetch={false}` or clicking before
prefetch completes), the server now embeds a runtime prefetch stream in
the dynamic RSC navigation payload. On the client, this stream is
decoded and written into the segment cache so that subsequent
navigations to the same page can serve runtime-prefetchable content
(cookies, headers, searchParams) instantly, without needing a separate
prefetch request.

On the server, `generateStagedDynamicFlightRenderResult` detects routes
with runtime prefetching enabled and attaches a `CacheSignal` and
`PrerenderResumeDataCache` to the `RequestStore`. The dynamic render
fills these caches as a side effect. Once `cacheSignal.cacheReady()`
resolves, a final runtime prerender (the same 5-stage pipeline used for
regular runtime prefetches) runs and its output is piped into a
`TransformStream` whose readable side is included in the RSC payload as
the `p` field on the `NavigationFlightResponse`. This avoids a separate
prospective prerender because the dynamic render has already warmed the
caches.

On the client, `processRuntimePrefetchStream` strips the isPartial byte,
decodes the inner Flight stream, and the result is written into the
segment cache via `writeDynamicRenderResponseIntoCache` with
`FetchStrategy.PPRRuntime`. Both the `navigateToUnknownRoute` and
`fetchMissingDynamicData` code paths handle the new stream.

This is gated on the explicit `unstable_instant` opt-in because it adds
extra server processing (a full runtime prerender per navigation
request) and increases payload size. It also requires that the runtime
prefetch output has been validated first.

Known limitation: the runtime prefetch cache write currently evicts the
static cache entry (which may have a longer stale time) because
`upsertSegmentEntry` treats the fallback match as a replacement target.
This means that after the runtime cache expires, the static cache is no
longer available as a fallback. A follow-up may address this with a
layered cache approach where entries with different fetch strategies and
stale times coexist independently.

Extracting runtime data from initial HTML loads (the PPR resume path) is
also deferred to a follow-up.
parent a41e4d57
...@@ -83,6 +83,7 @@ type SpaFetchServerResponseResult = { ...@@ -83,6 +83,7 @@ type SpaFetchServerResponseResult = {
postponed: boolean postponed: boolean
staleTime: number staleTime: number
staticStageData: StaticStageData | null staticStageData: StaticStageData | null
runtimePrefetchStream: ReadableStream<Uint8Array> | null
responseHeaders: Headers responseHeaders: Headers
debugInfo: Array<any> | null debugInfo: Array<any> | null
} }
...@@ -286,6 +287,7 @@ export async function fetchServerResponse( ...@@ -286,6 +287,7 @@ export async function fetchServerResponse(
postponed, postponed,
staleTime, staleTime,
staticStageData, staticStageData,
runtimePrefetchStream: flightResponse.p ?? null,
responseHeaders: res.headers, responseHeaders: res.headers,
debugInfo: flightResponsePromise._debugInfo ?? null, debugInfo: flightResponsePromise._debugInfo ?? null,
} }
......
...@@ -37,8 +37,11 @@ import { ...@@ -37,8 +37,11 @@ import {
invalidateRouteCacheEntries, invalidateRouteCacheEntries,
getStaleAt, getStaleAt,
writeStaticStageResponseIntoCache, writeStaticStageResponseIntoCache,
processRuntimePrefetchStream,
writeDynamicRenderResponseIntoCache,
EntryStatus, EntryStatus,
} from '../segment-cache/cache' } from '../segment-cache/cache'
import { FetchStrategy } from '../segment-cache/types'
import { discoverKnownRoute } from '../segment-cache/optimistic-routes' import { discoverKnownRoute } from '../segment-cache/optimistic-routes'
import { NEXT_NAV_DEPLOYMENT_ID_HEADER } from '../../../lib/constants' import { NEXT_NAV_DEPLOYMENT_ID_HEADER } from '../../../lib/constants'
import type { NormalizedSearch } from '../segment-cache/cache-key' import type { NormalizedSearch } from '../segment-cache/cache-key'
...@@ -1582,12 +1585,12 @@ async function fetchMissingDynamicData( ...@@ -1582,12 +1585,12 @@ async function fetchMissingDynamicData(
await waitForNavigationLock() await waitForNavigationLock()
} }
const now = Date.now()
if (routeCacheEntry !== null && result.staticStageData !== null) { if (routeCacheEntry !== null && result.staticStageData !== null) {
const { response: staticStageResponse, isResponsePartial } = const { response: staticStageResponse, isResponsePartial } =
result.staticStageData result.staticStageData
const now = Date.now()
getStaleAt(now, staticStageResponse.s) getStaleAt(now, staticStageResponse.s)
.then((staleAt) => { .then((staleAt) => {
const buildId = const buildId =
...@@ -1611,6 +1614,34 @@ async function fetchMissingDynamicData( ...@@ -1611,6 +1614,34 @@ async function fetchMissingDynamicData(
}) })
} }
if (routeCacheEntry !== null && result.runtimePrefetchStream !== null) {
processRuntimePrefetchStream(
now,
result.runtimePrefetchStream,
dynamicRequestTree,
result.renderedSearch
)
.then((processed) => {
if (processed !== null) {
writeDynamicRenderResponseIntoCache(
now,
FetchStrategy.PPRRuntime,
processed.flightDatas,
processed.buildId,
processed.isResponsePartial,
processed.headVaryParams,
processed.staleAt,
processed.navigationSeed,
null
)
}
})
.catch(() => {
// The runtime prefetch cache write failed. Not fatal — the
// navigation completed normally, we just won't cache runtime data.
})
}
const didReceiveUnknownParallelRoute = writeDynamicDataIntoNavigationTask( const didReceiveUnknownParallelRoute = writeDynamicDataIntoNavigationTask(
task, task,
seed.routeTree, seed.routeTree,
......
...@@ -2938,6 +2938,62 @@ export function writeStaticStageResponseIntoCache( ...@@ -2938,6 +2938,62 @@ export function writeStaticStageResponseIntoCache(
) )
} }
/**
* Decodes an embedded runtime prefetch Flight stream, normalizes the flight
* data, and derives a `NavigationSeed` from the base tree.
*
* Returns `null` if the response triggers an MPA navigation.
*/
export async function processRuntimePrefetchStream(
now: number,
runtimePrefetchStream: ReadableStream<Uint8Array>,
baseTree: FlightRouterState,
renderedSearch: string
): Promise<{
flightDatas: NormalizedFlightData[]
navigationSeed: NavigationSeed
buildId: string | undefined
isResponsePartial: boolean
headVaryParams: VaryParams | null
staleAt: number
} | null> {
const { stream, isPartial } = await stripIsPartialByte(runtimePrefetchStream)
const serverData =
await createFromNextReadableStream<NavigationFlightResponse>(
stream,
undefined,
{ allowPartialStream: true }
)
const headVaryParamsThenable = serverData.h
const headVaryParams =
headVaryParamsThenable !== null
? readVaryParams(headVaryParamsThenable)
: null
const staleAt = await getStaleAt(now, serverData.s)
const flightDatas = normalizeFlightData(serverData.f)
if (typeof flightDatas === 'string') {
return null
}
const navigationSeed = convertServerPatchToFullTree(
baseTree,
flightDatas,
renderedSearch
)
return {
flightDatas,
navigationSeed,
buildId: serverData.b,
isResponsePartial: isPartial,
headVaryParams,
staleAt,
}
}
/** /**
* Strips the leading isPartial byte from an RSC response stream. * Strips the leading isPartial byte from an RSC response stream.
* *
......
...@@ -22,6 +22,8 @@ import { ...@@ -22,6 +22,8 @@ import {
convertRootFlightRouterStateToRouteTree, convertRootFlightRouterStateToRouteTree,
getStaleAt, getStaleAt,
writeStaticStageResponseIntoCache, writeStaticStageResponseIntoCache,
processRuntimePrefetchStream,
writeDynamicRenderResponseIntoCache,
type RouteTree, type RouteTree,
type FulfilledRouteCacheEntry, type FulfilledRouteCacheEntry,
} from './cache' } from './cache'
...@@ -373,6 +375,7 @@ async function navigateToUnknownRoute( ...@@ -373,6 +375,7 @@ async function navigateToUnknownRoute(
couldBeIntercepted, couldBeIntercepted,
supportsPerSegmentPrefetching, supportsPerSegmentPrefetching,
staticStageData, staticStageData,
runtimePrefetchStream,
responseHeaders, responseHeaders,
debugInfo, debugInfo,
} = result } = result
...@@ -434,6 +437,34 @@ async function navigateToUnknownRoute( ...@@ -434,6 +437,34 @@ async function navigateToUnknownRoute(
// completed normally, we just won't write into the cache. // completed normally, we just won't write into the cache.
}) })
} }
if (runtimePrefetchStream !== null) {
processRuntimePrefetchStream(
now,
runtimePrefetchStream,
currentFlightRouterState,
renderedSearch
)
.then((processed) => {
if (processed !== null) {
writeDynamicRenderResponseIntoCache(
now,
FetchStrategy.PPRRuntime,
processed.flightDatas,
processed.buildId,
processed.isResponsePartial,
processed.headVaryParams,
processed.staleAt,
processed.navigationSeed,
null
)
}
})
.catch(() => {
// The runtime prefetch cache write failed. Not fatal — the
// navigation completed normally, we just won't cache runtime data.
})
}
} }
return navigateToKnownRoute( return navigateToKnownRoute(
......
...@@ -509,6 +509,7 @@ async function generateDynamicRSCPayload( ...@@ -509,6 +509,7 @@ async function generateDynamicRSCPayload(
skipPageRendering?: boolean skipPageRendering?: boolean
staleTimeIterable?: AsyncIterable<number> staleTimeIterable?: AsyncIterable<number>
staticStageByteLengthPromise?: Promise<number> staticStageByteLengthPromise?: Promise<number>
runtimePrefetchStream?: ReadableStream<Uint8Array>
} }
): Promise<RSCPayload> { ): Promise<RSCPayload> {
// Flight data that is going to be passed to the browser. // Flight data that is going to be passed to the browser.
...@@ -648,6 +649,10 @@ async function generateDynamicRSCPayload( ...@@ -648,6 +649,10 @@ async function generateDynamicRSCPayload(
baseResponse.l = options.staticStageByteLengthPromise baseResponse.l = options.staticStageByteLengthPromise
} }
if (options?.runtimePrefetchStream !== undefined) {
baseResponse.p = options.runtimePrefetchStream
}
return baseResponse return baseResponse
} }
...@@ -755,7 +760,8 @@ async function generateStagedDynamicFlightRenderResult( ...@@ -755,7 +760,8 @@ async function generateStagedDynamicFlightRenderResult(
requestStore: RequestStore requestStore: RequestStore
): Promise<RenderResult> { ): Promise<RenderResult> {
const { componentMod, workStore, renderOpts } = ctx const { componentMod, workStore, renderOpts } = ctx
const { renderToReadableStream } = componentMod const { renderToReadableStream, routeModule } = componentMod
const { loaderTree } = routeModule.userland
const { onInstrumentationRequestError, experimental } = renderOpts const { onInstrumentationRequestError, experimental } = renderOpts
function onFlightDataRenderError(err: DigestedError, silenceLog: boolean) { function onFlightDataRenderError(err: DigestedError, silenceLog: boolean) {
...@@ -803,11 +809,53 @@ async function generateStagedDynamicFlightRenderResult( ...@@ -803,11 +809,53 @@ async function generateStagedDynamicFlightRenderResult(
resolveStaticStageByteLength = resolve resolveStaticStageByteLength = resolve
}) })
// Check if this route has opted into runtime prefetching via
// unstable_instant. If so, we piggyback on the dynamic render to fill caches
// and then spawn a final runtime prerender whose result stream is embedded in
// the RSC payload. This is gated on the explicit opt-in because it adds extra
// server processing, increases the response payload size, and the runtime
// prefetch output should have been validated first.
const hasRuntimePrefetch =
await anySegmentHasRuntimePrefetchEnabled(loaderTree)
let runtimePrefetchStream: ReadableStream<Uint8Array> | undefined
if (hasRuntimePrefetch) {
// Create a mutable cache that gets filled during the dynamic render.
const prerenderResumeDataCache = createPrerenderResumeDataCache()
requestStore.prerenderResumeDataCache = prerenderResumeDataCache
const cacheSignal = new CacheSignal()
trackPendingModules(cacheSignal)
requestStore.cacheSignal = cacheSignal
// Create a deferred stream for the runtime prefetch result. Its readable
// side goes into the RSC payload (Flight serializes it lazily). The
// writable side receives the runtime prerender result once the dynamic
// render has filled all caches.
const runtimePrefetchTransform = new TransformStream<Uint8Array>()
runtimePrefetchStream = runtimePrefetchTransform.readable
// Wait for the dynamic render to fill caches, then run the final runtime
// prerender (fire-and-forget — does not block the response).
void cacheSignal
.cacheReady()
.then(() =>
spawnRuntimePrefetchDuringNavigation(
runtimePrefetchTransform.writable,
ctx,
prerenderResumeDataCache,
requestStore,
onError
)
)
}
const rscPayload = await workUnitAsyncStorage.run( const rscPayload = await workUnitAsyncStorage.run(
requestStore, requestStore,
generateDynamicRSCPayload, generateDynamicRSCPayload,
ctx, ctx,
{ staleTimeIterable, staticStageByteLengthPromise } { staleTimeIterable, staticStageByteLengthPromise, runtimePrefetchStream }
) )
const { clientModules } = getClientReferenceManifest() const { clientModules } = getClientReferenceManifest()
...@@ -848,6 +896,49 @@ async function generateStagedDynamicFlightRenderResult( ...@@ -848,6 +896,49 @@ async function generateStagedDynamicFlightRenderResult(
}) })
} }
/**
* Runs a final runtime prerender using the provided (already filled) cache and
* pipes its output into the provided writable stream. The caller is responsible
* for waiting until caches are warm before calling this function.
*/
async function spawnRuntimePrefetchDuringNavigation(
writable: WritableStream<Uint8Array>,
ctx: AppRenderContext,
prerenderResumeDataCache: PrerenderResumeDataCache,
requestStore: RequestStore,
onError: (err: unknown) => string | undefined
): Promise<void> {
try {
const { componentMod, getDynamicParamFromSegment } = ctx
const { loaderTree } = componentMod.routeModule.userland
const rootParams = getRootParams(loaderTree, getDynamicParamFromSegment)
const staleTimeIterable = new StaleTimeIterable()
const { result } = await finalRuntimeServerPrerender(
ctx,
generateDynamicRSCPayload.bind(null, ctx, { staleTimeIterable }),
prerenderResumeDataCache,
null, // renderResumeDataCache
rootParams,
requestStore.headers,
requestStore.cookies,
requestStore.draftMode,
onError,
staleTimeIterable
)
await result.prelude.pipeTo(writable)
} catch {
// Runtime prerender failed. Close the stream gracefully — the navigation
// still works, we just won't get cached runtime data.
try {
await writable.close()
} catch {
// Writable may already be closed/errored.
}
}
}
type RenderToReadableStreamServerOptions = NonNullable< type RenderToReadableStreamServerOptions = NonNullable<
Parameters< Parameters<
(typeof import('react-server-dom-webpack/server.node'))['renderToReadableStream'] (typeof import('react-server-dom-webpack/server.node'))['renderToReadableStream']
......
...@@ -286,6 +286,8 @@ export type NavigationFlightResponse = { ...@@ -286,6 +286,8 @@ export type NavigationFlightResponse = {
l?: Promise<number> l?: Promise<number>
/** headVaryParams */ /** headVaryParams */
h: VaryParamsThenable | null h: VaryParamsThenable | null
/** runtimePrefetchStream — Embedded runtime prefetch Flight stream. */
p?: ReadableStream<Uint8Array>
} }
// Response from `createFromFetch` for server actions. Action's flight data can be null // Response from `createFromFetch` for server actions. Action's flight data can be null
......
...@@ -28,6 +28,11 @@ export default function Home() { ...@@ -28,6 +28,11 @@ export default function Home() {
Go to page with fallback params Go to page with fallback params
</Link> </Link>
</li> </li>
<li>
<Link href="/runtime-prefetchable" prefetch={false}>
Go to runtime-prefetchable page
</Link>
</li>
</ul> </ul>
</main> </main>
) )
......
import { cacheLife } from 'next/cache'
import { cookies, headers } from 'next/headers'
import { connection } from 'next/server'
import { setTimeout } from 'timers/promises'
import { Suspense } from 'react'
export const unstable_instant = {
prefetch: 'runtime',
samples: [
{
cookies: [{ name: 'testCookie', value: 'testValue' }],
headers: [['x-test-header', 'test']],
searchParams: {},
},
],
}
export default async function Page({
searchParams,
}: {
searchParams: Promise<{ q?: string }>
}) {
return (
<main>
<CachedContent />
<div id="search-params-boundary">
<Suspense fallback={<p>Loading search params...</p>}>
<SearchParamsContent searchParams={searchParams} />
</Suspense>
</div>
<div id="cookies-boundary">
<Suspense fallback={<p>Loading cookies...</p>}>
<CookiesContent />
</Suspense>
</div>
<div id="headers-boundary">
<Suspense fallback={<p>Loading headers...</p>}>
<HeadersContent />
</Suspense>
</div>
<div id="connection-boundary">
<Suspense fallback={<p>Loading connection...</p>}>
<ConnectionContent />
</Suspense>
</div>
</main>
)
}
async function CachedContent() {
'use cache'
cacheLife({ stale: 120 })
return <p id="cached-content">Cached content ({new Date().toISOString()})</p>
}
async function SearchParamsContent({
searchParams,
}: {
searchParams: Promise<{ q?: string }>
}) {
'use cache: private'
cacheLife({ stale: 30 })
const { q } = await searchParams
await setTimeout(300)
return (
<p>
Search params: {q ?? 'none'} ({new Date().toISOString()})
</p>
)
}
async function CookiesContent() {
'use cache: private'
cacheLife({ stale: 30 })
const cookieStore = await cookies()
const value = cookieStore.get('testCookie')?.value ?? 'none'
await setTimeout(300)
return (
<p>
Cookie: {value} ({new Date().toISOString()})
</p>
)
}
async function HeadersContent() {
'use cache: private'
cacheLife({ stale: 30 })
const headerStore = await headers()
const value = headerStore.get('x-test-header') ?? 'none'
await setTimeout(300)
return (
<p>
Header: {value} ({new Date().toISOString()})
</p>
)
}
async function ConnectionContent() {
await connection()
await setTimeout(600)
return <p>Dynamic content ({new Date().toISOString()})</p>
}
...@@ -403,6 +403,160 @@ describe('cached navigations', () => { ...@@ -403,6 +403,160 @@ describe('cached navigations', () => {
) )
}) })
it('caches runtime-prefetchable content from a navigation for instant second visit', async () => {
let page: Playwright.Page
const browser = await next.browser('/', {
async beforePageLoad(p: Playwright.Page) {
page = p
await page.clock.install()
},
})
const act = createRouterAct(page)
// First navigation — full dynamic request, no prefetch
await act(
async () => {
await browser.elementByCss('a[href="/runtime-prefetchable"]').click()
},
{ includes: 'Dynamic content' }
)
// Verify all content is visible
expect(await browser.elementById('cached-content').text()).toContain(
'Cached content'
)
expect(
await browser.elementById('search-params-boundary').text()
).toContain('Search params:')
expect(await browser.elementById('cookies-boundary').text()).toContain(
'Cookie:'
)
expect(await browser.elementById('headers-boundary').text()).toContain(
'Header:'
)
expect(await browser.elementById('connection-boundary').text()).toContain(
'Dynamic content'
)
// Navigate back to home
await browser.back()
expect(await browser.elementByCss('h1').text()).toBe('Home')
// Second navigation — no time has passed, so both the static cache
// (stale: 120s) and the runtime cache (stale: 30s from the
// short-lived cache entry in CookiesContent) should still be fresh.
// With unstable_instant { prefetch: 'runtime' }, runtime-prefetchable
// content (cookies, headers, searchParams) should be cached from the
// first navigation and show instantly alongside the static content.
// Only truly dynamic content (connection()) needs a server request.
await act(async () => {
await act(
async () => {
await browser.elementByCss('a[href="/runtime-prefetchable"]').click()
},
{
includes: 'Dynamic content',
block: true,
}
)
// Static cached content should be visible
expect(await browser.elementById('cached-content').text()).toContain(
'Cached content'
)
// Runtime-prefetchable content should also be visible (cached from
// the first navigation's embedded runtime prefetch stream)
expect(
await browser.elementById('search-params-boundary').text()
).toContain('Search params:')
expect(await browser.elementById('cookies-boundary').text()).toContain(
'Cookie:'
)
expect(await browser.elementById('headers-boundary').text()).toContain(
'Header:'
)
// Only connection() content should show a Suspense fallback — it's
// truly dynamic and not runtime-prefetchable
expect(await browser.elementById('connection-boundary').text()).toBe(
'Loading connection...'
)
})
// After unblocking, all content should be visible
expect(await browser.elementById('cached-content').text()).toContain(
'Cached content'
)
expect(
await browser.elementById('search-params-boundary').text()
).toContain('Search params:')
expect(await browser.elementById('cookies-boundary').text()).toContain(
'Cookie:'
)
expect(await browser.elementById('headers-boundary').text()).toContain(
'Header:'
)
expect(await browser.elementById('connection-boundary').text()).toContain(
'Dynamic content'
)
// Navigate back to home again
await browser.back()
expect(await browser.elementByCss('h1').text()).toBe('Home')
// Fast-forward past the runtime cache's stale time (30s).
await page.clock.fastForward(60_000)
// Third navigation — runtime cache is stale. Verify the navigation
// blocks on a full server request (nothing is cached).
//
// TODO: Ideally, the static cache (120s stale) should survive and show
// static content instantly even after the runtime cache expires. Currently
// the runtime prefetch write (PPRRuntime) evicts the static cache entry
// (PPR) via the fallback lookup in upsertSegmentEntry, so there's no
// static fallback after the runtime entry expires. This needs a layered
// cache approach where entries with different fetch strategies / stale
// times coexist independently.
await act(async () => {
await act(
async () => {
await browser.elementByCss('a[href="/runtime-prefetchable"]').click()
},
{
includes: 'Dynamic content',
block: true,
}
)
// With a stale cache, nothing from the target page should be visible
// while the request is blocked. The navigation stays on the home page.
const mainText = await (await browser.elementByCss('main')).innerText()
expect(mainText).not.toContain('Cached content')
expect(mainText).not.toContain('Search params:')
expect(mainText).not.toContain('Cookie:')
expect(mainText).not.toContain('Header:')
expect(mainText).not.toContain('Dynamic content')
})
// After unblocking, all content should be visible
expect(await browser.elementById('cached-content').text()).toContain(
'Cached content'
)
expect(
await browser.elementById('search-params-boundary').text()
).toContain('Search params:')
expect(await browser.elementById('cookies-boundary').text()).toContain(
'Cookie:'
)
expect(await browser.elementById('headers-boundary').text()).toContain(
'Header:'
)
expect(await browser.elementById('connection-boundary').text()).toContain(
'Dynamic content'
)
})
it('caches a fully static page from the initial HTML for subsequent navigations', async () => { it('caches a fully static page from the initial HTML for subsequent navigations', async () => {
let page: Playwright.Page let page: Playwright.Page
// Start directly at /fully-static — full HTML load, not a client-side // Start directly at /fully-static — full HTML load, not a client-side
......
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