[dev] Define request ID for RSC requests on the client (#84605)

Previously, we defined a request ID for RSC requests on the server. The
request ID is used to tag debug information sent via WebSocket to the
client, which then routes those chunks to the debug channel associated
with this ID.

However, this meant that the client had to await the server response to
retrieve the request ID from the response headers, before we could pass
the response (and the debug channel) to React.

For #84580, we want to pass the response promise directly to React, to
accurately show timing information about the request in the React
DevTools. To achieve this, we now define the request ID on the client,
and send it to the server via a request header. This means that the
client can create the debug channel immediately, without waiting for the
server response.

closes NAR-426

Author: unstubbable

packages/next/errors.json

@@ -851,5 +851,6 @@
   "850": "metadataBase is not a valid URL: %s",
   "851": "Pass either `webpack` or `turbopack`, not both.",
   "852": "Only custom servers can pass `webpack`, `turbo`, or `turbopack`.",
-  "853": "Turbopack build failed"
+  "853": "Turbopack build failed",
+  "854": "Expected a %s request header."
 }

packages/next/src/client/components/router-reducer/fetch-server-response.ts

@@ -21,6 +21,7 @@ import {
   NEXT_DID_POSTPONE_HEADER,
   NEXT_ROUTER_STALE_TIME_HEADER,
   NEXT_HTML_REQUEST_ID_HEADER,
+  NEXT_REQUEST_ID_HEADER,
 } from '../app-router-headers'
 import { callServer } from '../../app-call-server'
 import { findSourceMapURL } from '../../app-find-source-map-url'
