wip: correctly label IO promises in devtools

lubieowoce · lubieowoce · commit 15dfaa61bf94 · 2025-10-17T17:19:04.000+02:00
diff --git a/packages/next/src/server/app-render/app-render.tsx b/packages/next/src/server/app-render/app-render.tsx
@@ -2803,6 +2803,12 @@ async function renderWithRestartOnCacheMissInDev(
     cacheSignal,
     hangingCacheAbortSignal: hangingCacheAbortController.signal,
     hangingPromiseAbortSignal: initialHangingPromiseController.signal,
+    asyncApiPromises: createAsyncApiPromisesInDev(
+      initialStageController,
+      requestStore.cookies,
+      requestStore.mutableCookies,
+      requestStore.headers
+    ),
     dynamicTracking: createDynamicTrackingState(
       false // isDebugDynamicAccesses
     ),
@@ -2942,6 +2948,12 @@ async function renderWithRestartOnCacheMissInDev(
     stagedRendering: finalStageController,
     prerenderResumeDataCache: null,
     cacheSignal: null,
+    asyncApiPromises: createAsyncApiPromisesInDev(
+      initialStageController,
+      requestStore.cookies,
+      requestStore.mutableCookies,
+      requestStore.headers
+    ),
     dynamicTracking: createDynamicTrackingState(
       false // isDebugDynamicAccesses
     ),
@@ -2992,6 +3004,48 @@ async function renderWithRestartOnCacheMissInDev(
   }
 }
 
+function createAsyncApiPromisesInDev(
+  stagedRendering: StagedRenderingController,
+  cookies: RequestStore['cookies'],
+  mutableCookies: RequestStore['mutableCookies'],
+  headers: RequestStore['headers']
+): DevRequestStoreModern['asyncApiPromises'] {
+  return {
+    // Runtime APIs
+    cookies: stagedRendering.delayUntilStage(
+      RenderStage.Runtime,
+      'cookies',
+      cookies
+    ),
+    mutableCookies: stagedRendering.delayUntilStage(
+      RenderStage.Runtime,
+      'cookies',
+      mutableCookies as RequestStore['cookies']
+    ),
+    headers: stagedRendering.delayUntilStage(
+      RenderStage.Runtime,
+      'headers',
+      headers
+    ),
+    // These are not used directly, but we chain other `params`/`searchParams` promises off of them.
+    sharedParamsParent: stagedRendering.delayUntilStage(
+      RenderStage.Runtime,
+      'params',
+      '<internal params>'
+    ),
+    sharedSearchParamsParent: stagedRendering.delayUntilStage(
+      RenderStage.Runtime,
+      'searchParams',
+      '<internal searchParams>'
+    ),
+    connection: stagedRendering.delayUntilStage(
+      RenderStage.Dynamic,
+      'connection',
+      undefined
+    ),
+  }
+}
+
 type DebugChannelPair = {
   serverSide: DebugChannelServer
   clientSide: DebugChannelClient
diff --git a/packages/next/src/server/app-render/staged-rendering.ts b/packages/next/src/server/app-render/staged-rendering.ts
@@ -71,15 +71,17 @@ export class StagedRenderingController {
     return this.getStagePromise(stage)
   }
 
-  delayUntilStage<T>(stage: NonStaticRenderStage, resolvedValue: T) {
+  delayUntilStage<T>(
+    stage: NonStaticRenderStage,
+    displayName: string | undefined,
+    resolvedValue: T
+  ) {
     const stagePromise = this.getStagePromise(stage)
-    // FIXME: this seems to be the only form that leads to correct API names
-    // being displayed in React Devtools (in the "suspended by" section).
-    // If we use `promise.then(() => resolvedValue)`, the names are lost.
-    // It's a bit strange that only one of those works right.
-    const promise = new Promise<T>((resolve, reject) => {
-      stagePromise.then(resolve.bind(null, resolvedValue), reject)
-    })
+    const promise = createDevtoolsIOPromise(
+      stagePromise,
+      displayName,
+      resolvedValue
+    )
 
     // Analogously to `makeHangingPromise`, we might reject this promise if the signal is invoked.
     // (e.g. in the case where we don't want want the render to proceed to the dynamic stage and abort it).
@@ -91,4 +93,24 @@ export class StagedRenderingController {
   }
 }
 
+function createDevtoolsIOPromise<T>(
+  trigger: Promise<any>,
+  displayName: string | undefined,
+  resolvedValue: T
+): Promise<T> {
+  // If we create a `new Promise` and give it a displayName
+  // (with no userspace code above us in the stack)
+  // ReactDevtools will use it as the IO cause when determining "suspended by".
+  // In particular, it should shadow any inner IO that resolved/rejected the promise
+  // (which in this case will be the `setTimeout` that triggers the relevant stage)
+  const promise = new Promise<T>((resolve, reject) => {
+    trigger.then(resolve.bind(null, resolvedValue), reject)
+  })
+  if (displayName !== undefined) {
+    // @ts-expect-error
+    promise.displayName = displayName
+  }
+  return promise
+}
+
 function ignoreReject() {}
diff --git a/packages/next/src/server/app-render/work-unit-async-storage.external.ts b/packages/next/src/server/app-render/work-unit-async-storage.external.ts
@@ -92,6 +92,7 @@ export type DevStoreModernPartial = {
   readonly stagedRendering: StagedRenderingController
   readonly captureOwnerStack: () => string | null
   readonly dynamicTracking: DynamicTrackingState
+  readonly asyncApiPromises: DevAsyncApiPromises
 } & (
   | {
       // In the initial render, we track and fill caches
@@ -121,6 +122,17 @@ type AllMissing<TObj extends Record<string, any>> = {
   [key in keyof TObj]?: undefined
 }
 
+type DevAsyncApiPromises = {
+  cookies: Promise<ReadonlyRequestCookies>
+  mutableCookies: Promise<ReadonlyRequestCookies>
+  headers: Promise<ReadonlyHeaders>
+
+  sharedParamsParent: Promise<string>
+  sharedSearchParamsParent: Promise<string>
+
+  connection: Promise<undefined>
+}
+
 /**
  * The Prerender store is for tracking information related to prerenders.
  *
diff --git a/packages/next/src/server/dynamic-rendering-utils.ts b/packages/next/src/server/dynamic-rendering-utils.ts
@@ -83,7 +83,11 @@ export function makeDevtoolsIOAwarePromise<T>(
 ): Promise<T> {
   if (requestStore.stagedRendering) {
     // We resolve each stage in a timeout, so React DevTools will pick this up as IO.
-    return requestStore.stagedRendering.delayUntilStage(stage, underlying)
+    return requestStore.stagedRendering.delayUntilStage(
+      stage,
+      undefined,
+      underlying
+    )
   }
   // in React DevTools if we resolve in a setTimeout we will observe
   // the promise resolution as something that can suspend a boundary or root.
diff --git a/packages/next/src/server/request/connection.ts b/packages/next/src/server/request/connection.ts
@@ -106,6 +106,9 @@ export function connection(): Promise<void> {
             // Semantically we only need the dev tracking when running in `next dev`
             // but since you would never use next dev with production NODE_ENV we use this
             // as a proxy so we can statically exclude this code from production builds.
+            if (workUnitStore.asyncApiPromises) {
+              return workUnitStore.asyncApiPromises.connection
+            }
             return makeDevtoolsIOAwarePromise(
               undefined,
               workUnitStore,
diff --git a/packages/next/src/server/request/cookies.ts b/packages/next/src/server/request/cookies.ts
@@ -190,6 +190,22 @@ function makeUntrackedCookiesWithDevWarnings(
   underlyingCookies: ReadonlyRequestCookies,
   route?: string
 ): Promise<ReadonlyRequestCookies> {
+  if (requestStore.asyncApiPromises) {
+    let promise: Promise<ReadonlyRequestCookies>
+    if (underlyingCookies === requestStore.mutableCookies) {
+      promise = requestStore.asyncApiPromises.mutableCookies
+    } else if (underlyingCookies === requestStore.cookies) {
+      promise = requestStore.asyncApiPromises.cookies
+    } else {
+      throw new InvariantError(
+        'Received a underlying cookies object that does not match either `cookies` or `mutableCookies`'
+      )
+    }
+    // TODO(restart-on-cache-miss): Instrument with warnings
+    // return instrumentCookiesPromiseWithDevWarnings(promise, route)
+    return promise
+  }
+
   const cachedCookies = CachedCookies.get(underlyingCookies)
   if (cachedCookies) {
     return cachedCookies
@@ -201,7 +217,22 @@ function makeUntrackedCookiesWithDevWarnings(
     RenderStage.Runtime
   )
 
-  const proxiedPromise = new Proxy(promise, {
+  const proxiedPromise = instrumentCookiesPromiseWithDevWarnings(promise, route)
+
+  CachedCookies.set(underlyingCookies, proxiedPromise)
+
+  return proxiedPromise
+}
+
+const warnForSyncAccess = createDedupedByCallsiteServerErrorLoggerDev(
+  createCookiesAccessError
+)
+
+function instrumentCookiesPromiseWithDevWarnings(
+  promise: Promise<ReadonlyRequestCookies>,
+  route: string | undefined
+) {
+  return new Proxy(promise, {
     get(target, prop, receiver) {
       switch (prop) {
         case Symbol.iterator: {
@@ -226,17 +257,12 @@ function makeUntrackedCookiesWithDevWarnings(
 
       return ReflectAdapter.get(target, prop, receiver)
     },
+    set(target, prop, newValue, receiver) {
+      return ReflectAdapter.set(target, prop, newValue, receiver)
+    },
   })
-
-  CachedCookies.set(underlyingCookies, proxiedPromise)
-
-  return proxiedPromise
 }
 
-const warnForSyncAccess = createDedupedByCallsiteServerErrorLoggerDev(
-  createCookiesAccessError
-)
-
 function createCookiesAccessError(
   route: string | undefined,
   expression: string
diff --git a/packages/next/src/server/request/headers.ts b/packages/next/src/server/request/headers.ts
@@ -199,6 +199,13 @@ function makeUntrackedHeadersWithDevWarnings(
   route: string | undefined,
   requestStore: RequestStore
 ): Promise<ReadonlyHeaders> {
+  if (requestStore.asyncApiPromises) {
+    const promise = requestStore.asyncApiPromises.headers
+    // TODO(restart-on-cache-miss): Instrument with warnings
+    // return instrumentHeadersPromiseWithDevWarnings(promise, route)
+    return promise
+  }
+
   const cachedHeaders = CachedHeaders.get(underlyingHeaders)
   if (cachedHeaders) {
     return cachedHeaders
@@ -210,7 +217,22 @@ function makeUntrackedHeadersWithDevWarnings(
     RenderStage.Runtime
   )
 
-  const proxiedPromise = new Proxy(promise, {
+  const proxiedPromise = instrumentHeadersPromiseWithDevWarnings(promise, route)
+
+  CachedHeaders.set(underlyingHeaders, proxiedPromise)
+
+  return proxiedPromise
+}
+
+const warnForSyncAccess = createDedupedByCallsiteServerErrorLoggerDev(
+  createHeadersAccessError
+)
+
+function instrumentHeadersPromiseWithDevWarnings(
+  promise: Promise<ReadonlyHeaders>,
+  route: string | undefined
+) {
+  return new Proxy(promise, {
     get(target, prop, receiver) {
       switch (prop) {
         case Symbol.iterator: {
@@ -237,17 +259,12 @@ function makeUntrackedHeadersWithDevWarnings(
 
       return ReflectAdapter.get(target, prop, receiver)
     },
+    set(target, prop, newValue, receiver) {
+      return ReflectAdapter.set(target, prop, newValue, receiver)
+    },
   })
-
-  CachedHeaders.set(underlyingHeaders, proxiedPromise)
-
-  return proxiedPromise
 }
 
-const warnForSyncAccess = createDedupedByCallsiteServerErrorLoggerDev(
-  createHeadersAccessError
-)
-
 function createHeadersAccessError(
   route: string | undefined,
   expression: string
diff --git a/packages/next/src/server/request/params.ts b/packages/next/src/server/request/params.ts
@@ -455,6 +455,19 @@ function makeDynamicallyTrackedParamsWithDevWarnings(
   workStore: WorkStore,
   requestStore: RequestStore
 ): Promise<Params> {
+  if (requestStore.asyncApiPromises && hasFallbackParams) {
+    const promise = requestStore.asyncApiPromises.sharedParamsParent.then(
+      () => underlyingParams
+    )
+    // TODO(restart-on-cache-miss): Instrument with warnings
+    // return instrumentParamsPromiseWithDevWarnings(
+    //   underlyingParams,
+    //   promise,
+    //   workStore
+    // )
+    return promise
+  }
+
   const cachedParams = CachedParams.get(underlyingParams)
   if (cachedParams) {
     return cachedParams
@@ -472,6 +485,20 @@ function makeDynamicallyTrackedParamsWithDevWarnings(
     : // We don't want to force an environment transition when this params is not part of the fallback params set
       Promise.resolve(underlyingParams)
 
+  const proxiedPromise = instrumentParamsPromiseWithDevWarnings(
+    underlyingParams,
+    promise,
+    workStore
+  )
+  CachedParams.set(underlyingParams, proxiedPromise)
+  return proxiedPromise
+}
+
+function instrumentParamsPromiseWithDevWarnings(
+  underlyingParams: Params,
+  promise: Promise<Params>,
+  workStore: WorkStore
+): Promise<Params> {
   // Track which properties we should warn for.
   const proxiedProperties = new Set<string>()
 
@@ -484,7 +511,7 @@ function makeDynamicallyTrackedParamsWithDevWarnings(
     }
   })
 
-  const proxiedPromise = new Proxy(promise, {
+  return new Proxy(promise, {
     get(target, prop, receiver) {
       if (typeof prop === 'string') {
         if (
@@ -509,9 +536,6 @@ function makeDynamicallyTrackedParamsWithDevWarnings(
       return Reflect.ownKeys(target)
     },
   })
-
-  CachedParams.set(underlyingParams, proxiedPromise)
-  return proxiedPromise
 }
 
 const warnForSyncAccess = createDedupedByCallsiteServerErrorLoggerDev(
diff --git a/packages/next/src/server/request/search-params.ts b/packages/next/src/server/request/search-params.ts
diff --git a/packages/next/src/shared/lib/utils/reflect-utils.ts b/packages/next/src/shared/lib/utils/reflect-utils.ts
