Remove proxy for cookies and headers to improve awaited value detection.

gnoff · gnoff · commit 34f6f4a54821 · 2025-10-18T23:04:07.000-07:00
The proxy obscures the awaited value for the suspended by information for await cookies() and await headers(). Instead we use property descriptors that are revokable. This allows the debug info to convey the actual awaited value.

We cannot do the same for params and searchParams because for those we need the proxy to trap arbitrary param and searchParam sync access. We can remove this in a future version of Next.js and then the awaited values will improve in dev
diff --git a/packages/next/errors.json b/packages/next/errors.json
@@ -888,5 +888,5 @@
   "887": "`cacheLife()` is only available with the `cacheComponents` config.",
   "888": "Unknown \\`cacheLife()\\` profile \"%s\" is not configured in next.config.js\\nmodule.exports = {\n  cacheLife: {\n    \"%s\": ...\\n  }\n}",
   "889": "Unknown \\`cacheLife()\\` profile \"%s\" is not configured in next.config.js\\nmodule.exports = {\n  cacheLife: {\n      \"%s\": ...\\n    }\n}",
-  "890": "Received a underlying cookies object that does not match either `cookies` or `mutableCookies`"
+  "890": "Received an underlying cookies object that does not match either `cookies` or `mutableCookies`"
 }