@@ -77,6 +78,7 @@ export type RequestHeaders = {
   // A header that is only added in test mode to assert on fetch priority
   'Next-Test-Fetch-Priority'?: RequestInit['priority']
   [NEXT_HTML_REQUEST_ID_HEADER]?: string // dev-only
+  [NEXT_REQUEST_ID_HEADER]?: string // dev-only
 }
 
 function doMpaNavigation(url: string): FetchServerResponseResult {
@@ -230,7 +232,7 @@ export async function fetchServerResponse(
       : res.body
     const response = await (createFromNextReadableStream(
       flightStream,
-      res.headers
+      headers
     ) as Promise<NavigationFlightResponse>)
 
     if (getAppBuildId() !== response.b) {
@@ -299,8 +301,17 @@ export async function createFetch(
     headers['x-deployment-id'] = process.env.NEXT_DEPLOYMENT_ID
   }
 
-  if (process.env.NODE_ENV !== 'production' && self.__next_r) {
-    headers[NEXT_HTML_REQUEST_ID_HEADER] = self.__next_r
+  if (process.env.NODE_ENV !== 'production') {
+    if (self.__next_r) {
+      headers[NEXT_HTML_REQUEST_ID_HEADER] = self.__next_r
+    }
+
+    // Create a new request ID for the server action request. The server uses
+    // this to tag debug information sent via WebSocket to the client, which
+    // then routes those chunks to the debug channel associated with this ID.
+    headers[NEXT_REQUEST_ID_HEADER] = crypto
+      .getRandomValues(new Uint32Array(1))[0]
+      .toString(16)
   }
 
   const fetchOptions: RequestInit = {
@@ -404,12 +415,12 @@ export async function createFetch(
 
 export function createFromNextReadableStream(
   flightStream: ReadableStream<Uint8Array>,
-  responseHeaders: Headers
+  requestHeaders: RequestHeaders
 ): Promise<unknown> {
   return createFromReadableStream(flightStream, {
     callServer,
     findSourceMapURL,
-    debugChannel: createDebugChannel && createDebugChannel(responseHeaders),
+    debugChannel: createDebugChannel && createDebugChannel(requestHeaders),
   })
 }
 

packages/next/src/client/components/router-reducer/reducers/server-action-reducer.ts

@@ -12,6 +12,7 @@ import {
   NEXT_ROUTER_STATE_TREE_HEADER,
   NEXT_URL,
   RSC_CONTENT_TYPE_HEADER,
+  NEXT_REQUEST_ID_HEADER,
 } from '../../app-router-headers'
 import { UnrecognizedActionError } from '../../unrecognized-action-error'
 
@@ -119,8 +120,17 @@ async function fetchServerAction(
     headers[NEXT_URL] = nextUrl
   }
 
-  if (process.env.NODE_ENV !== 'production' && self.__next_r) {
-    headers[NEXT_HTML_REQUEST_ID_HEADER] = self.__next_r
+  if (process.env.NODE_ENV !== 'production') {
+    if (self.__next_r) {
+      headers[NEXT_HTML_REQUEST_ID_HEADER] = self.__next_r
+    }
+
+    // Create a new request ID for the server action request. The server uses
+    // this to tag debug information sent via WebSocket to the client, which
+    // then routes those chunks to the debug channel associated with this ID.
+    headers[NEXT_REQUEST_ID_HEADER] = crypto
+      .getRandomValues(new Uint32Array(1))[0]
+      .toString(16)
   }
 
   const res = await fetch(state.canonicalUrl, { method: 'POST', headers, body })
@@ -198,7 +208,7 @@ async function fetchServerAction(
         callServer,
         findSourceMapURL,
         temporaryReferences,
-        debugChannel: createDebugChannel && createDebugChannel(res.headers),
+        debugChannel: createDebugChannel && createDebugChannel(headers),
       }
     )
 

packages/next/src/client/components/segment-cache-impl/cache.ts

@@ -1432,7 +1432,7 @@ export async function fetchRouteOnCacheMiss(
       )
       const serverData = await (createFromNextReadableStream(
         prefetchStream,
-        response.headers
+        headers
       ) as Promise<RootTreePrefetch>)
       if (serverData.buildId !== getAppBuildId()) {
         // The server build does not match the client. Treat as a 404. During
@@ -1484,7 +1484,7 @@ export async function fetchRouteOnCacheMiss(
       )
       const serverData = await (createFromNextReadableStream(
         prefetchStream,
-        response.headers
+        headers
       ) as Promise<NavigationFlightResponse>)
       if (serverData.b !== getAppBuildId()) {
         // The server build does not match the client. Treat as a 404. During
@@ -1630,7 +1630,7 @@ export async function fetchSegmentOnCacheMiss(
     )
     const serverData = await (createFromNextReadableStream(
       prefetchStream,
-      response.headers
+      headers
     ) as Promise<SegmentPrefetch>)
     if (serverData.buildId !== getAppBuildId()) {
       // The server build does not match the client. Treat as a 404. During
@@ -1750,7 +1750,7 @@ export async function fetchSegmentPrefetchesUsingDynamicRequest(
     )
     const serverData = await (createFromNextReadableStream(
       prefetchStream,
-      response.headers
+      headers
     ) as Promise<NavigationFlightResponse>)
 
     const isResponsePartial =

packages/next/src/client/dev/debug-channel.ts

@@ -23,18 +23,20 @@ export function getOrCreateDebugChannelReadableWriterPair(
   return pair
 }
 
-export function createDebugChannel(responseHeaders: Headers | undefined): {
+export function createDebugChannel(
+  requestHeaders: Record<string, string> | undefined
+): {
   writable?: WritableStream
   readable?: ReadableStream
 } {
   let requestId: string | undefined
 
-  if (responseHeaders) {
-    requestId = responseHeaders.get(NEXT_REQUEST_ID_HEADER) ?? undefined
+  if (requestHeaders) {
+    requestId = requestHeaders[NEXT_REQUEST_ID_HEADER] ?? undefined
 
     if (!requestId) {
       throw new InvariantError(
-        `Expected a ${JSON.stringify(NEXT_REQUEST_ID_HEADER)} response header.`
+        `Expected a ${JSON.stringify(NEXT_REQUEST_ID_HEADER)} request header.`
       )
     }
   } else {

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

@@ -287,6 +287,7 @@ interface ParsedRequestHeaders {
   readonly isRSCRequest: boolean
   readonly nonce: string | undefined
   readonly previouslyRevalidatedTags: string[]
+  readonly requestId: string | undefined
   readonly htmlRequestId: string | undefined
 }
 
@@ -332,10 +333,25 @@ function parseRequestHeaders(
     options.previewModeId
   )
 
-  const htmlRequestId =
-    typeof headers[NEXT_HTML_REQUEST_ID_HEADER] === 'string'
-      ? headers[NEXT_HTML_REQUEST_ID_HEADER]
-      : undefined
+  let requestId: string | undefined
+  let htmlRequestId: string | undefined
+
+  if (process.env.NODE_ENV !== 'production') {
+    // The request IDs are only used in development mode to send debug
+    // information to the matching client (identified by the HTML request ID
+    // that was sent to the client with the HTML document) for the current
+    // request (identified by the request ID, as defined by the client).
+
+    requestId =
+      typeof headers[NEXT_REQUEST_ID_HEADER] === 'string'
+        ? headers[NEXT_REQUEST_ID_HEADER]
+        : undefined
+
+    htmlRequestId =
+      typeof headers[NEXT_HTML_REQUEST_ID_HEADER] === 'string'
+        ? headers[NEXT_HTML_REQUEST_ID_HEADER]
+        : undefined
+  }
 
   return {
     flightRouterState,
@@ -347,6 +363,7 @@ function parseRequestHeaders(
     isDevWarmupRequest,
     nonce,
     previouslyRevalidatedTags,
+    requestId,
     htmlRequestId,
   }
 }
@@ -1632,22 +1649,7 @@ async function renderToHTMLOrFlightImpl(
   const { isStaticGeneration } = workStore
 
   let requestId: string
-
-  if (isStaticGeneration) {
-    requestId = Buffer.from(
-      await crypto.subtle.digest('SHA-1', Buffer.from(req.url))
-    ).toString('hex')
-  } else if (process.env.NEXT_RUNTIME === 'edge') {
-    requestId = crypto.randomUUID()
-  } else {
-    requestId = (
-      require('next/dist/compiled/nanoid') as typeof import('next/dist/compiled/nanoid')
-    ).nanoid()
-  }
-
-  if (process.env.NODE_ENV !== 'production') {
-    res.setHeader(NEXT_REQUEST_ID_HEADER, requestId)
-  }
+  let htmlRequestId: string
 
   const {
     flightRouterState,
@@ -1657,9 +1659,33 @@ async function renderToHTMLOrFlightImpl(
     isDevWarmupRequest,
     isHmrRefresh,
     nonce,
-    htmlRequestId = requestId,
   } = parsedRequestHeaders
 
+  if (parsedRequestHeaders.requestId) {
+    // If the client has provided a request ID (in development mode), we use it.
+    requestId = parsedRequestHeaders.requestId
+  } else {
+    // Otherwise we generate a new request ID.
+    if (isStaticGeneration) {
+      requestId = Buffer.from(
+        await crypto.subtle.digest('SHA-1', Buffer.from(req.url))
+      ).toString('hex')
+    } else if (process.env.NEXT_RUNTIME === 'edge') {
+      requestId = crypto.randomUUID()
+    } else {
+      requestId = (
+        require('next/dist/compiled/nanoid') as typeof import('next/dist/compiled/nanoid')
+      ).nanoid()
+    }
+  }
+
+  // If the client has provided an HTML request ID, we use it to associate the
+  // request with the HTML document from which it originated, which is used to
+  // send debug information to the associated WebSocket client. Otherwise, this
+  // is the request for the HTML document, so we use the request ID also as the
+  // HTML request ID.
+  htmlRequestId = parsedRequestHeaders.htmlRequestId || requestId
+
   /**
    * Dynamic parameters. E.g. when you visit `/dashboard/vercel` which is rendered by `/dashboard/[slug]` the value will be {"slug": "vercel"}.
    */