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

Fix custom cache handlers missing on initial requests (#99372)

Startup preloading can initialize the built-in handler map before a
configured handler finishes loading. A request that reaches `'use
cache'` during the import can use the built-in handler instead of the
configured handler. Next.js now waits for registration to finish before
rendering that request. The server, route module, and export helper
share the registration promise.

Regression tests verify that the first request uses the configured
handler with startup preloading enabled. The affected fixtures no longer
disable preloading. Preloading also logs failed handler imports without
an unhandled rejection.
parent b9adf551
...@@ -6,6 +6,7 @@ import { interopDefault } from '../../lib/interop-default' ...@@ -6,6 +6,7 @@ import { interopDefault } from '../../lib/interop-default'
import { formatDynamicImportPath } from '../../lib/format-dynamic-import-path' import { formatDynamicImportPath } from '../../lib/format-dynamic-import-path'
import { import {
initializeCacheHandlers, initializeCacheHandlers,
registerCustomCacheHandlers,
setCacheHandler, setCacheHandler,
} from '../../server/use-cache/handlers' } from '../../server/use-cache/handlers'
...@@ -38,7 +39,9 @@ export async function createIncrementalCache({ ...@@ -38,7 +39,9 @@ export async function createIncrementalCache({
) )
} }
if (cacheHandlers && initializeCacheHandlers(cacheMaxMemorySize)) { if (cacheHandlers) {
initializeCacheHandlers(cacheMaxMemorySize)
await registerCustomCacheHandlers(async () => {
for (const [kind, handler] of Object.entries(cacheHandlers)) { for (const [kind, handler] of Object.entries(cacheHandlers)) {
if (!handler) continue if (!handler) continue
...@@ -51,6 +54,7 @@ export async function createIncrementalCache({ ...@@ -51,6 +54,7 @@ export async function createIncrementalCache({
) )
) )
} }
})
} }
let previewProps = { let previewProps = {
......
...@@ -127,7 +127,11 @@ import { RouteKind } from './route-kind' ...@@ -127,7 +127,11 @@ import { RouteKind } from './route-kind'
import { InvariantError } from '../shared/lib/invariant-error' import { InvariantError } from '../shared/lib/invariant-error'
import { AwaiterOnce } from './after/awaiter' import { AwaiterOnce } from './after/awaiter'
import { AsyncCallbackSet } from './lib/async-callback-set' import { AsyncCallbackSet } from './lib/async-callback-set'
import { initializeCacheHandlers, setCacheHandler } from './use-cache/handlers' import {
initializeCacheHandlers,
registerCustomCacheHandlers,
setCacheHandler,
} from './use-cache/handlers'
import type { UnwrapPromise } from '../lib/coalesced-function' import type { UnwrapPromise } from '../lib/coalesced-function'
import { populateStaticEnv } from '../lib/static-env' import { populateStaticEnv } from '../lib/static-env'
import { NodeModuleLoader } from './lib/module-loader/node-module-loader' import { NodeModuleLoader } from './lib/module-loader/node-module-loader'
...@@ -251,7 +255,10 @@ export default class NextNodeServer extends BaseServer< ...@@ -251,7 +255,10 @@ export default class NextNodeServer extends BaseServer<
!this.minimalMode && !this.minimalMode &&
this.nextConfig.experimental.preloadEntriesOnStart this.nextConfig.experimental.preloadEntriesOnStart
) { ) {
this.unstable_preloadEntries() // Preloading may join a failing registration started by a request.
void this.unstable_preloadEntries().catch((err) => {
Log.error('Failed to preload entries:', err)
})
} }
if (!options.dev) { if (!options.dev) {
...@@ -413,10 +420,8 @@ export default class NextNodeServer extends BaseServer< ...@@ -413,10 +420,8 @@ export default class NextNodeServer extends BaseServer<
const { cacheMaxMemorySize, cacheHandlers } = this.nextConfig const { cacheMaxMemorySize, cacheHandlers } = this.nextConfig
if (!cacheHandlers) return if (!cacheHandlers) return
// If we've already initialized the cache handlers interface, don't do it initializeCacheHandlers(cacheMaxMemorySize)
// again. await registerCustomCacheHandlers(async () => {
if (!initializeCacheHandlers(cacheMaxMemorySize)) return
for (const [kind, handler] of Object.entries(cacheHandlers)) { for (const [kind, handler] of Object.entries(cacheHandlers)) {
if (!handler) continue if (!handler) continue
...@@ -429,6 +434,7 @@ export default class NextNodeServer extends BaseServer< ...@@ -429,6 +434,7 @@ export default class NextNodeServer extends BaseServer<
) )
) )
} }
})
} }
protected async getIncrementalCache({ protected async getIncrementalCache({
......
...@@ -55,7 +55,11 @@ import { patchSetHeaderWithCookieSupport } from '../lib/patch-set-header' ...@@ -55,7 +55,11 @@ import { patchSetHeaderWithCookieSupport } from '../lib/patch-set-header'
import { normalizePagePath } from '../../shared/lib/page-path/normalize-page-path' import { normalizePagePath } from '../../shared/lib/page-path/normalize-page-path'
import { isStaticMetadataRoute } from '../../lib/metadata/is-metadata-route' import { isStaticMetadataRoute } from '../../lib/metadata/is-metadata-route'
import { IncrementalCache } from '../lib/incremental-cache' import { IncrementalCache } from '../lib/incremental-cache'
import { initializeCacheHandlers, setCacheHandler } from '../use-cache/handlers' import {
initializeCacheHandlers,
registerCustomCacheHandlers,
setCacheHandler,
} from '../use-cache/handlers'
import { interopDefault } from '../app-render/interop-default' import { interopDefault } from '../app-render/interop-default'
import { RouteKind } from '../route-kind' import { RouteKind } from '../route-kind'
import type { BaseNextRequest } from '../base-http' import type { BaseNextRequest } from '../base-http'
...@@ -453,10 +457,8 @@ export abstract class RouteModule< ...@@ -453,10 +457,8 @@ export abstract class RouteModule<
const { cacheMaxMemorySize, cacheHandlers } = nextConfig const { cacheMaxMemorySize, cacheHandlers } = nextConfig
if (!cacheHandlers) return if (!cacheHandlers) return
// If we've already initialized the cache handlers interface, don't do it initializeCacheHandlers(cacheMaxMemorySize)
// again. await registerCustomCacheHandlers(async () => {
if (!initializeCacheHandlers(cacheMaxMemorySize)) return
for (const [kind, handler] of Object.entries(cacheHandlers)) { for (const [kind, handler] of Object.entries(cacheHandlers)) {
if (!handler) continue if (!handler) continue
...@@ -482,6 +484,7 @@ export abstract class RouteModule< ...@@ -482,6 +484,7 @@ export abstract class RouteModule<
) )
) )
} }
})
} }
} }
......
...@@ -14,6 +14,9 @@ const debug = process.env.NEXT_PRIVATE_DEBUG_CACHE ...@@ -14,6 +14,9 @@ const debug = process.env.NEXT_PRIVATE_DEBUG_CACHE
const handlersSymbol = Symbol.for('@next/cache-handlers') const handlersSymbol = Symbol.for('@next/cache-handlers')
const handlersMapSymbol = Symbol.for('@next/cache-handlers-map') const handlersMapSymbol = Symbol.for('@next/cache-handlers-map')
const handlersSetSymbol = Symbol.for('@next/cache-handlers-set') const handlersSetSymbol = Symbol.for('@next/cache-handlers-set')
const customCacheHandlersRegistrationSymbol = Symbol.for(
'@next/custom-cache-handlers-registration'
)
const privateHandlerSymbol = Symbol.for('@next/cache-handlers-private') const privateHandlerSymbol = Symbol.for('@next/cache-handlers-private')
const builtInHandlersSymbol = Symbol.for('@next/cache-handlers-built-in') const builtInHandlersSymbol = Symbol.for('@next/cache-handlers-built-in')
const devFrontHandlersSymbol = Symbol.for('@next/cache-handlers-dev-fronts') const devFrontHandlersSymbol = Symbol.for('@next/cache-handlers-dev-fronts')
...@@ -42,6 +45,7 @@ const reference: typeof globalThis & { ...@@ -42,6 +45,7 @@ const reference: typeof globalThis & {
} }
[handlersMapSymbol]?: Map<string, CacheHandler> [handlersMapSymbol]?: Map<string, CacheHandler>
[handlersSetSymbol]?: Set<CacheHandler> [handlersSetSymbol]?: Set<CacheHandler>
[customCacheHandlersRegistrationSymbol]?: Promise<void>
[builtInHandlersSymbol]?: Set<CacheHandler> [builtInHandlersSymbol]?: Set<CacheHandler>
// DEV-only // DEV-only
[privateHandlerSymbol]?: CacheHandler [privateHandlerSymbol]?: CacheHandler
...@@ -54,13 +58,12 @@ const reference: typeof globalThis & { ...@@ -54,13 +58,12 @@ const reference: typeof globalThis & {
* Initialize the cache handlers. * Initialize the cache handlers.
* @param cacheMaxMemorySize - The maximum memory size of the cache in bytes, if * @param cacheMaxMemorySize - The maximum memory size of the cache in bytes, if
* not provided, the default memory size will be used. * not provided, the default memory size will be used.
* @returns `true` if the cache handlers were initialized, `false` if they were already initialized.
*/ */
export function initializeCacheHandlers(cacheMaxMemorySize: number): boolean { export function initializeCacheHandlers(cacheMaxMemorySize: number): void {
// If the cache handlers have already been initialized, don't do it again. // If the cache handlers have already been initialized, don't do it again.
if (reference[handlersMapSymbol]) { if (reference[handlersMapSymbol]) {
debug?.('cache handlers already initialized') debug?.('cache handlers already initialized')
return false return
} }
debug?.('initializing cache handlers') debug?.('initializing cache handlers')
...@@ -136,8 +139,18 @@ export function initializeCacheHandlers(cacheMaxMemorySize: number): boolean { ...@@ -136,8 +139,18 @@ export function initializeCacheHandlers(cacheMaxMemorySize: number): boolean {
reference[devFrontHandlersSymbol] = new Map() reference[devFrontHandlersSymbol] = new Map()
reference[devTieredHandlersSymbol] = new Map() reference[devTieredHandlersSymbol] = new Map()
} }
}
export function registerCustomCacheHandlers(
register: () => Promise<void>
): Promise<void> {
let pendingPromise = reference[customCacheHandlersRegistrationSymbol]
if (!pendingPromise) {
pendingPromise = register()
reference[customCacheHandlersRegistrationSymbol] = pendingPromise
}
return true return pendingPromise
} }
/** /**
......
...@@ -5,14 +5,6 @@ const nextConfig: NextConfig = { ...@@ -5,14 +5,6 @@ const nextConfig: NextConfig = {
default: require.resolve('./handler.js'), 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,
}, },
} }
......
import { cacheTag } from 'next/cache'
import { connection } from 'next/server'
async function getData() {
'use cache'
cacheTag('registration')
return 'registration'
}
export default async function Page() {
await connection()
return <p id="data">{await getData()}</p>
}
import handler from './handler.js'
if (process.env.NEXT_TEST_FAIL_CUSTOM_CACHE_HANDLER === '1') {
throw new Error('test custom cache handler failed to load')
}
// Widen the registration window for the first-request race test.
await new Promise((resolve) => setTimeout(resolve, 500))
export default handler
...@@ -4,17 +4,7 @@ ...@@ -4,17 +4,7 @@
const nextConfig = { const nextConfig = {
cacheComponents: true, cacheComponents: true,
cacheHandlers: { cacheHandlers: {
default: require.resolve('./handler.js'), default: require.resolve('./handler-loader.mjs'),
},
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,
}, },
} }
......
...@@ -18,6 +18,22 @@ describe('use-cache-custom-handler', () => { ...@@ -18,6 +18,22 @@ describe('use-cache-custom-handler', () => {
outputIndex = next.cliOutput.length outputIndex = next.cliOutput.length
}) })
it('uses the custom handler for the first request during startup', async () => {
const $ = await next.render$('/registration')
expect($('#data').text()).toBe('registration')
await retry(async () => {
const writes: CacheWrite[] = await next
.fetch('/cache-writes')
.then((response) => response.json())
expect(writes).toContainEqual(
expect.objectContaining({
tags: expect.arrayContaining(['registration']),
})
)
}, 3000)
})
it('should use a modern custom cache handler if provided', async () => { it('should use a modern custom cache handler if provided', async () => {
const browser = await next.browser(`/`) const browser = await next.browser(`/`)
const initialData = await browser.elementById('data').text() const initialData = await browser.elementById('data').text()
...@@ -188,4 +204,25 @@ describe('use-cache-custom-handler', () => { ...@@ -188,4 +204,25 @@ describe('use-cache-custom-handler', () => {
) )
}) })
}) })
if (isNextStart) {
it('handles a failed handler preload without an unhandled rejection', async () => {
await next.stop()
await next.start({
skipBuild: true,
env: { NEXT_TEST_FAIL_CUSTOM_CACHE_HANDLER: '1' },
})
await retry(() => {
expect(next.cliOutput).toContain('Failed to preload entries:')
expect(next.cliOutput).toContain(
'test custom cache handler failed to load'
)
})
const response = await next.fetch('/registration')
expect(response.status).toBe(500)
expect(next.cliOutput).not.toContain('unhandledRejection:')
})
}
}) })
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