[Flight] Wire up async_hooks in Node.js DEV for inspecting Promises (#27840)

This wires up the use of `async_hooks` in the Node build (as well as the
Edge build when a global is available) in DEV mode only. This will be
used to track debug info about what suspended during an RSC pass.

Enabled behind a flag for now.

Author: sebmarkbage

.eslintrc.js

@@ -532,6 +532,7 @@ module.exports = {
     trustedTypes: 'readonly',
     IS_REACT_ACT_ENVIRONMENT: 'readonly',
     AsyncLocalStorage: 'readonly',
+    async_hooks: 'readonly',
     globalThis: 'readonly',
   },
 };

packages/react-server/src/ReactFlightServer.js

@@ -70,6 +70,7 @@ import {
   requestStorage,
   prepareHostDispatcher,
   createHints,
+  initAsyncDebugInfo,
 } from './ReactFlightServerConfig';
 
 import {
@@ -117,6 +118,8 @@ import binaryToComparableString from 'shared/binaryToComparableString';
 
 import {SuspenseException, getSuspendedThenable} from './ReactFlightThenable';
 
+initAsyncDebugInfo();
+
 const ObjectPrototype = Object.prototype;
 
 type JSONValue =

packages/react-server/src/ReactFlightServerConfigDebugNode.js

@@ -0,0 +1,33 @@
+/**
+ * Copyright (c) Meta Platforms, Inc. and affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ *
+ * @flow
+ */
+
+import {createAsyncHook, executionAsyncId} from './ReactFlightServerConfig';
+import {enableAsyncDebugInfo} from 'shared/ReactFeatureFlags';
+
+// Initialize the tracing of async operations.
+// We do this globally since the async work can potentially eagerly
+// start before the first request and once requests start they can interleave.
+// In theory we could enable and disable using a ref count of active requests
+// but given that typically this is just a live server, it doesn't really matter.
+export function initAsyncDebugInfo(): void {
+  if (__DEV__ && enableAsyncDebugInfo) {
+    createAsyncHook({
+      init(asyncId: number, type: string, triggerAsyncId: number): void {
+        // TODO
+      },
+      promiseResolve(asyncId: number): void {
+        // TODO
+        executionAsyncId();
+      },
+      destroy(asyncId: number): void {
+        // TODO
+      },
+    }).enable();
+  }
+}

packages/react-server/src/ReactFlightServerConfigDebugNoop.js

@@ -0,0 +1,11 @@
+/**
+ * Copyright (c) Meta Platforms, Inc. and affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ *
+ * @flow
+ */
+
+// Exported for runtimes that don't support Promise instrumentation for async debugging.
+export function initAsyncDebugInfo(): void {}

packages/react-server/src/forks/ReactFlightServerConfig.custom.js

@@ -11,6 +11,8 @@ import type {Request} from 'react-server/src/ReactFlightServer';
 
 export * from '../ReactFlightServerConfigBundlerCustom';
 
+export * from '../ReactFlightServerConfigDebugNoop';
+
 export type Hints = any;
 export type HintCode = any;
 // eslint-disable-next-line no-unused-vars

packages/react-server/src/forks/ReactFlightServerConfig.dom-browser-esm.js

@@ -16,3 +16,5 @@ export * from 'react-dom-bindings/src/server/ReactFlightServerConfigDOM';
 export const supportsRequestStorage = true;
 export const requestStorage: AsyncLocalStorage<Request> =
   new AsyncLocalStorage();
+
+export * from '../ReactFlightServerConfigDebugNoop';

packages/react-server/src/forks/ReactFlightServerConfig.dom-browser-turbopack.js

@@ -14,3 +14,5 @@ export * from 'react-dom-bindings/src/server/ReactFlightServerConfigDOM';
 
 export const supportsRequestStorage = false;
 export const requestStorage: AsyncLocalStorage<Request> = (null: any);
+
+export * from '../ReactFlightServerConfigDebugNoop';

packages/react-server/src/forks/ReactFlightServerConfig.dom-browser.js

@@ -14,3 +14,5 @@ export * from 'react-dom-bindings/src/server/ReactFlightServerConfigDOM';
 
 export const supportsRequestStorage = false;
 export const requestStorage: AsyncLocalStorage<Request> = (null: any);
+
+export * from '../ReactFlightServerConfigDebugNoop';

packages/react-server/src/forks/ReactFlightServerConfig.dom-bun.js

@@ -14,3 +14,5 @@ export * from 'react-dom-bindings/src/server/ReactFlightServerConfigDOM';
 
 export const supportsRequestStorage = false;
 export const requestStorage: AsyncLocalStorage<Request> = (null: any);
+
+export * from '../ReactFlightServerConfigDebugNoop';

packages/react-server/src/forks/ReactFlightServerConfig.dom-edge-turbopack.js

@@ -16,3 +16,18 @@ export const supportsRequestStorage = typeof AsyncLocalStorage === 'function';
 export const requestStorage: AsyncLocalStorage<Request> = supportsRequestStorage
   ? new AsyncLocalStorage()
   : (null: any);
+
+// We use the Node version but get access to async_hooks from a global.
+import type {HookCallbacks, AsyncHook} from 'async_hooks';
+export const createAsyncHook: HookCallbacks => AsyncHook =
+  typeof async_hooks === 'object'
+    ? async_hooks.createHook
+    : function () {
+        return ({
+          enable() {},
+          disable() {},
+        }: any);
+      };
+export const executionAsyncId: () => number =
+  typeof async_hooks === 'object' ? async_hooks.executionAsyncId : (null: any);
+export * from '../ReactFlightServerConfigDebugNode';

packages/react-server/src/forks/ReactFlightServerConfig.dom-edge.js

@@ -16,3 +16,18 @@ export const supportsRequestStorage = typeof AsyncLocalStorage === 'function';
 export const requestStorage: AsyncLocalStorage<Request> = supportsRequestStorage
   ? new AsyncLocalStorage()
   : (null: any);
+
+// We use the Node version but get access to async_hooks from a global.
+import type {HookCallbacks, AsyncHook} from 'async_hooks';
+export const createAsyncHook: HookCallbacks => AsyncHook =
+  typeof async_hooks === 'object'
+    ? async_hooks.createHook
+    : function () {
+        return ({
+          enable() {},
+          disable() {},
+        }: any);
+      };
+export const executionAsyncId: () => number =
+  typeof async_hooks === 'object' ? async_hooks.executionAsyncId : (null: any);
+export * from '../ReactFlightServerConfigDebugNode';

packages/react-server/src/forks/ReactFlightServerConfig.dom-fb-experimental.js

@@ -14,3 +14,5 @@ export * from 'react-dom-bindings/src/server/ReactFlightServerConfigDOM';
 
 export const supportsRequestStorage = false;
 export const requestStorage: AsyncLocalStorage<Request> = (null: any);
+
+export * from '../ReactFlightServerConfigDebugNoop';

packages/react-server/src/forks/ReactFlightServerConfig.dom-legacy.js

@@ -14,3 +14,5 @@ export * from 'react-dom-bindings/src/server/ReactFlightServerConfigDOM';
 
 export const supportsRequestStorage = false;
 export const requestStorage: AsyncLocalStorage<Request> = (null: any);
+
+export * from '../ReactFlightServerConfigDebugNoop';

packages/react-server/src/forks/ReactFlightServerConfig.dom-node-esm.js

@@ -16,3 +16,6 @@ export * from 'react-dom-bindings/src/server/ReactFlightServerConfigDOM';
 export const supportsRequestStorage = true;
 export const requestStorage: AsyncLocalStorage<Request> =
   new AsyncLocalStorage();
+
+export {createHook as createAsyncHook, executionAsyncId} from 'async_hooks';
+export * from '../ReactFlightServerConfigDebugNode';

packages/react-server/src/forks/ReactFlightServerConfig.dom-node-turbopack.js

@@ -17,3 +17,6 @@ export * from 'react-dom-bindings/src/server/ReactFlightServerConfigDOM';
 export const supportsRequestStorage = true;
 export const requestStorage: AsyncLocalStorage<Request> =
   new AsyncLocalStorage();
+
+export {createHook as createAsyncHook, executionAsyncId} from 'async_hooks';
+export * from '../ReactFlightServerConfigDebugNode';

packages/react-server/src/forks/ReactFlightServerConfig.dom-node.js

@@ -17,3 +17,6 @@ export * from 'react-dom-bindings/src/server/ReactFlightServerConfigDOM';
 export const supportsRequestStorage = true;
 export const requestStorage: AsyncLocalStorage<Request> =
   new AsyncLocalStorage();
+
+export {createHook as createAsyncHook, executionAsyncId} from 'async_hooks';
+export * from '../ReactFlightServerConfigDebugNode';

packages/shared/ReactFeatureFlags.js

@@ -229,6 +229,8 @@ export const enableProfilerNestedUpdatePhase = __PROFILE__;
 // issues in DEV builds.
 export const enableDebugTracing = false;
 
+export const enableAsyncDebugInfo = __EXPERIMENTAL__;
+
 // Track which Fiber(s) schedule render work.
 export const enableUpdaterTracking = __PROFILE__;
 

packages/shared/forks/ReactFeatureFlags.native-fb.js

@@ -29,6 +29,7 @@ export const {
 // The rest of the flags are static for better dead code elimination.
 export const disableModulePatternComponents = true;
 export const enableDebugTracing = false;
+export const enableAsyncDebugInfo = false;
 export const enableSchedulingProfiler = __PROFILE__;
 export const enableProfilerTimer = __PROFILE__;
 export const enableProfilerCommitHooks = __PROFILE__;

packages/shared/forks/ReactFeatureFlags.native-oss.js

@@ -12,6 +12,7 @@ import typeof * as ExportsType from './ReactFeatureFlags.native-oss';
 
 export const debugRenderPhaseSideEffectsForStrictMode = false;
 export const enableDebugTracing = false;
+export const enableAsyncDebugInfo = false;
 export const enableSchedulingProfiler = false;
 export const replayFailedUnitOfWorkWithInvokeGuardedCallback = __DEV__;
 export const enableProfilerTimer = __PROFILE__;

packages/shared/forks/ReactFeatureFlags.test-renderer.js

@@ -12,6 +12,7 @@ import typeof * as ExportsType from './ReactFeatureFlags.test-renderer';
 
 export const debugRenderPhaseSideEffectsForStrictMode = false;
 export const enableDebugTracing = false;
+export const enableAsyncDebugInfo = false;
 export const enableSchedulingProfiler = false;
 export const replayFailedUnitOfWorkWithInvokeGuardedCallback = false;
 export const enableProfilerTimer = __PROFILE__;

packages/shared/forks/ReactFeatureFlags.test-renderer.native.js

@@ -12,6 +12,7 @@ import typeof * as ExportsType from './ReactFeatureFlags.test-renderer';
 
 export const debugRenderPhaseSideEffectsForStrictMode = false;
 export const enableDebugTracing = false;
+export const enableAsyncDebugInfo = false;
 export const enableSchedulingProfiler = false;
 export const replayFailedUnitOfWorkWithInvokeGuardedCallback = false;
 export const enableProfilerTimer = __PROFILE__;

packages/shared/forks/ReactFeatureFlags.test-renderer.www.js

@@ -12,6 +12,7 @@ import typeof * as ExportsType from './ReactFeatureFlags.test-renderer.www';
 
 export const debugRenderPhaseSideEffectsForStrictMode = false;
 export const enableDebugTracing = false;
+export const enableAsyncDebugInfo = false;
 export const enableSchedulingProfiler = false;
 export const replayFailedUnitOfWorkWithInvokeGuardedCallback = false;
 export const enableProfilerTimer = __PROFILE__;

packages/shared/forks/ReactFeatureFlags.www.js

@@ -116,5 +116,7 @@ export const forceConcurrentByDefaultForTesting = false;
 export const useMicrotasksForSchedulingInFabric = false;
 export const passChildrenWhenCloningPersistedNodes = false;
 
+export const enableAsyncDebugInfo = false;
+
 // Flow magic to verify the exports of this file match the original version.
 ((((null: any): ExportsType): FeatureFlagsType): ExportsType);

scripts/flow/environment.js

@@ -281,22 +281,50 @@ declare module 'pg/lib/utils' {
   };
 }
 
-declare class AsyncLocalStorage<T> {
-  disable(): void;
-  getStore(): T | void;
-  run(store: T, callback: (...args: any[]) => void, ...args: any[]): void;
-  enterWith(store: T): void;
-}
-
+// Node
 declare module 'async_hooks' {
   declare class AsyncLocalStorage<T> {
     disable(): void;
     getStore(): T | void;
     run(store: T, callback: (...args: any[]) => void, ...args: any[]): void;
     enterWith(store: T): void;
   }
+  declare interface AsyncResource {}
+  declare function executionAsyncId(): number;
+  declare function executionAsyncResource(): AsyncResource;
+  declare function triggerAsyncId(): number;
+  declare type HookCallbacks = {
+    init?: (
+      asyncId: number,
+      type: string,
+      triggerAsyncId: number,
+      resource: AsyncResource,
+    ) => void,
+    before?: (asyncId: number) => void,
+    after?: (asyncId: number) => void,
+    promiseResolve?: (asyncId: number) => void,
+    destroy?: (asyncId: number) => void,
+  };
+  declare class AsyncHook {
+    enable(): this;
+    disable(): this;
+  }
+  declare function createHook(callbacks: HookCallbacks): AsyncHook;
 }
 
+// Edge
+declare class AsyncLocalStorage<T> {
+  disable(): void;
+  getStore(): T | void;
+  run(store: T, callback: (...args: any[]) => void, ...args: any[]): void;
+  enterWith(store: T): void;
+}
+
+declare var async_hooks: {
+  createHook(callbacks: any): any,
+  executionAsyncId(): number,
+};
+
 declare module 'node:worker_threads' {
   declare class MessageChannel {
     port1: MessagePort;

scripts/rollup/validate/eslintrc.cjs.js

@@ -54,6 +54,7 @@ module.exports = {
 
     // Temp
     AsyncLocalStorage: 'readonly',
+    async_hooks: 'readonly',
 
     // Flight Webpack
     __webpack_chunk_load__: 'readonly',

scripts/rollup/validate/eslintrc.cjs2015.js

@@ -52,6 +52,7 @@ module.exports = {
 
     // Temp
     AsyncLocalStorage: 'readonly',
+    async_hooks: 'readonly',
 
     // Flight Webpack
     __webpack_chunk_load__: 'readonly',

scripts/rollup/validate/eslintrc.esm.js

@@ -54,6 +54,7 @@ module.exports = {
 
     // Temp
     AsyncLocalStorage: 'readonly',
+    async_hooks: 'readonly',
 
     // Flight Webpack
     __webpack_chunk_load__: 'readonly',

scripts/rollup/validate/eslintrc.fb.js

@@ -55,6 +55,7 @@ module.exports = {
 
     // Temp
     AsyncLocalStorage: 'readonly',
+    async_hooks: 'readonly',
 
     // jest
     jest: 'readonly',

scripts/rollup/validate/eslintrc.rn.js

@@ -53,6 +53,7 @@ module.exports = {
 
     // Temp
     AsyncLocalStorage: 'readonly',
+    async_hooks: 'readonly',
 
     // jest
     jest: 'readonly',

scripts/rollup/validate/eslintrc.umd.js

@@ -59,6 +59,7 @@ module.exports = {
 
     // Temp
     AsyncLocalStorage: 'readonly',
+    async_hooks: 'readonly',
 
     // Flight Webpack
     __webpack_chunk_load__: 'readonly',

scripts/shared/inlinedHostConfigs.js

@@ -45,6 +45,7 @@ module.exports = [
       'react-devtools-shared',
       'react-interactions',
       'shared/ReactDOMSharedInternals',
+      'react-server/src/ReactFlightServerConfigDebugNode.js',
     ],
     isFlowTyped: true,
     isServerSupported: true,
@@ -81,6 +82,7 @@ module.exports = [
       'react-devtools-shared',
       'react-interactions',
       'shared/ReactDOMSharedInternals',
+      'react-server/src/ReactFlightServerConfigDebugNode.js',
     ],
     isFlowTyped: true,
     isServerSupported: true,
@@ -117,6 +119,7 @@ module.exports = [
       'react-devtools-shared',
       'react-interactions',
       'shared/ReactDOMSharedInternals',
+      'react-server/src/ReactFlightServerConfigDebugNode.js',
     ],
     isFlowTyped: true,
     isServerSupported: true,
@@ -154,6 +157,7 @@ module.exports = [
       'react-devtools-shared',
       'react-interactions',
       'shared/ReactDOMSharedInternals',
+      'react-server/src/ReactFlightServerConfigDebugNode.js',
     ],
     isFlowTyped: true,
     isServerSupported: true,
@@ -297,6 +301,7 @@ module.exports = [
       'react-devtools-shell',
       'react-devtools-shared',
       'shared/ReactDOMSharedInternals',
+      'react-server/src/ReactFlightServerConfigDebugNode.js',
     ],
     isFlowTyped: true,
     isServerSupported: true,
@@ -330,6 +335,7 @@ module.exports = [
       'react-devtools-shell',
       'react-devtools-shared',
       'shared/ReactDOMSharedInternals',
+      'react-server/src/ReactFlightServerConfigDebugNode.js',
     ],
     isFlowTyped: true,
     isServerSupported: true,
@@ -364,6 +370,7 @@ module.exports = [
       'react-devtools-shared',
       'react-interactions',
       'shared/ReactDOMSharedInternals',
+      'react-server/src/ReactFlightServerConfigDebugNode.js',
     ],
     isFlowTyped: true,
     isServerSupported: true,