Ensure global cache handlers are used properly (vercel#74626)

ijjk · web-flow · commit 8ffa6c74b1f3 · 2025-01-08T06:51:30.000Z
Currently any cache handlers configured under the global symbol are
overridden by the default built-in cache handle unexpectedly. The
default built-in cache handler should only be used if no user configured
one is available and no global symbol provided one is available.

This also fixes `expireTags` not being called on configured cache
handlers at all due to that part not being wired up.

Regression tests for the above are also added to ensure this is behaving
as expected.
diff --git a/packages/next/src/build/static-paths/app.ts b/packages/next/src/build/static-paths/app.ts
@@ -2,24 +2,21 @@ import type { ParamValue, Params } from '../../server/request/params'
 import type { AppPageModule } from '../../server/route-modules/app-page/module'
 import type { AppSegment } from '../segment-config/app/app-segments'
 import type { StaticPathsResult } from './types'
-import type { CacheHandler } from '../../server/lib/incremental-cache'
 
 import path from 'path'
 import { AfterRunner } from '../../server/after/run-with-after'
 import { createWorkStore } from '../../server/async-storage/work-store'
 import { FallbackMode } from '../../lib/fallback'
-import { formatDynamicImportPath } from '../../lib/format-dynamic-import-path'
 import { getRouteMatcher } from '../../shared/lib/router/utils/route-matcher'
 import {
   getRouteRegex,
   type RouteRegex,
 } from '../../shared/lib/router/utils/route-regex'
-import { IncrementalCache } from '../../server/lib/incremental-cache'
-import { interopDefault } from '../../lib/interop-default'
-import { nodeFs } from '../../server/lib/node-fs-methods'
+import type { IncrementalCache } from '../../server/lib/incremental-cache'
 import { normalizePathname, encodeParam } from './utils'
-import * as ciEnvironment from '../../server/ci-info'
 import escapePathDelimiters from '../../shared/lib/router/utils/escape-path-delimiters'
+import { createIncrementalCache } from '../../export/helpers/create-incremental-cache'
+import type { NextConfigComplete } from '../../server/config-shared'
 
 /**
  * Compares two parameters to see if they're equal.
@@ -263,6 +260,7 @@ export async function buildAppStaticPaths({
   cacheHandler,
   cacheLifeProfiles,
   requestHeaders,
+  cacheHandlers,
   maxMemoryCacheSize,
   fetchCacheKeyPrefix,
   nextConfigOutput,
@@ -280,6 +278,7 @@ export async function buildAppStaticPaths({
   isrFlushToDisk?: boolean
   fetchCacheKeyPrefix?: string
   cacheHandler?: string
+  cacheHandlers?: NextConfigComplete['experimental']['cacheHandlers']
   cacheLifeProfiles?: {
     [profile: string]: import('../../server/use-cache/cache-life').CacheLife
   }
@@ -302,33 +301,16 @@ export async function buildAppStaticPaths({
 
   ComponentMod.patchFetch()
 
-  let CurCacheHandler: typeof CacheHandler | undefined
-  if (cacheHandler) {
-    CurCacheHandler = interopDefault(
-      await import(formatDynamicImportPath(dir, cacheHandler)).then(
-        (mod) => mod.default || mod
-      )
-    )
-  }
-
-  const incrementalCache = new IncrementalCache({
-    fs: nodeFs,
-    dev: true,
+  const incrementalCache = await createIncrementalCache({
+    dir,
+    distDir,
     dynamicIO,
-    flushToDisk: isrFlushToDisk,
-    serverDistDir: path.join(distDir, 'server'),
-    fetchCacheKeyPrefix,
-    maxMemoryCacheSize,
-    getPrerenderManifest: () => ({
-      version: -1 as any, // letting us know this doesn't conform to spec
-      routes: {},
-      dynamicRoutes: {},
-      notFoundRoutes: [],
-      preview: null as any, // `preview` is special case read in next-dev-server
-    }),
-    CurCacheHandler,
+    cacheHandler,
+    cacheHandlers,
     requestHeaders,
-    minimalMode: ciEnvironment.hasNextSupport,
+    fetchCacheKeyPrefix,
+    flushToDisk: isrFlushToDisk,
+    cacheMaxMemorySize: maxMemoryCacheSize,
   })
 
   const regex = getRouteRegex(page)
diff --git a/packages/next/src/build/templates/edge-ssr-app.ts b/packages/next/src/build/templates/edge-ssr-app.ts
@@ -13,14 +13,24 @@ import type { NextConfigComplete } from '../../server/config-shared'
 import { PAGE_TYPES } from '../../lib/page-types'
 import { setReferenceManifestsSingleton } from '../../server/app-render/encryption-utils'
 import { createServerModuleMap } from '../../server/app-render/action-utils'
+import {
+  cacheHandlerGlobal,
+  cacheHandlersSymbol,
+} from '../../server/use-cache/constants'
 
 declare const incrementalCacheHandler: any
 // OPTIONAL_IMPORT:incrementalCacheHandler
 
 const cacheHandlers = {}
 
-if (!(globalThis as any).__nextCacheHandlers) {
-  ;(globalThis as any).__nextCacheHandlers = cacheHandlers
+if (!cacheHandlerGlobal.__nextCacheHandlers) {
+  cacheHandlerGlobal.__nextCacheHandlers = cacheHandlers
+
+  if (!cacheHandlerGlobal.__nextCacheHandlers.default) {
+    cacheHandlerGlobal.__nextCacheHandlers.default =
+      cacheHandlerGlobal[cacheHandlersSymbol]?.DefaultCache ||
+      cacheHandlerGlobal.__nextCacheHandlers.__nextDefault
+  }
 }
 
 const Document: DocumentType = null!
diff --git a/packages/next/src/build/templates/edge-ssr.ts b/packages/next/src/build/templates/edge-ssr.ts
@@ -23,6 +23,10 @@ import type { RequestData } from '../../server/web/types'
 import type { BuildManifest } from '../../server/get-page-files'
 import type { NextConfigComplete } from '../../server/config-shared'
 import type { PAGE_TYPES } from '../../lib/page-types'
+import {
+  cacheHandlerGlobal,
+  cacheHandlersSymbol,
+} from '../../server/use-cache/constants'
 
 // injected by the loader afterwards.
 declare const pagesType: PAGE_TYPES
@@ -42,8 +46,14 @@ declare const user500RouteModuleOptions: any
 
 const cacheHandlers = {}
 
-if (!(globalThis as any).__nextCacheHandlers) {
-  ;(globalThis as any).__nextCacheHandlers = cacheHandlers
+if (!cacheHandlerGlobal.__nextCacheHandlers) {
+  cacheHandlerGlobal.__nextCacheHandlers = cacheHandlers
+
+  if (!cacheHandlerGlobal.__nextCacheHandlers.default) {
+    cacheHandlerGlobal.__nextCacheHandlers.default =
+      cacheHandlerGlobal[cacheHandlersSymbol]?.DefaultCache ||
+      cacheHandlerGlobal.__nextCacheHandlers.__nextDefault
+  }
 }
 
 const pageMod = {
diff --git a/packages/next/src/build/webpack/loaders/next-edge-app-route-loader/index.ts b/packages/next/src/build/webpack/loaders/next-edge-app-route-loader/index.ts
@@ -36,7 +36,7 @@ const EdgeAppRouteLoader: webpack.LoaderDefinitionFunction<EdgeAppRouteLoaderQue
     const cacheHandlers = JSON.parse(cacheHandlersStringified || '{}')
 
     if (!cacheHandlers.default) {
-      cacheHandlers.default = require.resolve(
+      cacheHandlers.__nextDefault = require.resolve(
         '../../../../server/lib/cache-handlers/default'
       )
     }
diff --git a/packages/next/src/build/webpack/loaders/next-edge-ssr-loader/index.ts b/packages/next/src/build/webpack/loaders/next-edge-ssr-loader/index.ts
@@ -85,7 +85,7 @@ const edgeSSRLoader: webpack.LoaderDefinitionFunction<EdgeSSRLoaderQuery> =
     const cacheHandlers = JSON.parse(cacheHandlersStringified || '{}')
 
     if (!cacheHandlers.default) {
-      cacheHandlers.default = require.resolve(
+      cacheHandlers.__nextDefault = require.resolve(
         '../../../../server/lib/cache-handlers/default'
       )
     }
diff --git a/packages/next/src/export/helpers/create-incremental-cache.ts b/packages/next/src/export/helpers/create-incremental-cache.ts
@@ -4,6 +4,8 @@ import { hasNextSupport } from '../../server/ci-info'
 import { nodeFs } from '../../server/lib/node-fs-methods'
 import { interopDefault } from '../../lib/interop-default'
 import { formatDynamicImportPath } from '../../lib/format-dynamic-import-path'
+import { cacheHandlerGlobal } from '../../server/use-cache/constants'
+import DefaultCacheHandler from '../../server/lib/cache-handlers/default'
 
 export async function createIncrementalCache({
   cacheHandler,
@@ -14,6 +16,7 @@ export async function createIncrementalCache({
   dir,
   flushToDisk,
   cacheHandlers,
+  requestHeaders,
 }: {
   dynamicIO: boolean
   cacheHandler?: string
@@ -22,6 +25,7 @@ export async function createIncrementalCache({
   distDir: string
   dir: string
   flushToDisk?: boolean
+  requestHeaders?: Record<string, string | string[] | undefined>
   cacheHandlers?: Record<string, string | undefined>
 }) {
   // Custom cache handler overrides.
@@ -34,8 +38,8 @@ export async function createIncrementalCache({
     )
   }
 
-  if (!(globalThis as any).__nextCacheHandlers && cacheHandlers) {
-    ;(globalThis as any).__nextCacheHandlers = {}
+  if (!cacheHandlerGlobal.__nextCacheHandlers && cacheHandlers) {
+    cacheHandlerGlobal.__nextCacheHandlers = {}
 
     for (const key of Object.keys(cacheHandlers)) {
       if (cacheHandlers[key]) {
@@ -46,11 +50,15 @@ export async function createIncrementalCache({
         )
       }
     }
+
+    if (!cacheHandlers.default) {
+      cacheHandlerGlobal.__nextCacheHandlers.default = DefaultCacheHandler
+    }
   }
 
   const incrementalCache = new IncrementalCache({
     dev: false,
-    requestHeaders: {},
+    requestHeaders: requestHeaders || {},
     flushToDisk,
     dynamicIO,
     maxMemoryCacheSize: cacheMaxMemorySize,
diff --git a/packages/next/src/server/base-server.ts b/packages/next/src/server/base-server.ts
@@ -1359,7 +1359,7 @@ export default abstract class Server<
           ) || []
 
         for (const handler of Object.values(_globalThis.__nextCacheHandlers)) {
-          if (typeof handler.receiveExpiredTags === 'function') {
+          if (typeof handler?.receiveExpiredTags === 'function') {
             await handler.receiveExpiredTags(...expiredTags)
           }
         }
diff --git a/packages/next/src/server/dev/next-dev-server.ts b/packages/next/src/server/dev/next-dev-server.ts
@@ -770,6 +770,7 @@ export default class DevServer extends Server {
           isAppPath,
           requestHeaders,
           cacheHandler: this.nextConfig.cacheHandler,
+          cacheHandlers: this.nextConfig.experimental.cacheHandlers,
           cacheLifeProfiles: this.nextConfig.experimental.cacheLife,
           fetchCacheKeyPrefix: this.nextConfig.experimental.fetchCacheKeyPrefix,
           isrFlushToDisk: this.nextConfig.experimental.isrFlushToDisk,
diff --git a/packages/next/src/server/dev/static-paths-worker.ts b/packages/next/src/server/dev/static-paths-worker.ts
@@ -18,6 +18,7 @@ import { InvariantError } from '../../shared/lib/invariant-error'
 import { collectRootParamKeys } from '../../build/segment-config/app/collect-root-param-keys'
 import { buildAppStaticPaths } from '../../build/static-paths/app'
 import { buildPagesStaticPaths } from '../../build/static-paths/pages'
+import { createIncrementalCache } from '../../export/helpers/create-incremental-cache'
 
 type RuntimeConfig = {
   pprConfig: ExperimentalPPRConfig | undefined
@@ -45,6 +46,7 @@ export async function loadStaticPaths({
   maxMemoryCacheSize,
   requestHeaders,
   cacheHandler,
+  cacheHandlers,
   cacheLifeProfiles,
   nextConfigOutput,
   buildId,
@@ -65,6 +67,7 @@ export async function loadStaticPaths({
   maxMemoryCacheSize?: number
   requestHeaders: IncrementalCache['requestHeaders']
   cacheHandler?: string
+  cacheHandlers?: NextConfigComplete['experimental']['cacheHandlers']
   cacheLifeProfiles?: {
     [profile: string]: import('../../server/use-cache/cache-life').CacheLife
   }
@@ -73,6 +76,20 @@ export async function loadStaticPaths({
   authInterrupts: boolean
   sriEnabled: boolean
 }): Promise<Partial<StaticPathsResult>> {
+  // this needs to be initialized before loadComponents otherwise
+  // "use cache" could be missing it's cache handlers
+  await createIncrementalCache({
+    dir,
+    distDir,
+    dynamicIO: false,
+    cacheHandler,
+    cacheHandlers,
+    requestHeaders,
+    fetchCacheKeyPrefix,
+    flushToDisk: isrFlushToDisk,
+    cacheMaxMemorySize: maxMemoryCacheSize,
+  })
+
   // update work memory runtime-config
   require('../../shared/lib/runtime-config.external').setConfig(config)
   setHttpClientAndAgentOptions({
diff --git a/packages/next/src/server/lib/cache-handlers/default.ts b/packages/next/src/server/lib/cache-handlers/default.ts
@@ -103,7 +103,7 @@ const DefaultCacheHandler: CacheHandler = {
     }
   },
 
-  async unstable_expireTags(...tags) {
+  async expireTags(...tags) {
     for (const tag of tags) {
       if (!tagsManifest.items[tag]) {
         tagsManifest.items[tag] = {}
@@ -113,8 +113,11 @@ const DefaultCacheHandler: CacheHandler = {
     }
   },
 
+  // This is only meant to invalidate in memory tags
+  // not meant to be propagated like expireTags would
+  // in multi-instance scenario
   async receiveExpiredTags(...tags): Promise<void> {
-    return this.unstable_expireTags(...tags)
+    return this.expireTags(...tags)
   },
 }
 
diff --git a/packages/next/src/server/lib/cache-handlers/types.ts b/packages/next/src/server/lib/cache-handlers/types.ts
@@ -44,9 +44,9 @@ export interface CacheHandler {
 
   set(cacheKey: string, entry: Promise<CacheEntry>): Promise<void>
 
-  // This is called when unstable_expireTags('') is called
+  // This is called when expireTags('') is called
   // and should update tags manifest accordingly
-  unstable_expireTags(...tags: string[]): Promise<void>
+  expireTags(...tags: string[]): Promise<void>
 
   // This is called when an action request sends
   // NEXT_CACHE_REVALIDATED_TAGS_HEADER and tells
diff --git a/packages/next/src/server/lib/incremental-cache/index.ts b/packages/next/src/server/lib/incremental-cache/index.ts
@@ -249,7 +249,22 @@ export class IncrementalCache implements IncrementalCacheType {
   }
 
   async revalidateTag(tags: string | string[]): Promise<void> {
-    return this.cacheHandler?.revalidateTag?.(tags)
+    const _globalThis: typeof globalThis & {
+      __nextCacheHandlers?: Record<
+        string,
+        import('../cache-handlers/types').CacheHandler
+      >
+    } = globalThis
+
+    return Promise.all([
+      // call expireTags on all configured cache handlers
+      Object.values(_globalThis.__nextCacheHandlers || {}).map(
+        (cacheHandler) =>
+          typeof cacheHandler.expireTags === 'function' &&
+          cacheHandler.expireTags(...(Array.isArray(tags) ? tags : [tags]))
+      ),
+      this.cacheHandler?.revalidateTag?.(tags),
+    ]).then(() => {})
   }
 
   // x-ref: https://github.com/facebook/react/blob/2655c9354d8e1c54ba888444220f63e836925caa/packages/react/src/ReactFetch.js#L23
diff --git a/packages/next/src/server/next-server.ts b/packages/next/src/server/next-server.ts
@@ -109,6 +109,7 @@ import { InvariantError } from '../shared/lib/invariant-error'
 import { AwaiterOnce } from './after/awaiter'
 import { AsyncCallbackSet } from './lib/async-callback-set'
 import DefaultCacheHandler from './lib/cache-handlers/default'
+import { cacheHandlerGlobal, cacheHandlersSymbol } from './use-cache/constants'
 
 export * from './base-server'
 
@@ -379,8 +380,8 @@ export default class NextNodeServer extends BaseServer<
   protected async loadCustomCacheHandlers() {
     const { cacheHandlers } = this.nextConfig.experimental
 
-    if (!(globalThis as any).__nextCacheHandlers && cacheHandlers) {
-      ;(globalThis as any).__nextCacheHandlers = {}
+    if (!cacheHandlerGlobal.__nextCacheHandlers && cacheHandlers) {
+      cacheHandlerGlobal.__nextCacheHandlers = {}
 
       for (const key of Object.keys(cacheHandlers)) {
         if (cacheHandlers[key]) {
@@ -393,7 +394,9 @@ export default class NextNodeServer extends BaseServer<
       }
 
       if (!cacheHandlers.default) {
-        ;(globalThis as any).__nextCacheHandlers.default = DefaultCacheHandler
+        cacheHandlerGlobal.__nextCacheHandlers.default =
+          cacheHandlerGlobal[cacheHandlersSymbol]?.DefaultCache ||
+          DefaultCacheHandler
       }
     }
   }
diff --git a/packages/next/src/server/use-cache/constants.ts b/packages/next/src/server/use-cache/constants.ts
@@ -0,0 +1,13 @@
+import type { CacheHandler } from '../lib/cache-handlers/types'
+
+// If the expire time is less than .
+export const DYNAMIC_EXPIRE = 300
+
+export const cacheHandlersSymbol = Symbol.for('@next/cache-handlers')
+export const cacheHandlerGlobal: typeof globalThis & {
+  [cacheHandlersSymbol]?: {
+    RemoteCache?: CacheHandler
+    DefaultCache?: CacheHandler
+  }
+  __nextCacheHandlers?: Record<string, CacheHandler>
+} = globalThis
diff --git a/packages/next/src/server/use-cache/use-cache-wrapper.ts b/packages/next/src/server/use-cache/use-cache-wrapper.ts
diff --git a/test/production/app-dir/dynamic-io-cache-handlers/app/layout.tsx b/test/production/app-dir/dynamic-io-cache-handlers/app/layout.tsx
diff --git a/test/production/app-dir/dynamic-io-cache-handlers/app/page.tsx b/test/production/app-dir/dynamic-io-cache-handlers/app/page.tsx
diff --git a/test/production/app-dir/dynamic-io-cache-handlers/app/revalidate-tag/route.ts b/test/production/app-dir/dynamic-io-cache-handlers/app/revalidate-tag/route.ts
diff --git a/test/production/app-dir/dynamic-io-cache-handlers/dynamic-io-cache-handlers.test.ts b/test/production/app-dir/dynamic-io-cache-handlers/dynamic-io-cache-handlers.test.ts
diff --git a/test/production/app-dir/dynamic-io-cache-handlers/next.config.js b/test/production/app-dir/dynamic-io-cache-handlers/next.config.js

Original file line number	Diff line number	Diff line change
`@@ -36,7 +36,7 @@ const EdgeAppRouteLoader: webpack.LoaderDefinitionFunction<EdgeAppRouteLoaderQue`
`36`	`36`	`const cacheHandlers = JSON.parse(cacheHandlersStringified \|\| '{}')`
`37`	`37`
`38`	`38`	`if (!cacheHandlers.default) {`
`39`		`- cacheHandlers.default = require.resolve(`
	`39`	`+ cacheHandlers.__nextDefault = require.resolve(`
`40`	`40`	`'../../../../server/lib/cache-handlers/default'`
`41`	`41`	`)`
`42`	`42`	`}`
Original file line number	Diff line number	Diff line change
`@@ -85,7 +85,7 @@ const edgeSSRLoader: webpack.LoaderDefinitionFunction<EdgeSSRLoaderQuery> =`
`85`	`85`	`const cacheHandlers = JSON.parse(cacheHandlersStringified \|\| '{}')`
`86`	`86`
`87`	`87`	`if (!cacheHandlers.default) {`
`88`		`- cacheHandlers.default = require.resolve(`
	`88`	`+ cacheHandlers.__nextDefault = require.resolve(`
`89`	`89`	`'../../../../server/lib/cache-handlers/default'`
`90`	`90`	`)`
`91`	`91`	`}`
Original file line number	Diff line number	Diff line change
`@@ -1359,7 +1359,7 @@ export default abstract class Server<`
`1359`	`1359`	`) \|\| []`
`1360`	`1360`
`1361`	`1361`	`for (const handler of Object.values(_globalThis.__nextCacheHandlers)) {`
`1362`		`- if (typeof handler.receiveExpiredTags === 'function') {`
	`1362`	`+ if (typeof handler?.receiveExpiredTags === 'function') {`
`1363`	`1363`	`await handler.receiveExpiredTags(...expiredTags)`
`1364`	`1364`	`}`
`1365`	`1365`	`}`
Original file line number	Diff line number	Diff line change
`@@ -103,7 +103,7 @@ const DefaultCacheHandler: CacheHandler = {`
`103`	`103`	`}`
`104`	`104`	`},`
`105`	`105`
`106`		`- async unstable_expireTags(...tags) {`
	`106`	`+ async expireTags(...tags) {`
`107`	`107`	`for (const tag of tags) {`
`108`	`108`	`if (!tagsManifest.items[tag]) {`
`109`	`109`	`tagsManifest.items[tag] = {}`
`@@ -113,8 +113,11 @@ const DefaultCacheHandler: CacheHandler = {`
`113`	`113`	`}`
`114`	`114`	`},`
`115`	`115`
	`116`	`+ // This is only meant to invalidate in memory tags`
	`117`	`+ // not meant to be propagated like expireTags would`
	`118`	`+ // in multi-instance scenario`
`116`	`119`	`async receiveExpiredTags(...tags): Promise<void> {`
`117`		`- return this.unstable_expireTags(...tags)`
	`120`	`+ return this.expireTags(...tags)`
`118`	`121`	`},`
`119`	`122`	`}`
`120`	`123`