Include server latency in debug info (#84580)

The debug info of the promise created by the Flight client represents
the latency between when the navigation starts and when it's passed to
React. Most importantly, it should include the time it takes for the
client to start receiving data from the server.

Before this PR, the timing was too late because we did not call into the
Flight client until after we started receiving data.

To fix this, we switch from using `createFromReadableStream` to
`createFromFetch`. This allows us to call into the Flight client
immediately without waiting for the `fetch` promise to resolve.

The `_debugInfo` field contains the profiling information. Promises that
are created by Flight already have this info added by React; for any
derived promise created by the router, we need to transfer the Flight
debug info onto the derived promise.

Concretely, we create a derived promise for each route segment contained
in a response. Any nested promises contained with that segment are
passed directly from Flight to React and don't require special
processing.

Author: acdlite

packages/next/src/client/components/router-reducer/create-initial-router-state.test.tsx

@@ -139,6 +139,7 @@ describe('createInitialRouterState', () => {
       cache: expectedCache,
       nextUrl: '/linking',
       previousNextUrl: null,
+      debugInfo: null,
     }
 
     expect(state).toMatchObject(expected)

packages/next/src/client/components/router-reducer/create-initial-router-state.ts

@@ -111,6 +111,7 @@ export function createInitialRouterState({
       (extractPathFromFlightRouterState(initialTree) || location?.pathname) ??
       null,
     previousNextUrl: null,
+    debugInfo: null,
   }
 
   if (process.env.NODE_ENV !== 'development' && location) {
@@ -146,6 +147,7 @@ export function createInitialRouterState({
           prerendered && !process.env.__NEXT_CLIENT_SEGMENT_CACHE
             ? STATIC_STALETIME_MS
             : -1,
+        debugInfo: null,
       },
       tree: initialState.tree,
       prefetchCache: initialState.prefetchCache,

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

@@ -2,7 +2,10 @@
 
 // TODO: Explicitly import from client.browser
 // eslint-disable-next-line import/no-extraneous-dependencies
-import { createFromReadableStream as createFromReadableStreamBrowser } from 'react-server-dom-webpack/client'
+import {
+  createFromReadableStream as createFromReadableStreamBrowser,
+  createFromFetch as createFromFetchBrowser,
+} from 'react-server-dom-webpack/client'
 
 import type {
   FlightRouterState,
@@ -37,6 +40,8 @@ import { urlToUrlWithoutFlightMarker } from '../../route-params'
 
 const createFromReadableStream =
   createFromReadableStreamBrowser as (typeof import('react-server-dom-webpack/client.browser'))['createFromReadableStream']
+const createFromFetch =
+  createFromFetchBrowser as (typeof import('react-server-dom-webpack/client.browser'))['createFromFetch']
 
 let createDebugChannel:
   | typeof import('../../dev/debug-channel').createDebugChannel
@@ -65,6 +70,7 @@ export type FetchServerResponseResult = {
   prerendered: boolean
   postponed: boolean
   staleTime: number
+  debugInfo: Array<any> | null
 }
 
 export type RequestHeaders = {
@@ -91,6 +97,7 @@ function doMpaNavigation(url: string): FetchServerResponseResult {
     prerendered: false,
     postponed: false,
     staleTime: -1,
+    debugInfo: null,
   }
 }
 
@@ -175,10 +182,17 @@ export async function fetchServerResponse(
       }
     }
 
-    const res = await createFetch(
+    // Typically, during a navigation, we decode the response using Flight's
+    // `createFromFetch` API, which accepts a `fetch` promise.
+    // TODO: Remove this check once the old PPR flag is removed
+    const isLegacyPPR =
+      process.env.__NEXT_PPR && !process.env.__NEXT_CACHE_COMPONENTS
+    const shouldImmediatelyDecode = !isLegacyPPR
+    const res = await createFetch<NavigationFlightResponse>(
       url,
       headers,
       fetchPriority,
+      shouldImmediatelyDecode,
       abortController.signal
     )
 
@@ -226,26 +240,37 @@ export async function fetchServerResponse(
       ).waitForWebpackRuntimeHotUpdate()
     }
 
-    // Handle the `fetch` readable stream that can be unwrapped by `React.use`.
-    const flightStream = postponed
-      ? createUnclosingPrefetchStream(res.body)
-      : res.body
-    const response = await (createFromNextReadableStream(
-      flightStream,
-      headers
-    ) as Promise<NavigationFlightResponse>)
+    let flightResponsePromise = res.flightResponse
+    if (flightResponsePromise === null) {
+      // Typically, `createFetch` would have already started decoding the
+      // Flight response. If it hasn't, though, we need to decode it now.
+      // TODO: This should only be reachable if legacy PPR is enabled (i.e. PPR
+      // without Cache Components). Remove this branch once legacy PPR
+      // is deleted.
+      const flightStream = postponed
+        ? createUnclosingPrefetchStream(res.body)
+        : res.body
+      flightResponsePromise =
+        createFromNextReadableStream<NavigationFlightResponse>(
+          flightStream,
+          headers
+        )
+    }
+
+    const flightResponse = await flightResponsePromise
 
-    if (getAppBuildId() !== response.b) {
+    if (getAppBuildId() !== flightResponse.b) {
       return doMpaNavigation(res.url)
     }
 
     return {
-      flightData: normalizeFlightData(response.f),
+      flightData: normalizeFlightData(flightResponse.f),
       canonicalUrl: canonicalUrl,
       couldBeIntercepted: interception,
-      prerendered: response.S,
+      prerendered: flightResponse.S,
       postponed,
       staleTime,
+      debugInfo: flightResponsePromise._debugInfo ?? null,
     }
   } catch (err) {
     if (!abortController.signal.aborted) {
@@ -265,6 +290,7 @@ export async function fetchServerResponse(
       prerendered: false,
       postponed: false,
       staleTime: -1,
+      debugInfo: null,
     }
   }
 }
@@ -274,21 +300,23 @@ export async function fetchServerResponse(
 // the codebase. For example, there's some custom logic for manually following
 // redirects, so "redirected" in this type could be a composite of multiple
 // browser fetch calls; however, this fact should not leak to the caller.
-export type RSCResponse = {
+export type RSCResponse<T> = {
   ok: boolean
   redirected: boolean
   headers: Headers
   body: ReadableStream<Uint8Array> | null
   status: number
   url: string
+  flightResponse: (Promise<T> & { _debugInfo?: Array<any> }) | null
 }
 
-export async function createFetch(
+export async function createFetch<T>(
   url: URL,
   headers: RequestHeaders,
   fetchPriority: 'auto' | 'high' | 'low' | null,
+  shouldImmediatelyDecode: boolean,
   signal?: AbortSignal
-): Promise<RSCResponse> {
+): Promise<RSCResponse<T>> {
   // TODO: In output: "export" mode, the headers do nothing. Omit them (and the
   // cache busting search param) from the request so they're
   // maximally cacheable.
@@ -326,7 +354,21 @@ export async function createFetch(
   // track them separately.
   let fetchUrl = new URL(url)
   setCacheBustingSearchParam(fetchUrl, headers)
-  let browserResponse = await fetch(fetchUrl, fetchOptions)
+  let fetchPromise = fetch(fetchUrl, fetchOptions)
+  // Immediately pass the fetch promise to the Flight client so that the debug
+  // info includes the latency from the client to the server. The internal timer
+  // in React starts as soon as `createFromFetch` is called.
+  //
+  // The only case where we don't do this is during a prefetch, because we have
+  // to do some extra processing of the response stream (see
+  // `createUnclosingPrefetchStream`). But this is fine, because a top-level
+  // prefetch response never blocks a navigation; if it hasn't already been
+  // written into the cache by the time the navigation happens, the router will
+  // go straight to a dynamic request.
+  let flightResponsePromise = shouldImmediatelyDecode
+    ? createFromNextFetch<T>(fetchPromise, headers)
+    : null
+  let browserResponse = await fetchPromise
 
   // If the server responds with a redirect (e.g. 307), and the redirected
   // location does not contain the cache busting search param set in the
@@ -379,9 +421,14 @@ export async function createFetch(
       //
       // Append the cache busting search param to the redirected URL and
       // fetch again.
+      // TODO: We should abort the previous request.
       fetchUrl = new URL(responseUrl)
       setCacheBustingSearchParam(fetchUrl, headers)
-      browserResponse = await fetch(fetchUrl, fetchOptions)
+      fetchPromise = fetch(fetchUrl, fetchOptions)
+      flightResponsePromise = shouldImmediatelyDecode
+        ? createFromNextFetch<T>(fetchPromise, headers)
+        : null
+      browserResponse = await fetchPromise
       // We just performed a manual redirect, so this is now true.
       redirected = true
     }
@@ -392,7 +439,7 @@ export async function createFetch(
   const responseUrl = new URL(browserResponse.url, fetchUrl)
   responseUrl.searchParams.delete(NEXT_RSC_UNION_QUERY)
 
-  const rscResponse: RSCResponse = {
+  const rscResponse: RSCResponse<T> = {
     url: responseUrl.href,
 
     // This is true if any redirects occurred, either automatically by the
@@ -408,22 +455,38 @@ export async function createFetch(
     headers: browserResponse.headers,
     body: browserResponse.body,
     status: browserResponse.status,
+
+    // This is the exact promise returned by `createFromFetch`. It contains
+    // debug information that we need to transfer to any derived promises that
+    // are later rendered by React.
+    flightResponse: flightResponsePromise,
   }
 
   return rscResponse
 }
 
-export function createFromNextReadableStream(
+export function createFromNextReadableStream<T>(
   flightStream: ReadableStream<Uint8Array>,
   requestHeaders: RequestHeaders
-): Promise<unknown> {
+): Promise<T> {
   return createFromReadableStream(flightStream, {
     callServer,
     findSourceMapURL,
     debugChannel: createDebugChannel && createDebugChannel(requestHeaders),
   })
 }
 
+function createFromNextFetch<T>(
+  promiseForResponse: Promise<Response>,
+  requestHeaders: RequestHeaders
+): Promise<T> & { _debugInfo?: Array<any> } {
+  return createFromFetch(promiseForResponse, {
+    callServer,
+    findSourceMapURL,
+    debugChannel: createDebugChannel && createDebugChannel(requestHeaders),
+  })
+}
+
 function createUnclosingPrefetchStream(
   originalFlightStream: ReadableStream<Uint8Array>
 ): ReadableStream<Uint8Array> {

packages/next/src/client/components/router-reducer/handle-mutable.ts

@@ -87,5 +87,6 @@ export function handleMutable(
       : state.tree,
     nextUrl,
     previousNextUrl: previousNextUrl,
+    debugInfo: mutable.collectedDebugInfo ?? null,
   }
 }