Unverified Commit d0df62e8 authored by Hendrik Liebau's avatar Hendrik Liebau Committed by GitHub

Fix metadata propagation for deduplicated nested caches (#98808)

#94694 delayed shared metadata until handler writes settled to protect
cross-request retries. Same-request consumers also awaited this promise,
so an outer cache could save its result before inheriting the inner
cache's root-param dependencies, tags, and lifetime.

Metadata now becomes available when collection finishes. Cross-request
key verification and pending-invocation cleanup still wait for handler
writes to settle.

The regression tests hold an inner write pending while both outer caches
complete. They check metadata at write time and verify that a later
request with different root params cannot reuse the earlier result. The
fixtures disable startup preloading to isolate these tests from a
separate custom-handler registration race that we'll address in a
follow-up.
parent d5b615eb
...@@ -220,18 +220,31 @@ class SharedCacheEntry { ...@@ -220,18 +220,31 @@ class SharedCacheEntry {
private stream: ReadableStream<Uint8Array> private stream: ReadableStream<Uint8Array>
/** /**
* The pending metadata promise. Cross-request joiners need to await this for * Resolves when collection finishes, without waiting for handler writes.
* root param verification BEFORE calling fork(). Intra-request joiners chain
* .then() for fire-and-forget propagation.
*/ */
public readonly pendingMetadata: Promise<CacheResultMetadata> public readonly pendingMetadata: Promise<CacheResultMetadata>
/**
* Resolves with collected metadata after any handler writes settle. Write
* failures do not discard the metadata. Collection failures still reject this
* promise.
*/
public readonly pendingCompletion: Promise<CacheResultMetadata>
constructor( constructor(
stream: ReadableStream<Uint8Array>, stream: ReadableStream<Uint8Array>,
pendingMetadata: Promise<CacheResultMetadata> pendingMetadata: Promise<CacheResultMetadata>,
pendingWrite: Promise<void> | undefined
) { ) {
this.stream = stream this.stream = stream
this.pendingMetadata = pendingMetadata this.pendingMetadata = pendingMetadata
this.pendingCompletion =
pendingWrite === undefined
? pendingMetadata
: pendingWrite.then(
() => pendingMetadata,
() => pendingMetadata
)
} }
/** /**
...@@ -262,10 +275,9 @@ function ignoreReject() {} ...@@ -262,10 +275,9 @@ function ignoreReject() {}
* Manages the deferred promise for a shared cache result, tracks which maps * Manages the deferred promise for a shared cache result, tracks which maps
* it's registered in, and drives cleanup from resolve/reject. * it's registered in, and drives cleanup from resolve/reject.
* *
* For 'cached' results, cleanup is lazy: entries stay in the maps until * Cached results stay in the maps until collection finishes and handler writes
* metadata/collection resolves, giving late-arriving invocations a chance to * settle. Later invocations can join while either remains pending. For
* join while the leader streams. For 'prerender-dynamic' and errors, cleanup * 'prerender-dynamic' and errors, cleanup is immediate.
* is immediate.
*/ */
class ResolvableSharedCacheResult { class ResolvableSharedCacheResult {
private readonly deferred = createPromiseWithResolvers<SharedCacheResult>() private readonly deferred = createPromiseWithResolvers<SharedCacheResult>()
...@@ -298,7 +310,7 @@ class ResolvableSharedCacheResult { ...@@ -298,7 +310,7 @@ class ResolvableSharedCacheResult {
// Retain only an entry that collected successfully. A failed collection // Retain only an entry that collected successfully. A failed collection
// leaves metadata a later invocation cannot read, so it is dropped like // leaves metadata a later invocation cannot read, so it is dropped like
// any other failure and the next invocation regenerates. // any other failure and the next invocation regenerates.
result.entry.pendingMetadata.then( result.entry.pendingCompletion.then(
() => this.cleanupAndRetain(), () => this.cleanupAndRetain(),
() => this.cleanup() () => this.cleanup()
) )
...@@ -594,22 +606,19 @@ function serveJoinedCacheEntry( ...@@ -594,22 +606,19 @@ function serveJoinedCacheEntry(
logPrefix logPrefix
) )
// End the cache signal read when the result is fully collected, not when the // End the cache read after collection and metadata propagation, not when the
// stream is available. A failed collection has no metadata to propagate but // value stream becomes available. This does not wait for handler persistence.
// must still balance the read, so both settlements end it; leaving it open // A failed collection or propagation must still end the read so it cannot
// would stall a prerender waiting for its cache reads. The trailing .catch() // stall prerendering. The catch prevents an unhandled rejection after the
// covers propagation itself throwing after the rendering stream resolved. // stream has been returned.
sharedCacheEntry.pendingMetadata sharedCacheEntry.pendingMetadata
.then( .then((metadata) => {
(metadata) => { maybePropagateCacheEntryMetadata(cacheContext, metadata)
cacheSignal?.endRead() })
maybePropagateCacheEntryMetadata(cacheContext, metadata) .finally(() => {
}, cacheSignal?.endRead()
() => { })
cacheSignal?.endRead() .catch(ignoreReject)
}
)
.catch(() => {})
return stream return stream
} }
...@@ -2956,10 +2965,11 @@ export async function cache( ...@@ -2956,10 +2965,11 @@ export async function cache(
const sharedCacheResult = await crossRequestPendingCacheInvocation const sharedCacheResult = await crossRequestPendingCacheInvocation
if (sharedCacheResult.type === 'cached') { if (sharedCacheResult.type === 'cached') {
// Root param verification: wait for metadata, then check key. MUST // Verify root params before forking the stream. The shared
// happen before fork() — if key mismatches, we retry without having // invocation must complete first, including collection and write
// used the stream. // settlement. A changed key retries the handler lookup, which must
const metadata = await sharedCacheResult.entry.pendingMetadata // not run before the write settles.
const metadata = await sharedCacheResult.entry.pendingCompletion
// Ensure known root param names are up-to-date before verifying the // Ensure known root param names are up-to-date before verifying the
// key, since the leader's save path may not have updated them yet // key, since the leader's save path may not have updated them yet
...@@ -3393,12 +3403,7 @@ export async function cache( ...@@ -3393,12 +3403,7 @@ export async function cache(
const { stream: newStream, pendingCacheResult } = result const { stream: newStream, pendingCacheResult } = result
// Cross-request joiners derive their metadata from this promise. By let pendingWrite: Promise<void> | undefined
// default it's the collected result, but when we write to a cache
// handler we swap in a promise that resolves only after the write has
// landed, so a joiner that re-reads its recomputed key finds the
// entry.
let metadataSource: Promise<CollectedCacheResult> = pendingCacheResult
// When draft mode is enabled, we must not save the cache entry. // When draft mode is enabled, we must not save the cache entry.
if (!workStore.isDraftMode) { if (!workStore.isDraftMode) {
...@@ -3410,7 +3415,7 @@ export async function cache( ...@@ -3410,7 +3415,7 @@ export async function cache(
) )
if (cacheHandler) { if (cacheHandler) {
const pendingWrite = saveToCacheHandler( pendingWrite = saveToCacheHandler(
cacheHandler, cacheHandler,
id, id,
cacheHandlerKeyBase, cacheHandlerKeyBase,
...@@ -3419,15 +3424,6 @@ export async function cache( ...@@ -3419,15 +3424,6 @@ export async function cache(
) )
workStore.pendingRevalidateWrites ??= [] workStore.pendingRevalidateWrites ??= []
workStore.pendingRevalidateWrites.push(pendingWrite) workStore.pendingRevalidateWrites.push(pendingWrite)
// Wait for cache writes before exposing metadata. Cross-request
// joiners may recompute their root-param-specific key from it,
// then read the handler again. A write failure does not reject
// the metadata: joiners can regenerate if no entry was stored.
// Collection failures still propagate through `savedCacheResult`.
metadataSource = pendingWrite.then(
() => savedCacheResult,
() => savedCacheResult
)
} }
} }
...@@ -3438,7 +3434,7 @@ export async function cache( ...@@ -3438,7 +3434,7 @@ export async function cache(
) )
const pendingMetadata: Promise<CacheResultMetadata> = const pendingMetadata: Promise<CacheResultMetadata> =
metadataSource.then((collected) => ({ pendingCacheResult.then((collected) => ({
tags: collected.entry.tags, tags: collected.entry.tags,
revalidate: collected.entry.revalidate, revalidate: collected.entry.revalidate,
expire: collected.entry.expire, expire: collected.entry.expire,
...@@ -3452,7 +3448,8 @@ export async function cache( ...@@ -3452,7 +3448,8 @@ export async function cache(
const sharedCacheEntry = new SharedCacheEntry( const sharedCacheEntry = new SharedCacheEntry(
newStream, newStream,
pendingMetadata pendingMetadata,
pendingWrite
) )
stream = sharedCacheEntry.fork() stream = sharedCacheEntry.fork()
resolvableSharedCacheResult.resolve({ resolvableSharedCacheResult.resolve({
...@@ -3524,7 +3521,8 @@ export async function cache( ...@@ -3524,7 +3521,8 @@ export async function cache(
const sharedCacheEntry = new SharedCacheEntry( const sharedCacheEntry = new SharedCacheEntry(
stream, stream,
Promise.resolve(entryMetadata) Promise.resolve(entryMetadata),
undefined
) )
stream = sharedCacheEntry.fork() stream = sharedCacheEntry.fork()
resolvableSharedCacheResult.resolve({ resolvableSharedCacheResult.resolve({
......
import { cacheTag } from 'next/cache'
import { lang } from 'next/root-params'
import { connection } from 'next/server'
async function inner() {
'use cache'
const language = await lang()
cacheTag('nested-inner', `nested-language-${language}`)
return language
}
async function outerOne() {
'use cache'
cacheTag('nested-outer-one')
return inner()
}
async function outerTwo() {
'use cache'
cacheTag('nested-outer-two')
return inner()
}
export default async function Page({
searchParams,
}: {
searchParams: Promise<{ prime?: string }>
}) {
await connection()
const { prime } = await searchParams
const first = prime === '1' ? await outerOne() : null
const second = await outerTwo()
return (
<>
{first === null ? null : <p id="first">{first}</p>}
<p id="second">{second}</p>
</>
)
}
// @ts-check
const defaultCacheHandler =
require('next/dist/server/lib/cache-handlers/default.external').default
const { EventEmitter, once } = require('node:events')
const outerWrites = new EventEmitter()
const pendingOuterWrites = once(outerWrites, 'complete')
const observedOuters = new Set()
// Delay the English inner write until both outer entries reach `set()`. The
// nested route calls `outerOne()` and then `outerTwo()`, which share `inner()`.
// The wrapper must propagate the inner language dependency before it computes
// the cache key for `outerTwo()`. Otherwise, a later French request can reuse
// the English outer entry.
/**
* @type {import('next/cache').CacheHandler}
*/
module.exports = {
...defaultCacheHandler,
async set(cacheKey, pendingEntry) {
const { tags } = await pendingEntry
const outer = tags.find(
(tag) => tag === 'nested-outer-one' || tag === 'nested-outer-two'
)
const isRedirect = tags.some((tag) => tag.startsWith('_N_RP_'))
// Redirects are extra writes; count only each outer cache's value entry.
if (outer !== undefined && !isRedirect) {
observedOuters.add(outer)
if (observedOuters.size === 2) {
outerWrites.emit('complete')
}
}
// Hold only the English prime; a French request calls just one outer.
if (
tags.includes('nested-language-en') &&
outer === undefined &&
!isRedirect
) {
await pendingOuterWrites
}
return defaultCacheHandler.set(cacheKey, pendingEntry)
},
}
import type { NextConfig } from 'next' import type { NextConfig } from 'next'
const nextConfig: NextConfig = { const nextConfig: NextConfig = {
cacheHandlers: {
default: require.resolve('./handler.js'),
},
experimental: { experimental: {
// Disable startup preloading so the first request loads this fixture's
// handler before rendering. Preloading initializes the registry before its
// custom-handler import finishes. A concurrent request can then use the
// built-in handler and bypass the delayed write that this test needs.
//
// TODO: Make concurrent custom-handler initialization await registration.
// Then remove this fixture's `preloadEntriesOnStart: false` workaround.
preloadEntriesOnStart: false,
useCache: true, useCache: true,
}, },
} }
......
...@@ -385,6 +385,16 @@ describe('app-root-param-getters - cache dedup with root params', () => { ...@@ -385,6 +385,16 @@ describe('app-root-param-getters - cache dedup with root params', () => {
files: join(__dirname, 'fixtures', 'use-cache-dedup'), files: join(__dirname, 'fixtures', 'use-cache-dedup'),
}) })
it('should key a joining outer cache by the root params read by its inner cache', async () => {
const english = await next.render$('/ca/en/nested?prime=1')
expect(english('#first').text()).toBe('en')
expect(english('#second').text()).toBe('en')
const french = await next.render$('/ca/fr/nested')
expect(french('#first')).toHaveLength(0)
expect(french('#second').text()).toBe('fr')
})
it('should dedupe same root params and isolate different root params', async () => { it('should dedupe same root params and isolate different root params', async () => {
// In deploy mode, this can flake if Fluid routes concurrent requests // In deploy mode, this can flake if Fluid routes concurrent requests
// to different function instances: each instance may independently // to different function instances: each instance may independently
......
import { connection } from 'next/server'
import cacheWrites from '../../cache-writes'
export async function GET() {
await connection()
return Response.json(cacheWrites)
}
import { cacheLife, cacheTag } from 'next/cache' import { cacheLife, cacheTag } from 'next/cache'
import { connection } from 'next/server' import { connection } from 'next/server'
import { setTimeout } from 'timers/promises'
async function Inner() { async function Inner() {
'use cache' 'use cache'
await setTimeout(1000)
// This should lower the default cache lives of the outer cache scopes. // This should lower the default cache lives of the outer cache scopes.
cacheLife({ revalidate: 180, expire: 300 }) cacheLife({ revalidate: 180, expire: 300 })
cacheTag('inner') cacheTag('inner')
...@@ -19,7 +16,7 @@ async function Outer1() { ...@@ -19,7 +16,7 @@ async function Outer1() {
cacheTag('outer1') cacheTag('outer1')
return <Inner /> return Inner()
} }
async function Outer2() { async function Outer2() {
...@@ -27,16 +24,19 @@ async function Outer2() { ...@@ -27,16 +24,19 @@ async function Outer2() {
cacheTag('outer2') cacheTag('outer2')
return <Inner /> return Inner()
} }
export default async function Page() { export default async function Page() {
await connection() await connection()
const first = await Outer1()
const second = await Outer2()
return ( return (
<> <>
<Outer1 /> {first}
<Outer2 /> {second}
</> </>
) )
} }
// @ts-check
/**
* @typedef {{ cacheKey: string, tags: string[], stale: number, revalidate: number, expire: number }} CacheWrite
*/
/**
* @type {typeof globalThis & { cacheWrites?: CacheWrite[] }}
*/
const reference = globalThis
module.exports = reference.cacheWrites ??= []
...@@ -4,6 +4,11 @@ const defaultCacheHandler = ...@@ -4,6 +4,11 @@ const defaultCacheHandler =
require('next/dist/server/lib/cache-handlers/default.external').default require('next/dist/server/lib/cache-handlers/default.external').default
const { AsyncLocalStorage } = require('node:async_hooks') const { AsyncLocalStorage } = require('node:async_hooks')
const snapshot = AsyncLocalStorage.snapshot() const snapshot = AsyncLocalStorage.snapshot()
const cacheWrites = require('./cache-writes')
const { EventEmitter, once } = require('node:events')
const outerWrites = new EventEmitter()
const pendingOuterWrites = once(outerWrites, 'complete')
const observedOuters = new Set()
/** /**
* @type {import('next/cache').CacheHandler} * @type {import('next/cache').CacheHandler}
...@@ -17,14 +22,33 @@ const cacheHandler = { ...@@ -17,14 +22,33 @@ const cacheHandler = {
async set(cacheKey, pendingEntry) { async set(cacheKey, pendingEntry) {
console.log('ModernCustomCacheHandler::set', cacheKey) console.log('ModernCustomCacheHandler::set', cacheKey)
pendingEntry.then(({ revalidate, expire, tags }) => { const { stale, revalidate, expire, tags } = await pendingEntry
snapshot(() => { snapshot(() => {
console.log( console.log(
`ModernCustomCacheHandler::set-resolved-entry revalidate: ${revalidate}, expire: ${expire}, tags: ${tags}\n ${cacheKey}` `ModernCustomCacheHandler::set-resolved-entry revalidate: ${revalidate}, expire: ${expire}, tags: ${tags}\n ${cacheKey}`
) )
})
}) })
// Copy tags so delayed propagation cannot change the recorded metadata.
cacheWrites.push({ cacheKey, stale, revalidate, expire, tags: [...tags] })
// Hold the inner write until both outer entries reach this handler. The
// nested route calls `Outer1()` and then `Outer2()`, which share `Inner()`.
// The second call must inherit the inner metadata while persistence is
// still pending. The test checks the recorded tags and lifetimes for this
// ordering.
const outer = tags.find((tag) => tag === 'outer1' || tag === 'outer2')
if (outer !== undefined) {
observedOuters.add(outer)
if (observedOuters.size === 2) {
outerWrites.emit('complete')
}
}
if (tags.includes('inner') && outer === undefined) {
await pendingOuterWrites
}
return defaultCacheHandler.set(cacheKey, pendingEntry) return defaultCacheHandler.set(cacheKey, pendingEntry)
}, },
......
...@@ -6,6 +6,16 @@ const nextConfig = { ...@@ -6,6 +6,16 @@ const nextConfig = {
cacheHandlers: { cacheHandlers: {
default: require.resolve('./handler.js'), default: require.resolve('./handler.js'),
}, },
experimental: {
// Disable startup preloading so the first request loads this fixture's
// handler before rendering. Preloading initializes the registry before its
// custom-handler import finishes. A concurrent request can then use the
// built-in handler and bypass the delayed write that this test needs.
//
// TODO: Make concurrent custom-handler initialization await registration.
// Then remove this fixture's `preloadEntriesOnStart: false` workaround.
preloadEntriesOnStart: false,
},
} }
module.exports = nextConfig module.exports = nextConfig
import { nextTestSetup } from 'e2e-utils' import { nextTestSetup } from 'e2e-utils'
import { retry } from 'next-test-utils' import { retry } from 'next-test-utils'
import type { CacheWrite } from './cache-writes'
const isoDateRegExp = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z$/ const isoDateRegExp = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z$/
...@@ -129,25 +130,39 @@ describe('use-cache-custom-handler', () => { ...@@ -129,25 +130,39 @@ describe('use-cache-custom-handler', () => {
} }
it('should dedupe nested caches across different outer cache scopes, and still propagate cache life/tags correctly', async () => { it('should dedupe nested caches across different outer cache scopes, and still propagate cache life/tags correctly', async () => {
await next.fetch('/nested') const $ = await next.render$('/nested')
const values = $('p#inner')
.map((_, element) => $(element).text())
.get()
expect(values).toHaveLength(2)
expect(values[0]).toBeTruthy()
expect(values[0]).toBe(values[1])
await retry(async () => { await retry(async () => {
const cliOutput = next.cliOutput.slice(outputIndex) const writes: CacheWrite[] = await next
.fetch('/cache-writes')
expect(cliOutput).toIncludeRepeated( .then((response) => response.json())
`ModernCustomCacheHandler::set-resolved-entry revalidate: 180, expire: 300, tags: inner`, const nestedWrites = writes.filter(({ tags }) =>
1 tags.some((tag) => ['inner', 'outer1', 'outer2'].includes(tag))
)
expect(cliOutput).toIncludeRepeated(
`ModernCustomCacheHandler::set-resolved-entry revalidate: 180, expire: 300, tags: outer1,inner`,
1
)
expect(cliOutput).toIncludeRepeated(
`ModernCustomCacheHandler::set-resolved-entry revalidate: 180, expire: 300, tags: outer2,inner`,
1
) )
expect(new Set(nestedWrites.map(({ cacheKey }) => cacheKey)).size).toBe(3)
expect(nestedWrites).toEqual([
expect.objectContaining({
revalidate: 180,
expire: 300,
tags: ['inner'],
}),
expect.objectContaining({
revalidate: 180,
expire: 300,
tags: ['outer1', 'inner'],
}),
expect.objectContaining({
revalidate: 180,
expire: 300,
tags: ['outer2', 'inner'],
}),
])
}) })
}) })
......
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