Unverified Commit e92db453 authored by Sebastian "Sebbie" Silbermann's avatar Sebastian "Sebbie" Silbermann Committed by GitHub

[lts-active] Fix metadata propagation for deduplicated nested caches (#223)

Co-authored-by: 's avatarHendrik Liebau <mail@hendrik-liebau.de>
parent 40c2ba90
...@@ -204,18 +204,31 @@ class SharedCacheEntry { ...@@ -204,18 +204,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<CollectedCacheResult> | undefined
) { ) {
this.stream = stream this.stream = stream
this.pendingMetadata = pendingMetadata this.pendingMetadata = pendingMetadata
this.pendingCompletion =
pendingWrite === undefined
? pendingMetadata
: pendingWrite.then(
() => pendingMetadata,
() => pendingMetadata
)
} }
/** /**
...@@ -246,10 +259,9 @@ function ignoreReject() {} ...@@ -246,10 +259,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>()
...@@ -282,7 +294,7 @@ class ResolvableSharedCacheResult { ...@@ -282,7 +294,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()
) )
...@@ -582,22 +594,19 @@ function serveJoinedCacheEntry( ...@@ -582,22 +594,19 @@ function serveJoinedCacheEntry(
resumeDataCache resumeDataCache
) )
// 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
} }
...@@ -2928,10 +2937,11 @@ export async function cache( ...@@ -2928,10 +2937,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
...@@ -3328,12 +3338,7 @@ export async function cache( ...@@ -3328,12 +3338,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<CollectedCacheResult> | 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) {
...@@ -3344,7 +3349,7 @@ export async function cache( ...@@ -3344,7 +3349,7 @@ export async function cache(
) )
if (cacheHandler) { if (cacheHandler) {
metadataSource = saveToCacheHandler( pendingWrite = saveToCacheHandler(
cacheHandler, cacheHandler,
workStore, workStore,
id, id,
...@@ -3358,7 +3363,7 @@ export async function cache( ...@@ -3358,7 +3363,7 @@ export async function cache(
debug?.('leader resolved with generated entry', cacheHandlerKey) debug?.('leader resolved with generated entry', cacheHandlerKey)
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,
...@@ -3372,7 +3377,8 @@ export async function cache( ...@@ -3372,7 +3377,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({
...@@ -3440,7 +3446,8 @@ export async function cache( ...@@ -3440,7 +3446,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,
}, },
} }
......
...@@ -302,6 +302,16 @@ describe('app-root-param-getters - cache dedup with root params', () => { ...@@ -302,6 +302,16 @@ describe('app-root-param-getters - cache dedup with root params', () => {
if (skipped) return if (skipped) return
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 () => {
// Three concurrent requests: ca/en, ca/fr, ca/fr. // Three concurrent requests: ca/en, ca/fr, ca/fr.
const [$en, $fr1, $fr2] = await Promise.all([ const [$en, $fr1, $fr2] = await Promise.all([
......
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/dist/server/lib/cache-handlers/types').CacheHandler} * @type {import('next/dist/server/lib/cache-handlers/types').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$/
...@@ -135,25 +136,39 @@ describe('use-cache-custom-handler', () => { ...@@ -135,25 +136,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