diff --git a/packages/next/src/server/request/cookies.ts b/packages/next/src/server/request/cookies.ts
@@ -28,7 +28,6 @@ import {
 import { createDedupedByCallsiteServerErrorLoggerDev } from '../create-deduped-by-callsite-server-error-logger'
 import { isRequestAPICallableInsideAfter } from './utils'
 import { InvariantError } from '../../shared/lib/invariant-error'
-import { ReflectAdapter } from '../web/spec-extension/adapters/reflect'
 import { RenderStage } from '../app-render/staged-rendering'
 
 export function cookies(): Promise<ReadonlyRequestCookies> {
@@ -198,7 +197,7 @@ function makeUntrackedCookiesWithDevWarnings(
       promise = requestStore.asyncApiPromises.cookies
     } else {
       throw new InvariantError(
-        'Received a underlying cookies object that does not match either `cookies` or `mutableCookies`'
+        'Received an underlying cookies object that does not match either `cookies` or `mutableCookies`'
       )
     }
     return instrumentCookiesPromiseWithDevWarnings(promise, route)
@@ -230,35 +229,65 @@ function instrumentCookiesPromiseWithDevWarnings(
   promise: Promise<ReadonlyRequestCookies>,
   route: string | undefined
 ) {
-  return new Proxy(promise, {
-    get(target, prop, receiver) {
-      switch (prop) {
-        case Symbol.iterator: {
-          warnForSyncAccess(route, '`...cookies()` or similar iteration')
-          break
-        }
-        case 'size':
-        case 'get':
-        case 'getAll':
-        case 'has':
-        case 'set':
-        case 'delete':
-        case 'clear':
-        case 'toString': {
-          warnForSyncAccess(route, `\`cookies().${prop}\``)
-          break
-        }
-        default: {
-          // We only warn for well-defined properties of the cookies object.
-        }
-      }
+  Object.defineProperties(promise, {
+    [Symbol.iterator]: replaceableWarningDescriptorForSymbolIterator(
+      promise,
+      route
+    ),
+    size: replaceableWarningDescriptor(promise, 'size', route),
+    get: replaceableWarningDescriptor(promise, 'get', route),
+    getAll: replaceableWarningDescriptor(promise, 'getAll', route),
+    has: replaceableWarningDescriptor(promise, 'has', route),
+    set: replaceableWarningDescriptor(promise, 'set', route),
+    delete: replaceableWarningDescriptor(promise, 'delete', route),
+    clear: replaceableWarningDescriptor(promise, 'clear', route),
+    toString: replaceableWarningDescriptor(promise, 'toString', route),
+  })
+  return promise
+}
 
-      return ReflectAdapter.get(target, prop, receiver)
+function replaceableWarningDescriptor(
+  target: unknown,
+  prop: string,
+  route: string | undefined
+) {
+  return {
+    enumerable: false,
+    get() {
+      warnForSyncAccess(route, `\`cookies().${prop}\``)
+      return undefined
     },
-    set(target, prop, newValue, receiver) {
-      return ReflectAdapter.set(target, prop, newValue, receiver)
+    set(value: unknown) {
+      Object.defineProperty(target, prop, {
+        value,
+        writable: true,
+        configurable: true,
+      })
     },
-  })
+    configurable: true,
+  }
+}
+
+function replaceableWarningDescriptorForSymbolIterator(
+  target: unknown,
+  route: string | undefined
+) {
+  return {
+    enumerable: false,
+    get() {
+      warnForSyncAccess(route, '`...cookies()` or similar iteration')
+      return undefined
+    },
+    set(value: unknown) {
+      Object.defineProperty(target, Symbol.iterator, {
+        value,
+        writable: true,
+        enumerable: true,
+        configurable: true,
+      })
+    },
+    configurable: true,
+  }
 }
 
 function createCookiesAccessError(
diff --git a/packages/next/src/server/request/headers.ts b/packages/next/src/server/request/headers.ts
@@ -26,7 +26,6 @@ import {
 import { createDedupedByCallsiteServerErrorLoggerDev } from '../create-deduped-by-callsite-server-error-logger'
 import { isRequestAPICallableInsideAfter } from './utils'
 import { InvariantError } from '../../shared/lib/invariant-error'
-import { ReflectAdapter } from '../web/spec-extension/adapters/reflect'
 import { RenderStage } from '../app-render/staged-rendering'
 
 /**
@@ -230,37 +229,67 @@ function instrumentHeadersPromiseWithDevWarnings(
   promise: Promise<ReadonlyHeaders>,
   route: string | undefined
 ) {
-  return new Proxy(promise, {
-    get(target, prop, receiver) {
-      switch (prop) {
-        case Symbol.iterator: {
-          warnForSyncAccess(route, '`...headers()` or similar iteration')
-          break
-        }
-        case 'append':
-        case 'delete':
-        case 'get':
-        case 'has':
-        case 'set':
-        case 'getSetCookie':
-        case 'forEach':
-        case 'keys':
-        case 'values':
-        case 'entries': {
-          warnForSyncAccess(route, `\`headers().${prop}\``)
-          break
-        }
-        default: {
-          // We only warn for well-defined properties of the headers object.
-        }
-      }
+  Object.defineProperties(promise, {
+    [Symbol.iterator]: replaceableWarningDescriptorForSymbolIterator(
+      promise,
+      route
+    ),
+    append: replaceableWarningDescriptor(promise, 'append', route),
+    delete: replaceableWarningDescriptor(promise, 'delete', route),
+    get: replaceableWarningDescriptor(promise, 'get', route),
+    has: replaceableWarningDescriptor(promise, 'has', route),
+    set: replaceableWarningDescriptor(promise, 'set', route),
+    getSetCookie: replaceableWarningDescriptor(promise, 'getSetCookie', route),
+    forEach: replaceableWarningDescriptor(promise, 'forEach', route),
+    keys: replaceableWarningDescriptor(promise, 'keys', route),
+    values: replaceableWarningDescriptor(promise, 'values', route),
+    entries: replaceableWarningDescriptor(promise, 'entries', route),
+  })
+  return promise
+}
+
+function replaceableWarningDescriptor(
+  target: unknown,
+  prop: string,
+  route: string | undefined
+) {
+  return {
+    enumerable: false,
+    get() {
+      warnForSyncAccess(route, `\`headers().${prop}\``)
+      return undefined
+    },
+    set(value: unknown) {
+      Object.defineProperty(target, prop, {
+        value,
+        writable: true,
+        configurable: true,
+      })
+    },
+    configurable: true,
+  }
+}
 
-      return ReflectAdapter.get(target, prop, receiver)
+function replaceableWarningDescriptorForSymbolIterator(
+  target: unknown,
+  route: string | undefined
+) {
+  return {
+    enumerable: false,
+    get() {
+      warnForSyncAccess(route, '`...headers()` or similar iteration')
+      return undefined
     },
-    set(target, prop, newValue, receiver) {
-      return ReflectAdapter.set(target, prop, newValue, receiver)
+    set(value: unknown) {
+      Object.defineProperty(target, Symbol.iterator, {
+        value,
+        writable: true,
+        enumerable: true,
+        configurable: true,
+      })
     },
-  })
+    configurable: true,
+  }
 }
 
 function createHeadersAccessError(
