[Cache Components] allow using headers() in runtime prefetches (#83838)

This PR allows usage of `headers()` in runtime prefetches and private
caches. The implementation is basically analogous to `cookies()`.

Closes NAR-353

Author: lubieowoce

packages/next/src/server/app-render/app-render.tsx

@@ -676,6 +676,7 @@ async function generateRuntimePrefetchResult(
     prerenderResumeDataCache,
     renderResumeDataCache,
     rootParams,
+    requestStore.headers,
     requestStore.cookies,
     requestStore.draftMode
   )
@@ -686,6 +687,7 @@ async function generateRuntimePrefetchResult(
     prerenderResumeDataCache,
     renderResumeDataCache,
     rootParams,
+    requestStore.headers,
     requestStore.cookies,
     requestStore.draftMode,
     onError
@@ -707,6 +709,7 @@ async function prospectiveRuntimeServerPrerender(
   prerenderResumeDataCache: PrerenderResumeDataCache | null,
   renderResumeDataCache: RenderResumeDataCache | null,
   rootParams: Params,
+  headers: PrerenderStoreModernRuntime['headers'],
   cookies: PrerenderStoreModernRuntime['cookies'],
   draftMode: PrerenderStoreModernRuntime['draftMode']
 ) {
@@ -757,6 +760,7 @@ async function prospectiveRuntimeServerPrerender(
     // We only need task sequencing in the final prerender.
     runtimeStagePromise: null,
     // These are not present in regular prerenders, but allowed in a runtime prerender.
+    headers,
     cookies,
     draftMode,
   }
@@ -842,6 +846,7 @@ async function finalRuntimeServerPrerender(
   prerenderResumeDataCache: PrerenderResumeDataCache | null,
   renderResumeDataCache: RenderResumeDataCache | null,
   rootParams: Params,
+  headers: PrerenderStoreModernRuntime['headers'],
   cookies: PrerenderStoreModernRuntime['cookies'],
   draftMode: PrerenderStoreModernRuntime['draftMode'],
   onError: (err: unknown) => string | undefined
@@ -892,6 +897,7 @@ async function finalRuntimeServerPrerender(
     // Used to separate the "Static" stage from the "Runtime" stage.
     runtimeStagePromise,
     // These are not present in regular prerenders, but allowed in a runtime prerender.
+    headers,
     cookies,
     draftMode,
   }

packages/next/src/server/app-render/work-unit-async-storage.external.ts

@@ -120,6 +120,7 @@ export interface PrerenderStoreModernRuntime
    */
   readonly runtimeStagePromise: Promise<void> | null
 
+  readonly headers: RequestStore['headers']
   readonly cookies: RequestStore['cookies']
   readonly draftMode: RequestStore['draftMode']
 }
@@ -294,10 +295,7 @@ export interface PrivateUseCacheStore extends CommonUseCacheStore {
    */
   readonly runtimeStagePromise: Promise<void> | null
 
-  /**
-   * As opposed to the public cache store, the private cache store is allowed to
-   * access the request cookies.
-   */
+  readonly headers: ReadonlyHeaders
   readonly cookies: ReadonlyRequestCookies
 
   /**

packages/next/src/server/request/cookies.ts

@@ -126,10 +126,11 @@ export function cookies(): Promise<ReadonlyRequestCookies> {
             makeUntrackedCookies(workUnitStore.cookies)
           )
         case 'private-cache':
+          // Private caches are delayed until the runtime stage in use-cache-wrapper,
+          // so we don't need an additional delay here.
           if (process.env.__NEXT_CACHE_COMPONENTS) {
             return makeUntrackedCookies(workUnitStore.cookies)
           }
-
           return makeUntrackedExoticCookies(workUnitStore.cookies)
         case 'request':
           trackDynamicDataInDynamicRender(workUnitStore)

packages/next/src/server/request/headers.ts

@@ -12,6 +12,7 @@ import {
   type PrerenderStoreModern,
 } from '../app-render/work-unit-async-storage.external'
 import {
+  delayUntilRuntimeStage,
   postponeWithTracking,
   throwToInterruptStaticGeneration,
   trackDynamicDataInDynamicRender,
@@ -92,20 +93,13 @@ export function headers(): Promise<ReadonlyHeaders> {
           workStore.invalidDynamicUsageError ??= error
           throw error
         }
-        case 'private-cache': {
-          const error = new Error(
-            `Route ${workStore.route} used "headers" inside "use cache: private". Accessing "headers" inside a private cache scope is not supported. If you need this data inside a cached function use "headers" outside of the cached function and pass the required dynamic data in as an argument. See more info here: https://nextjs.org/docs/messages/next-request-in-use-cache`
-          )
-          Error.captureStackTrace(error, headers)
-          workStore.invalidDynamicUsageError ??= error
-          throw error
-        }
         case 'unstable-cache':
           throw new Error(
             `Route ${workStore.route} used "headers" inside a function cached with "unstable_cache(...)". Accessing Dynamic data sources inside a cache scope is not supported. If you need this data inside a cached function use "headers" outside of the cached function and pass the required dynamic data in as an argument. See more info here: https://nextjs.org/docs/app/api-reference/functions/unstable_cache`
           )
         case 'prerender':
         case 'prerender-client':
+        case 'private-cache':
         case 'prerender-runtime':
         case 'prerender-ppr':
         case 'prerender-legacy':
@@ -125,7 +119,6 @@ export function headers(): Promise<ReadonlyHeaders> {
     if (workUnitStore) {
       switch (workUnitStore.type) {
         case 'prerender':
-        case 'prerender-runtime':
           return makeHangingHeaders(workStore, workUnitStore)
         case 'prerender-client':
           const exportName = '`headers`'
@@ -152,6 +145,18 @@ export function headers(): Promise<ReadonlyHeaders> {
             workStore,
             workUnitStore
           )
+        case 'prerender-runtime':
+          return delayUntilRuntimeStage(
+            workUnitStore,
+            makeUntrackedHeaders(workUnitStore.headers)
+          )
+        case 'private-cache':
+          // Private caches are delayed until the runtime stage in use-cache-wrapper,
+          // so we don't need an additional delay here.
+          if (process.env.__NEXT_CACHE_COMPONENTS) {
+            return makeUntrackedHeaders(workUnitStore.headers)
+          }
+          return makeUntrackedExoticHeaders(workUnitStore.headers)
         case 'request':
           trackDynamicDataInDynamicRender(workUnitStore)
 

packages/next/src/server/use-cache/use-cache-wrapper.ts

@@ -211,6 +211,7 @@ function createUseCacheStore(
         outerWorkUnitStore
       ),
       rootParams: outerWorkUnitStore.rootParams,
+      headers: outerWorkUnitStore.headers,
       cookies: outerWorkUnitStore.cookies,
     }
   } else {

test/e2e/app-dir/cache-components-errors/cache-components-errors.test.ts

@@ -3406,63 +3406,6 @@ describe('Cache Components Errors', () => {
           })
         }
       })
-
-      describe('with `headers()`', () => {
-        if (isNextDev) {
-          it('should show a redbox error', async () => {
-            const browser = await next.browser('/use-cache-private-headers')
-
-            if (isTurbopack) {
-              await expect(browser).toDisplayRedbox(`
-               {
-                 "description": "Route /use-cache-private-headers used "headers" inside "use cache: private". Accessing "headers" inside a private cache scope is not supported. If you need this data inside a cached function use "headers" outside of the cached function and pass the required dynamic data in as an argument. See more info here: https://nextjs.org/docs/messages/next-request-in-use-cache",
-                 "environmentLabel": null,
-                 "label": "Runtime Error",
-                 "source": "app/use-cache-private-headers/page.tsx (25:18) @ Private
-               > 25 |     await headers()
-                    |                  ^",
-                 "stack": [
-                   "Private app/use-cache-private-headers/page.tsx (25:18)",
-                 ],
-               }
-              `)
-            } else {
-              await expect(browser).toDisplayRedbox(`
-               {
-                 "description": "Route /use-cache-private-headers used "headers" inside "use cache: private". Accessing "headers" inside a private cache scope is not supported. If you need this data inside a cached function use "headers" outside of the cached function and pass the required dynamic data in as an argument. See more info here: https://nextjs.org/docs/messages/next-request-in-use-cache",
-                 "environmentLabel": null,
-                 "label": "Runtime Error",
-                 "source": "app/use-cache-private-headers/page.tsx (25:18) @ Private
-               > 25 |     await headers()
-                    |                  ^",
-                 "stack": [
-                   "Private app/use-cache-private-headers/page.tsx (25:18)",
-                 ],
-               }
-              `)
-            }
-          })
-        } else {
-          // TODO: With prefetch sentinels this should yield a build error.
-          it('should not fail the build and show no runtime error (caught in userland)', async () => {
-            await prerender('/use-cache-private-headers')
-            await next.start({ skipBuild: true })
-            cliOutputLength = next.cliOutput.length
-
-            const browser = await next.browser('/use-cache-private-headers', {
-              pushErrorAsConsoleLog: true,
-            })
-
-            expect(await browser.elementById('private').text()).toBe('Private')
-
-            expect(await browser.log()).not.toContainEqual(
-              expect.objectContaining({ source: 'error' })
-            )
-
-            expect(next.cliOutput.slice(cliOutputLength)).not.toInclude('Error')
-          })
-        }
-      })
     })
 
     describe('Sync IO - Current Time - Date()', () => {

test/e2e/app-dir/cache-components-errors/fixtures/default/app/use-cache-private-headers/layout.tsx

@@ -23,6 +23,12 @@ export default async function Page() {
             prefetch={true}
           />
         </li>
+        <li>
+          <DebugLinkAccordion
+            href="/errors/sync-io-after-runtime-api/headers"
+            prefetch={true}
+          />
+        </li>
         <li>
           <DebugLinkAccordion
             href="/errors/sync-io-after-runtime-api/dynamic-params/123"

test/e2e/app-dir/cache-components-errors/fixtures/default/app/use-cache-private-headers/page.tsx

@@ -0,0 +1,23 @@
+import { headers } from 'next/headers'
+import { Suspense } from 'react'
+import { DebugRenderKind } from '../../../../shared'
+
+export default async function Page() {
+  return (
+    <main>
+      <DebugRenderKind />
+      <p id="intro">
+        This page performs sync IO after a headers() call, so we should only see
+        the error in a runtime prefetch
+      </p>
+      <Suspense fallback={<div style={{ color: 'grey' }}>Loading 1...</div>}>
+        <RuntimePrefetchable />
+      </Suspense>
+    </main>
+  )
+}
+
+async function RuntimePrefetchable() {
+  await headers()
+  return <div id="timestamp">Timestamp: {Date.now()}</div>
+}