Unverified Commit 1449fb9b authored by Hendrik Liebau's avatar Hendrik Liebau Committed by GitHub

Clarify 'use cache' coordination and fix cache sharing

The wrapper separates invocation preparation, Resume Data Cache reads,
cache handler lookups, generation, and cache entry consumption. The
foreground and background paths express reuse and lookup retries directly.
Pending and completed invocations have separate types, and their state
updates show which cache handler lookup and result they replace.

Intra-request deduplication shares cache handler lookups and generated
entries within a `WorkStore`. Cross-request generation deduplication shares
only pending generation and its cache handler writes. Each `WorkStore`
validates handler entries with its own implicit tags, so a concurrent
request cannot bypass path revalidation by joining another handler lookup.

Each invocation applies cache-life rules and propagates metadata to its
own outer scope. A direct prerender invocation can omit a short-lived
entry while a nested cache consumes it. Separate prerenders create their
own hanging promises when they omit handler entries. The Resume Data
Cache records the omission for later render phases.

The downstack tests extend PR #100652 and characterize the sharing bugs.
This change updates their expectations for independent handler lookups
and per-invocation rendering decisions. Background revalidation preserves
the Resume Data Cache consistency behavior from PR #100447, and the stream
error and cancellation handling from PR #100673 remains intact.
parent f07ce3e7
......@@ -5,7 +5,7 @@ import type { DeepReadonly } from '../../shared/lib/deep-readonly'
import type { AppSegmentConfig } from '../../build/segment-config/app/app-segment-config'
import type { AfterContext } from '../after/after-context'
import type { ResolvedCacheLifeProfiles } from '../config-shared'
import type { SharedCacheResult } from '../use-cache/use-cache-wrapper'
import type { CacheDeduplicationState } from '../use-cache/use-cache-wrapper'
import type { ValidationLevel } from '../config-shared'
// Share the instance module in the next-shared layer
......@@ -105,29 +105,11 @@ export interface WorkStore {
clientComponentLoadTracker: ClientComponentLoadTracker | undefined
/**
* Tracks pending `"use cache"` invocations within the current request scope,
* keyed by the serialized cache key (coarse key). Used for intra-request
* deduplication: when multiple components call the same cache function within
* a single request, only the first one runs (cache handler lookup +
* generation), and joiners tee its result stream.
* Root params are identical within a request, so the coarse key is sufficient.
* Stores intra-request deduplication state for each serialized key. Private
* caches and custom cache handlers retain completed entries. Built-in
* handlers release completed stream references and read the handler again.
*/
pendingCacheInvocations?: Map<string, Promise<SharedCacheResult>>
/**
* Invocations from this request that have already completed, keyed the same
* way as `pendingCacheInvocations`. Entries move here when their fill
* finishes rather than being dropped, so a later invocation of the same cache
* function reuses the entry instead of repeating the cache handler lookup
* and, on a miss, the work.
*
* Only populated for kinds where that saves something real: private caches,
* which have no cache handler in production, and kinds whose handler was
* supplied by the platform or by `cacheHandlers` config, whose reads may be
* remote. A built-in handler read is a map lookup, so retaining its entries
* would cost memory for nothing.
*/
completedCacheInvocations?: Map<string, Promise<SharedCacheResult>>
cacheDeduplicationStates?: Map<string, CacheDeduplicationState>
/**
* Set by the dev-server's hang-detection probe worker (see
......
......@@ -536,7 +536,7 @@ for (const { held, failure } of [
env: { NEXT_PRIVATE_DEBUG_CACHE: '1' },
})
it('currently shares the producer lookup while waiting for both root-param writes', async () => {
it('waits for both producer writes before retrying with different root values', async () => {
const id = `write-order-${randomUUID()}`
const control = (action: string) =>
next.fetch(
......@@ -567,16 +567,7 @@ for (const { held, failure } of [
await retry(async () => {
const state = await readState()
expect(state.requestedLanguages).toEqual(['en', 'fr'])
expect(state.lookupKeys).toHaveLength(1)
expect(
next.cliOutput
.split('\n')
.some(
(line) =>
line.includes('joining pending cross-request invocation') &&
line.includes(id)
)
).toBe(true)
expect(state.lookupKeys).toHaveLength(2)
})
await control('release-fill')
await retry(async () => {
......@@ -594,7 +585,7 @@ for (const { held, failure } of [
// for the held write, including when that settled write rejected.
const pendingState = await readState()
expect(pendingState.generatedLanguages).toEqual(['en'])
expect(pendingState.lookupKeys).toHaveLength(1)
expect(pendingState.lookupKeys).toHaveLength(2)
await control('release-write')
const [englishPage, frenchPage] = await Promise.all([english, french])
expect(englishPage('#value').text()).toStartWith('en:')
......@@ -623,7 +614,7 @@ describe('root cache lookup across two pending generations', () => {
env: { NEXT_PRIVATE_DEBUG_CACHE: '1' },
})
it('currently joins both generations without reading the redirected handler key', async () => {
it('keeps the initial generation available after a redirected generation completes during the lookup', async () => {
const id = `lookup-history-${randomUUID()}`
const pathname = `/ca/en/write-failure?id=${id}`
const control = (action: string) =>
......@@ -636,7 +627,6 @@ describe('root cache lookup across two pending generations', () => {
(response) =>
response.json() as Promise<{
generatedLanguages: string[]
requestedLanguages: string[]
initialLookupCount: number
specificLookupCount: number
writtenLanguages: string[]
......@@ -653,16 +643,7 @@ describe('root cache lookup across two pending generations', () => {
})
consumer = next.render$(`${pathname}&outer=1`)
await retry(async () => {
expect((await readState()).requestedLanguages).toEqual(['en', 'en'])
expect(
next.cliOutput
.split('\n')
.some(
(line) =>
line.includes('joining pending cross-request invocation') &&
line.includes(id)
)
).toBe(true)
expect((await readState()).initialLookupCount).toBe(2)
})
// Read root params become known while the initial value write is held.
// The new request starts generation under the root-specific key.
......@@ -674,30 +655,22 @@ describe('root cache lookup across two pending generations', () => {
await retry(async () => {
expect((await readState()).generatedLanguages).toEqual(['en', 'en'])
})
const pendingState = await readState()
expect(pendingState.initialLookupCount).toBe(1)
expect(pendingState.specificLookupCount).toBe(1)
await control('release-write')
await retry(() => {
expect(
next.cliOutput
.split('\n')
.some(
(line) =>
line.includes('joining pending cross-request invocation') &&
line.includes(id) &&
line.includes('"lang","en"')
)
).toBe(true)
await control('release-initial-lookup')
await retry(async () => {
expect((await readState()).specificLookupCount).toBe(2)
})
await control('release-second-write')
const [, specificPage, page] = await Promise.all([
initialProducer,
specificProducer,
consumer,
])
expect(page('#value').text()).toBe(specificPage('#value').text())
await specificProducer
// The redirected cache miss returns after the second producer finishes.
// Its retry sees a stale entry; the outer cache needs fresh data and must
// still find the first pending producer.
await control('release-specific-lookup')
await retry(async () => {
expect((await readState()).specificLookupCount).toBe(3)
})
expect((await readState()).generatedLanguages).toEqual(['en', 'en'])
await control('release-write')
const [, page] = await Promise.all([initialProducer, consumer])
expect(page('#value').text()).toStartWith('en:')
} finally {
await control('release-fill')
......
......@@ -13,7 +13,7 @@ export async function GET(request: Request) {
writes: cacheSharingState.writes.filter(
(tag) => tag === `observed-fill:${id}`
),
pausedLookupKeys: cacheSharingState.pausedLookupKeys.filter((key) =>
routeBLookupKeys: cacheSharingState.routeBLookupKeys.filter((key) =>
key.includes(JSON.stringify(id))
),
selectedEntrySoftTags: cacheSharingState.selectedEntrySoftTags,
......
......@@ -16,8 +16,8 @@
* IDs whose cached functions have started execution.
* @property {string[]} writes
* Tags from completed handler writes.
* @property {string[]} pausedLookupKeys
* Keys whose `get()` calls wait on `pendingRouteLookupResult`.
* @property {string[]} routeBLookupKeys
* Keys read by route B during the concurrent fill tests.
* @property {Promise<void> | null} pendingFill
* Pauses execution of the cached function.
* @property {(() => void) | null} releaseFill
......@@ -41,7 +41,7 @@ module.exports = reference.cacheSharingState ??= {
releaseEntryLookup: null,
fills: [],
writes: [],
pausedLookupKeys: [],
routeBLookupKeys: [],
pendingFill: null,
releaseFill: null,
pendingRouteLookupResult: null,
......
......@@ -18,12 +18,11 @@ const routeAwareCacheHandler = {
const entry = await cacheHandler.get(cacheKey, softTags)
if (
cacheKey.includes('observed-miss-') &&
softTags.some((tag) => tag.includes('/path-revalidation/b')) &&
cacheSharingState.pendingRouteLookupResult !== null
softTags.some((tag) => tag.includes('/path-revalidation/b'))
) {
// Record this `get()` call before it waits on `pendingRouteLookupResult`.
// The handler has not checked the route's implicit-tag expiration yet.
cacheSharingState.pausedLookupKeys.push(cacheKey)
// The underlying read has selected its result. A held lookup can
// therefore return a miss after a concurrent write completes.
cacheSharingState.routeBLookupKeys.push(cacheKey)
await cacheSharingState.pendingRouteLookupResult
}
if (entry === undefined) {
......
......@@ -227,7 +227,7 @@ describe('use-cache-custom-handler', () => {
// Development serves front-cache hits before reconciling the backing cache.
// Its serialized backing reads cannot reach both held lookups concurrently.
// @force-gate start
it('currently shares a handler lookup across routes and serves old data after revalidatePath()', async () => {
it('regenerates data for a revalidated route while another route reads the same cache entry', async () => {
const control = (action: string) =>
next.fetch('/path-revalidation', { method: 'POST', body: action })
const readLookupState = () =>
......@@ -272,13 +272,15 @@ describe('use-cache-custom-handler', () => {
routeARendering,
routeBRendering,
])
// B currently reuses A's handler result despite `revalidatePath()`. Only
// A's implicit tags reach `get()`.
// A must return the existing value. B must generate a new value because
// its implicit tags were revalidated. Each `get()` must receive its own
// route's implicit tags.
expect(routeAPage('#data').text()).toBe(initial)
expect(routeBPage('#data').text()).toBe(initial)
expect(routeBPage('#data').text()).not.toBe(initial)
expect(routeBPage('#data').text()).not.toBe('')
expect((await readLookupState()).softTags).toEqual([
expect.arrayContaining(['_N_T_/path-revalidation/a/page']),
expect.arrayContaining(['_N_T_/path-revalidation/b/page']),
])
} finally {
await control('release-entry-lookup')
......@@ -289,7 +291,7 @@ describe('use-cache-custom-handler', () => {
// The configured handler validates implicit tags before the test pauses it.
// Development's front cache can serve the entry without that handler read.
// @force-gate start
it('currently shares a handler lookup between equal routes separated by path revalidation', async () => {
it('reads the handler independently for equal routes separated by path revalidation', async () => {
const id = `same-route-${randomUUID()}`
const pathname = `/path-revalidation/a?id=${id}`
const control = (action: string) =>
......@@ -318,24 +320,14 @@ describe('use-cache-custom-handler', () => {
expect((await readState()).selectedEntrySoftTags).toHaveLength(1)
})
await control('revalidate-route-a')
const outputIndex = next.cliOutput.length
afterRevalidation = next.render$(pathname)
await retry(() => {
expect(
next.cliOutput
.slice(outputIndex)
.split('\n')
.some(
(line) =>
line.includes('joining pending cross-request invocation') &&
line.includes(id)
)
).toBe(true)
await retry(async () => {
expect((await readState()).writes).toHaveLength(2)
})
await control('release-selected-entry')
const freshPage = await afterRevalidation
expect(freshPage('#data').text()).toBe(initial)
expect(freshPage('#data').text()).not.toBe(initial)
expect(freshPage('#data').text()).not.toBe('')
await control('release-selected-entry')
expect((await beforeRevalidation)('#data').text()).toBe(initial)
} finally {
await control('release-selected-entry')
......@@ -343,10 +335,9 @@ describe('use-cache-custom-handler', () => {
}
})
// This test controls when the custom handler's `get()` returns. Development
// can serve an entry from its in-memory handler before that call completes.
// @force-gate start
it('currently shares a pending fill without checking route-specific cache invalidation', async () => {
async function readAfterConcurrentGenerationCompletes(
revalidateRouteB: boolean
) {
const id = `observed-miss-${randomUUID()}`
const pathname = `/path-revalidation?id=${id}`
const control = (action: string) =>
......@@ -357,8 +348,7 @@ describe('use-cache-custom-handler', () => {
response.json() as Promise<{
fills: string[]
writes: string[]
pausedLookupKeys: string[]
startedRoutes: string[]
routeBLookupKeys: string[]
}>
)
const initial = (await next.render$(`/path-revalidation/a?id=${id}`))(
......@@ -368,9 +358,8 @@ describe('use-cache-custom-handler', () => {
expect((await readState()).writes).toHaveLength(1)
})
// Start generation for A, then revalidate B before that generation
// completes. Configure B's `get()` to wait until A's handler write
// completes.
// Route B's lookup selects its result while A's replacement fill is
// pending. The handler holds that result until A's write completes.
await control('hold-fill')
await control('invalidate-entry')
const routeARendering = next.render$(`/path-revalidation/a?id=${id}`)
......@@ -379,11 +368,15 @@ describe('use-cache-custom-handler', () => {
await retry(async () => {
expect((await readState()).fills).toHaveLength(2)
})
await control('revalidate-route-b')
if (revalidateRouteB) {
// A's entry predates B's invalidation, so the handler must reject it
// for B.
await control('revalidate-route-b')
}
await control('hold-route-lookup-result')
routeBRendering = next.render$(`/path-revalidation/b?id=${id}`)
await retry(async () => {
expect((await readState()).startedRoutes).toContain(`b:${id}`)
expect((await readState()).routeBLookupKeys).toHaveLength(1)
})
await control('release-fill')
......@@ -394,23 +387,49 @@ describe('use-cache-custom-handler', () => {
await retry(async () => {
expect((await readState()).writes).toHaveLength(2)
})
// B currently joins A's generated result without calling `get()`. The
// empty `pausedLookupKeys` array confirms that B skipped its own lookup.
await control('release-route-lookup-result')
const routeBPage = await routeBRendering
expect(routeBPage('#data').text()).toBe(refreshed)
expect(routeBPage('#data').text()).not.toBe('')
await retry(async () => {
const state = await retry(async () => {
const state = await readState()
expect(state.pausedLookupKeys).toHaveLength(0)
expect(state.fills).toHaveLength(2)
expect(state.writes).toHaveLength(2)
expect(state.writes).toHaveLength(state.fills.length)
return state
})
return {
producerValue: refreshed,
consumerValue: routeBPage('#data').text(),
state,
}
} finally {
await control('release-fill')
await control('release-route-lookup-result')
await Promise.allSettled([routeARendering, routeBRendering])
}
}
// These tests control when the custom handler's `get()` returns. Development
// can serve an entry from its in-memory handler before that call completes.
// @force-gate start
it('reuses a handler entry written while its initial lookup was pending', async () => {
const { producerValue, consumerValue, state } =
await readAfterConcurrentGenerationCompletes(false)
expect(consumerValue).toBe(producerValue)
expect(state.fills).toHaveLength(2)
expect(state.writes).toHaveLength(2)
expect(state.routeBLookupKeys).toHaveLength(2)
})
// @force-gate start
it('respects a route-specific handler miss after an observed fill finishes during lookup', async () => {
const { producerValue, consumerValue, state } =
await readAfterConcurrentGenerationCompletes(true)
expect(consumerValue).not.toBe(producerValue)
expect(consumerValue).not.toBe('')
expect(state.fills).toHaveLength(3)
expect(state.writes).toHaveLength(3)
expect(state.routeBLookupKeys).toHaveLength(2)
})
if (isNextStart) {
......
......@@ -354,7 +354,7 @@ describe('use-cache-swr', () => {
}
})
it('currently gives nested callers stale data after background revalidation completes', async () => {
it('reuses a completed background revalidation when outer caches need fresh data from the same stale lookup', async () => {
const id = `caller-context-${randomUUID()}`
const initial = await warmData(id)
// Pause the page after its direct `readData()` call returns stale data. The
......@@ -367,12 +367,12 @@ describe('use-cache-swr', () => {
expect(dataRequestCountsByKey.get(`outer:${id}`)).toBeGreaterThan(0)
expectOneWrite(id)
})
// Both nested calls currently reuse the direct call's stale value,
// although the handler already contains the revalidated entry.
// The nested calls must use the revalidated entry after its handler write
// completes. Neither call should execute the cached function again.
releaseDataResponses(`outer:${id}`)
const $ = await rendering
expect($('#direct').text()).toBe(initial.value)
expect($('#first').text()).toBe(initial.value)
expect($('#first').text()).not.toBe(initial.value)
expect($('#first').text()).not.toBe('')
expect($('#second').text()).toBe($('#first').text())
expect(dataRequestCountsByKey.get(`fill:${id}`)).toBe(2)
......@@ -383,7 +383,7 @@ describe('use-cache-swr', () => {
}
})
it('currently delays a direct stale read behind a nested foreground fill', async () => {
it('serves stale data to a direct caller while an outer cache waits for the shared foreground fill', async () => {
const id = `caller-context-${randomUUID()}`
const initial = await warmData(id)
// Pause the nested `readData()` call at `fill:<id>`, then start the direct
......@@ -400,10 +400,20 @@ describe('use-cache-swr', () => {
).toBeGreaterThan(0)
})
releaseDataResponses(`direct-ready:${id}`)
// The `direct-served:<id>` request confirms that the direct call resolved
// while the nested call's generation remains pending.
await retry(
() => {
expect(
dataRequestCountsByKey.get(`direct-served:${id}`)
).toBeGreaterThan(0)
},
5000,
100
)
releaseDataResponses(`fill:${id}`)
const $ = await rendering
expect($('#direct').text()).not.toBe(initial.value)
expect($('#direct').text()).toBe($('#outer').text())
expect($('#direct').text()).toBe(initial.value)
expect($('#outer').text()).not.toBe(initial.value)
expect($('#outer').text()).not.toBe('')
expect(dataRequestCountsByKey.get(`fill:${id}`)).toBe(2)
......@@ -458,8 +468,8 @@ describe('use-cache-swr', () => {
// by the initial cold-fill set from the first fetch.
outputIndex = next.cliOutput.length
// This request should trigger SWR: the handler returns the stale entry,
// the framework serves it to the client, and kicks off a background regen.
// This request should trigger SWR: the handler returns the stale entry, the
// framework serves it to the client, and kicks off a background regen.
await browser.refresh()
const afterStale = await browser.elementById('outer-data').text()
......@@ -593,9 +603,9 @@ describe('use-cache-swr', () => {
// Reset output index to capture only the SWR-related logs.
outputIndex = next.cliOutput.length
// This triggers SWR: stale outer is served, background regen starts.
// During regen, the outer fn re-executes and calls the inner "use cache".
// The inner cache's get() should receive the page's implicit tags.
// This triggers SWR: stale outer is served, background regen starts. During
// regen, the outer fn re-executes and calls the inner "use cache". The
// inner cache's get() should receive the page's implicit tags.
await browser.refresh()
// Wait for the background regen to complete.
......@@ -604,8 +614,8 @@ describe('use-cache-swr', () => {
const cliOutput = next.cliOutput.slice(outputIndex)
// The inner cache's get() during SWR regen should include the page's
// implicit tags (softTags), not an empty array. We identify the inner
// cache by its "inner" sentinel argument in the key.
// implicit tags (softTags), not an empty array. We identify the inner cache
// by its "inner" sentinel argument in the key.
expect(cliOutput).toMatch(/PersistentCacheHandler::get.*"inner".*_N_T_\//)
})
......
......@@ -67,7 +67,7 @@ describe('use-cache-dedupe-prerender', () => {
describe('direct and nested calls during static prerendering', () => {
const fixture = setupFixture('context')
it('currently times out a nested cache when a direct short-lived warm-cache call starts the lookup first', async () => {
it('includes the long-lived outer cache in static HTML when the direct short-lived call starts the lookup first', async () => {
const { next, dataService } = fixture
// Pause the direct call's handler `get()` until `Outer()` calls the same
// short-lived cached function.
......@@ -77,13 +77,19 @@ describe('use-cache-dedupe-prerender', () => {
await dataService.waitForRequest('join-ready')
dataService.release('lookup:short-lived:shared')
const result = await building
// The nested call shares the direct call's hanging promise. Its cache
// entry cannot complete, so the build reports a prerender timeout.
expect(result.exitCode).toBe(1)
expect(next.cliOutput).toContain(
'function took too long during prerendering'
// `Outer()` must complete even though the direct call returns a hanging
// promise. Its cache lifetime allows the result in the static HTML.
expect(result.exitCode).toBe(0)
expect(next.cliOutput).not.toContain(
'Unexpected cache miss after cache warming phase during prerendering'
)
expect(next.cliOutput).toContain('Error occurred prerendering page "/"')
await next.start({ skipBuild: true })
const html = await next.render('/')
const [shell] = html.split('<!-- PPR_BOUNDARY_SENTINEL -->')
const $ = load(shell)
expect($('#outer').text()).toBe('short-lived shared')
expect($('#short-lived').length).toBe(0)
expect($('#short-pending').length).toBe(1)
} finally {
dataService.releaseAll()
await building
......@@ -94,7 +100,7 @@ describe('use-cache-dedupe-prerender', () => {
describe('concurrent prerenders sharing the same short-lived cache', () => {
const fixture = setupFixture('lifetime')
it('currently omits cached work in a second prerender after the first prerender finishes', async () => {
it('continues cached work in a second prerender after the first prerender finishes, when both share a pending short-lived cache call', async () => {
const { next, dataService } = fixture
// Keep the producer's `get()` pending until the consumer starts its
// calls. Keep `readIndependent()` pending until the producer's `after()`
......@@ -106,8 +112,8 @@ describe('use-cache-dedupe-prerender', () => {
await dataService.waitForRequest('join-ready')
dataService.release('lookup:short-lived:shared')
await dataService.waitForRequest('producer-finished')
// Resolve the independent read after the producer's `after()` callback.
// The consumer currently skips `readCachedMessage()`.
// The consumer must still complete its cached message after the
// producer's `after()` callback.
dataService.release('independent', 'independent value')
const result = await building
expect(result.exitCode).toBe(0)
......@@ -118,9 +124,9 @@ describe('use-cache-dedupe-prerender', () => {
const html = await next.render('/consumer')
const [shell] = html.split('<!-- PPR_BOUNDARY_SENTINEL -->')
const $ = load(shell)
expect($('#cached-message').text()).toBe('')
expect($('#consumer-pending').length).toBe(1)
expect(buildRequests).not.toContain('cached-message')
expect($('#cached-message').text()).toBe('message: independent value')
expect($('#consumer-pending').length).toBe(0)
expect(buildRequests).toContain('cached-message')
} finally {
dataService.releaseAll()
await building
......
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