[Flight] Source Map Server Actions to their Server Location (#30741)

This uses a similar technique to what we use to generate fake stack
frames for server components. This generates an eval:ed wrapper function
around the Server Reference proxy we create on the client. This wrapper
function gets the original `name` of the action on the server and I also
add a source map if `findSourceMapURL` is defined that points back to
the source of the server function.

For `"use server"` on the server, there's no new API. It just uses the
callsite of `registerServerReference()` on the Server. We can infer the
function name from the actual function on the server and we already have
the `findSourceMapURL` on the client receiving it.

For `"use server"` imported from the client, there's two new options
added to `createServerReference()` (in addition to the optional
[`encodeFormAction`](#27563)). These are only used in DEV mode. The
[`findSourceMapURL`](#29708) option is the same one added in #29708. We
need to pass this these references aren't created in the context of any
specific request but globally. The other weird thing about this case is
that this is actually a case where the compiled environment is the
client so any source maps are the same as for the client layer, so the
environment name here is just `"Client"`.

```diff
  createServerReference(
    id: string,
    callServer: CallServerCallback,
    encodeFormAction?: EncodeFormActionCallback,
+   findSourceMapURL?: FindSourceMapURLCallback, // DEV-only
+   functionName?: string, // DEV-only
  )
```

The key is that we use the location of the
`registerServerReference()`/`createServerReference()` call as the
location of the function. A compiler can either emit those at the same
locations as the original functions or use source maps to have those
segments refer to the original location of the function (or in the case
of a re-export the original location of the re-export is also a fine
approximate). The compiled output must call these directly without a
wrapper function because the wrapper adds a stack frame. I decided
against complicated and fragile dev-only options to skip n number of
frames that would just end up in prod code. The implementation just
skips one frame - our own. Otherwise it'll just point all source mapping
to the wrapper.

We don't have a `"use server"` imported from the client implementation
in the reference implementation/fixture so it's a bit tricky to test
that. In the case of CJS on the server, we just use a runtime instead of
compiler so it's tricky to source map those appropriately. We can
implement it for ESM on the server which is the main thing we're testing
in the fixture. It's easier in a real implementation where all the
compilation is just one pass. It's a little tricky since we have to
parse and append to other source maps but I'd like to do that as a
follow up. Or maybe that's just an exercise for the reader.

You can right click an action and click "Go to Definition".

<img width="1323" alt="Screenshot 2024-08-17 at 6 04 27 PM"
src="https://github.com/user-attachments/assets/94d379b3-8871-4671-a20d-cbf9cfbc2c6e">

For now they simply don't point to the right place but you can still
jump to the right file in the fixture:

<img width="1512" alt="Screenshot 2024-08-17 at 5 58 40 PM"
src="https://github.com/user-attachments/assets/1ea5d665-e25a-44ca-9515-481dd3c5c2fe">

In Firefox/Safari given that the location doesn't exist in the source
map yet, the browser refuses to open the file. Where as Chrome does
nearest (last) line.

packages/react-client/src/ReactFlightClient.js

@@ -13,6 +13,7 @@ import type {
   ReactComponentInfo,
   ReactAsyncInfo,
   ReactStackTrace,
+  ReactCallSite,
 } from 'shared/ReactTypes';
 import type {LazyComponent} from 'react/src/ReactLazy';
 
@@ -59,7 +60,7 @@ import {
   bindToConsole,
 } from './ReactFlightClientConfig';
 
-import {registerServerReference} from './ReactFlightReplyClient';
+import {createBoundServerReference} from './ReactFlightReplyClient';
 
 import {readTemporaryReference} from './ReactFlightTemporaryReferences';
 
@@ -1001,30 +1002,20 @@ function waitForReference<T>(
 
 function createServerReferenceProxy<A: Iterable<any>, T>(
   response: Response,
-  metaData: {id: any, bound: null | Thenable<Array<any>>},
+  metaData: {
+    id: any,
+    bound: null | Thenable<Array<any>>,
+    name?: string, // DEV-only
+    env?: string, // DEV-only
+    location?: ReactCallSite, // DEV-only
+  },
 ): (...A) => Promise<T> {
-  const callServer = response._callServer;
-  const proxy = function (): Promise<T> {
-    // $FlowFixMe[method-unbinding]
-    const args = Array.prototype.slice.call(arguments);
-    const p = metaData.bound;
-    if (!p) {
-      return callServer(metaData.id, args);
-    }
-    if (p.status === INITIALIZED) {
-      const bound = p.value;
-      return callServer(metaData.id, bound.concat(args));
-    }
-    // Since this is a fake Promise whose .then doesn't chain, we have to wrap it.
-    // TODO: Remove the wrapper once that's fixed.
-    return ((Promise.resolve(p): any): Promise<Array<any>>).then(
-      function (bound) {
-        return callServer(metaData.id, bound.concat(args));
-      },
-    );
-  };
-  registerServerReference(proxy, metaData, response._encodeFormAction);
-  return proxy;
+  return createBoundServerReference(
+    metaData,
+    response._callServer,
+    response._encodeFormAction,
+    __DEV__ ? response._debugFindSourceMapURL : undefined,
+  );
 }
 
 function getOutlinedModel<T>(

packages/react-client/src/ReactFlightReplyClient.js

@@ -13,6 +13,7 @@ import type {
   FulfilledThenable,
   RejectedThenable,
   ReactCustomFormAction,
+  ReactCallSite,
 } from 'shared/ReactTypes';
 import type {LazyComponent} from 'react/src/ReactLazy';
 import type {TemporaryReferenceSet} from './ReactFlightTemporaryReferences';
@@ -1023,7 +1024,99 @@ function isSignatureEqual(
   }
 }
 
-export function registerServerReference(
+let fakeServerFunctionIdx = 0;
+
+function createFakeServerFunction<A: Iterable<any>, T>(
+  name: string,
+  filename: string,
+  sourceMap: null | string,
+  line: number,
+  col: number,
+  environmentName: string,
+  innerFunction: (...A) => Promise<T>,
+): (...A) => Promise<T> {
+  // This creates a fake copy of a Server Module. It represents the Server Action on the server.
+  // We use an eval so we can source map it to the original location.
+
+  const comment =
+    '/* This module is a proxy to a Server Action. Turn on Source Maps to see the server source. */';
+
+  if (!name) {
+    // An eval:ed function with no name gets the name "eval". We give it something more descriptive.
+    name = '<anonymous>';
+  }
+  const encodedName = JSON.stringify(name);
+  // We generate code where both the beginning of the function and its parenthesis is at the line
+  // and column of the server executed code. We use a method form since that lets us name it
+  // anything we want and because the beginning of the function and its parenthesis is the same
+  // column. Because Chrome inspects the location of the parenthesis and Firefox inspects the
+  // location of the beginning of the function. By not using a function expression we avoid the
+  // ambiguity.
+  let code;
+  if (line <= 1) {
+    const minSize = encodedName.length + 7;
+    code =
+      's=>({' +
+      encodedName +
+      ' '.repeat(col < minSize ? 0 : col - minSize) +
+      ':' +
+      '(...args) => s(...args)' +
+      '})\n' +
+      comment;
+  } else {
+    code =
+      comment +
+      '\n'.repeat(line - 2) +
+      'server=>({' +
+      encodedName +
+      ':\n' +
+      ' '.repeat(col < 1 ? 0 : col - 1) +
+      // The function body can get printed so we make it look nice.
+      // This "calls the server with the arguments".
+      '(...args) => server(...args)' +
+      '})';
+  }
+
+  if (filename.startsWith('/')) {
+    // If the filename starts with `/` we assume that it is a file system file
+    // rather than relative to the current host. Since on the server fully qualified
+    // stack traces use the file path.
+    // TODO: What does this look like on Windows?
+    filename = 'file://' + filename;
+  }
+
+  if (sourceMap) {
+    // We use the prefix rsc://React/ to separate these from other files listed in
+    // the Chrome DevTools. We need a "host name" and not just a protocol because
+    // otherwise the group name becomes the root folder. Ideally we don't want to
+    // show these at all but there's two reasons to assign a fake URL.
+    // 1) A printed stack trace string needs a unique URL to be able to source map it.
+    // 2) If source maps are disabled or fails, you should at least be able to tell
+    //    which file it was.
+    code +=
+      '\n//# sourceURL=rsc://React/' +
+      encodeURIComponent(environmentName) +
+      '/' +
+      filename +
+      '?s' + // We add an extra s here to distinguish from the fake stack frames
+      fakeServerFunctionIdx++;
+    code += '\n//# sourceMappingURL=' + sourceMap;
+  } else if (filename) {
+    code += '\n//# sourceURL=' + filename;
+  }
+
+  try {
+    // Eval a factory and then call it to create a closure over the inner function.
+    // eslint-disable-next-line no-eval
+    return (0, eval)(code)(innerFunction)[name];
+  } catch (x) {
+    // If eval fails, such as if in an environment that doesn't support it,
+    // we fallback to just returning the inner function.
+    return innerFunction;
+  }
+}
+
+function registerServerReference(
   proxy: any,
   reference: {id: ServerReferenceId, bound: null | Thenable<Array<any>>},
   encodeFormAction: void | EncodeFormActionCallback,
@@ -1098,16 +1191,163 @@ function bind(this: Function): Function {
   return newFn;
 }
 
+export type FindSourceMapURLCallback = (
+  fileName: string,
+  environmentName: string,
+) => null | string;
+
+export function createBoundServerReference<A: Iterable<any>, T>(
+  metaData: {
+    id: ServerReferenceId,
+    bound: null | Thenable<Array<any>>,
+    name?: string, // DEV-only
+    env?: string, // DEV-only
+    location?: ReactCallSite, // DEV-only
+  },
+  callServer: CallServerCallback,
+  encodeFormAction?: EncodeFormActionCallback,
+  findSourceMapURL?: FindSourceMapURLCallback, // DEV-only
+): (...A) => Promise<T> {
+  const id = metaData.id;
+  const bound = metaData.bound;
+  let action = function (): Promise<T> {
+    // $FlowFixMe[method-unbinding]
+    const args = Array.prototype.slice.call(arguments);
+    const p = bound;
+    if (!p) {
+      return callServer(id, args);
+    }
+    if (p.status === 'fulfilled') {
+      const boundArgs = p.value;
+      return callServer(id, boundArgs.concat(args));
+    }
+    // Since this is a fake Promise whose .then doesn't chain, we have to wrap it.
+    // TODO: Remove the wrapper once that's fixed.
+    return ((Promise.resolve(p): any): Promise<Array<any>>).then(
+      function (boundArgs) {
+        return callServer(id, boundArgs.concat(args));
+      },
+    );
+  };
+  if (__DEV__) {
+    const location = metaData.location;
+    if (location) {
+      const functionName = metaData.name || '';
+      const [, filename, line, col] = location;
+      const env = metaData.env || 'Server';
+      const sourceMap =
+        findSourceMapURL == null ? null : findSourceMapURL(filename, env);
+      action = createFakeServerFunction(
+        functionName,
+        filename,
+        sourceMap,
+        line,
+        col,
+        env,
+        action,
+      );
+    }
+  }
+  registerServerReference(action, {id, bound}, encodeFormAction);
+  return action;
+}
+
+// This matches either of these V8 formats.
+//     at name (filename:0:0)
+//     at filename:0:0
+//     at async filename:0:0
+const v8FrameRegExp =
+  /^ {3} at (?:(.+) \((.+):(\d+):(\d+)\)|(?:async )?(.+):(\d+):(\d+))$/;
+// This matches either of these JSC/SpiderMonkey formats.
+// name@filename:0:0
+// filename:0:0
+const jscSpiderMonkeyFrameRegExp = /(?:(.*)@)?(.*):(\d+):(\d+)/;
+
+function parseStackLocation(error: Error): null | ReactCallSite {
+  // This parsing is special in that we know that the calling function will always
+  // be a module that initializes the server action. We also need this part to work
+  // cross-browser so not worth a Config. It's DEV only so not super code size
+  // sensitive but also a non-essential feature.
+  let stack = error.stack;
+  if (stack.startsWith('Error: react-stack-top-frame\n')) {
+    // V8's default formatting prefixes with the error message which we
+    // don't want/need.
+    stack = stack.slice(29);
+  }
+  const endOfFirst = stack.indexOf('\n');
+  let secondFrame;
+  if (endOfFirst !== -1) {
+    // Skip the first frame.
+    const endOfSecond = stack.indexOf('\n', endOfFirst + 1);
+    if (endOfSecond === -1) {
+      secondFrame = stack.slice(endOfFirst + 1);
+    } else {
+      secondFrame = stack.slice(endOfFirst + 1, endOfSecond);
+    }
+  } else {
+    secondFrame = stack;
+  }
+
+  let parsed = v8FrameRegExp.exec(secondFrame);
+  if (!parsed) {
+    parsed = jscSpiderMonkeyFrameRegExp.exec(secondFrame);
+    if (!parsed) {
+      return null;
+    }
+  }
+
+  let name = parsed[1] || '';
+  if (name === '<anonymous>') {
+    name = '';
+  }
+  let filename = parsed[2] || parsed[5] || '';
+  if (filename === '<anonymous>') {
+    filename = '';
+  }
+  const line = +(parsed[3] || parsed[6]);
+  const col = +(parsed[4] || parsed[7]);
+
+  return [name, filename, line, col];
+}
+
 export function createServerReference<A: Iterable<any>, T>(
   id: ServerReferenceId,
   callServer: CallServerCallback,
   encodeFormAction?: EncodeFormActionCallback,
+  findSourceMapURL?: FindSourceMapURLCallback, // DEV-only
+  functionName?: string,
 ): (...A) => Promise<T> {
-  const proxy = function (): Promise<T> {
+  let action = function (): Promise<T> {
     // $FlowFixMe[method-unbinding]
     const args = Array.prototype.slice.call(arguments);
     return callServer(id, args);
   };
-  registerServerReference(proxy, {id, bound: null}, encodeFormAction);
-  return proxy;
+  if (__DEV__) {
+    // Let's see if we can find a source map for the file which contained the
+    // server action. We extract it from the runtime so that it's resilient to
+    // multiple passes of compilation as long as we can find the final source map.
+    const location = parseStackLocation(new Error('react-stack-top-frame'));
+    if (location !== null) {
+      const [, filename, line, col] = location;
+      // While the environment that the Server Reference points to can be
+      // in any environment, what matters here is where the compiled source
+      // is from and that's in the currently executing environment. We hard
+      // code that as the value "Client" in case the findSourceMapURL helper
+      // needs it.
+      const env = 'Client';
+      const sourceMap =
+        findSourceMapURL == null ? null : findSourceMapURL(filename, env);
+      action = createFakeServerFunction(
+        functionName || '',
+        filename,
+        sourceMap,
+        line,
+        col,
+        env,
+        action,
+      );
+    }
+  }
+  registerServerReference(action, {id, bound: null}, encodeFormAction);
+  return action;
 }

packages/react-server-dom-esm/src/ReactFlightESMReferences.js

@@ -13,6 +13,7 @@ export type ServerReference<T: Function> = T & {
   $$typeof: symbol,
   $$id: string,
   $$bound: null | Array<ReactClientValue>,
+  $$location?: Error,
 };
 
 // eslint-disable-next-line no-unused-vars
@@ -68,10 +69,30 @@ export function registerServerReference<T: Function>(
   id: string,
   exportName: string,
 ): ServerReference<T> {
-  return Object.defineProperties((reference: any), {
-    $$typeof: {value: SERVER_REFERENCE_TAG},
-    $$id: {value: id + '#' + exportName, configurable: true},
-    $$bound: {value: null, configurable: true},
-    bind: {value: bind, configurable: true},
-  });
+  const $$typeof = {value: SERVER_REFERENCE_TAG};
+  const $$id = {
+    value: id + '#' + exportName,
+    configurable: true,
+  };
+  const $$bound = {value: null, configurable: true};
+  return Object.defineProperties(
+    (reference: any),
+    __DEV__
+      ? {
+          $$typeof,
+          $$id,
+          $$bound,
+          $$location: {
+            value: Error('react-stack-top-frame'),
+            configurable: true,
+          },
+          bind: {value: bind, configurable: true},
+        }
+      : {
+          $$typeof,
+          $$id,
+          $$bound,
+          bind: {value: bind, configurable: true},
+        },
+  );
 }

packages/react-server-dom-esm/src/server/ReactFlightServerConfigESMBundler.js

@@ -70,3 +70,10 @@ export function getServerReferenceBoundArguments<T>(
 ): null | Array<ReactClientValue> {
   return serverReference.$$bound;
 }
+
+export function getServerReferenceLocation<T>(
+  config: ClientManifest,
+  serverReference: ServerReference<T>,
+): void | Error {
+  return serverReference.$$location;
+}

packages/react-server-dom-turbopack/src/ReactFlightTurbopackReferences.js

@@ -13,6 +13,7 @@ export type ServerReference<T: Function> = T & {
   $$typeof: symbol,
   $$id: string,
   $$bound: null | Array<ReactClientValue>,
+  $$location?: Error,
 };
 
 // eslint-disable-next-line no-unused-vars
@@ -81,15 +82,32 @@ export function registerServerReference<T: Function>(
   id: string,
   exportName: null | string,
 ): ServerReference<T> {
-  return Object.defineProperties((reference: any), {
-    $$typeof: {value: SERVER_REFERENCE_TAG},
-    $$id: {
-      value: exportName === null ? id : id + '#' + exportName,
-      configurable: true,
-    },
-    $$bound: {value: null, configurable: true},
-    bind: {value: bind, configurable: true},
-  });
+  const $$typeof = {value: SERVER_REFERENCE_TAG};
+  const $$id = {
+    value: exportName === null ? id : id + '#' + exportName,
+    configurable: true,
+  };
+  const $$bound = {value: null, configurable: true};
+  return Object.defineProperties(
+    (reference: any),
+    __DEV__
+      ? {
+          $$typeof,
+          $$id,
+          $$bound,
+          $$location: {
+            value: Error('react-stack-top-frame'),
+            configurable: true,
+          },
+          bind: {value: bind, configurable: true},
+        }
+      : {
+          $$typeof,
+          $$id,
+          $$bound,
+          bind: {value: bind, configurable: true},
+        },
+  );
 }
 
 const PROMISE_PROTOTYPE = Promise.prototype;

packages/react-server-dom-turbopack/src/server/ReactFlightServerConfigTurbopackBundler.js

@@ -91,3 +91,10 @@ export function getServerReferenceBoundArguments<T>(
 ): null | Array<ReactClientValue> {
   return serverReference.$$bound;
 }
+
+export function getServerReferenceLocation<T>(
+  config: ClientManifest,
+  serverReference: ServerReference<T>,
+): void | Error {
+  return serverReference.$$location;
+}

packages/react-server-dom-webpack/src/ReactFlightWebpackReferences.js

@@ -13,6 +13,7 @@ export type ServerReference<T: Function> = T & {
   $$typeof: symbol,
   $$id: string,
   $$bound: null | Array<ReactClientValue>,
+  $$location?: Error,
 };
 
 // eslint-disable-next-line no-unused-vars
@@ -89,15 +90,32 @@ export function registerServerReference<T: Function>(
   id: string,
   exportName: null | string,
 ): ServerReference<T> {
-  return Object.defineProperties((reference: any), {
-    $$typeof: {value: SERVER_REFERENCE_TAG},
-    $$id: {
-      value: exportName === null ? id : id + '#' + exportName,
-      configurable: true,
-    },
-    $$bound: {value: null, configurable: true},
-    bind: {value: bind, configurable: true},
-  });
+  const $$typeof = {value: SERVER_REFERENCE_TAG};
+  const $$id = {
+    value: exportName === null ? id : id + '#' + exportName,
+    configurable: true,
+  };
+  const $$bound = {value: null, configurable: true};
+  return Object.defineProperties(
+    (reference: any),
+    __DEV__
+      ? {
+          $$typeof,
+          $$id,
+          $$bound,
+          $$location: {
+            value: Error('react-stack-top-frame'),
+            configurable: true,
+          },
+          bind: {value: bind, configurable: true},
+        }
+      : {
+          $$typeof,
+          $$id,
+          $$bound,
+          bind: {value: bind, configurable: true},
+        },
+  );
 }
 
 const PROMISE_PROTOTYPE = Promise.prototype;

packages/react-server-dom-webpack/src/__tests__/ReactFlightDOMBrowser-test.js

@@ -1393,9 +1393,21 @@ describe('ReactFlightDOMBrowser', () => {
           const body = await ReactServerDOMClient.encodeReply(args);
           return callServer(ref, body);
         },
+        undefined,
+        undefined,
+        'upper',
       ),
     };
 
+    expect(ServerModuleBImportedOnClient.upper.name).toBe(
+      __DEV__ ? 'upper' : 'action',
+    );
+    if (__DEV__) {
+      expect(ServerModuleBImportedOnClient.upper.toString()).toBe(
+        '(...args) => server(...args)',
+      );
+    }
+
     function Client({action}) {
       // Client side pass a Server Reference into an action.
       actionProxy = text => action(ServerModuleBImportedOnClient.upper, text);

packages/react-server-dom-webpack/src/server/ReactFlightServerConfigWebpackBundler.js

@@ -91,3 +91,10 @@ export function getServerReferenceBoundArguments<T>(
 ): null | Array<ReactClientValue> {
   return serverReference.$$bound;
 }
+
+export function getServerReferenceLocation<T>(
+  config: ClientManifest,
+  serverReference: ServerReference<T>,
+): void | Error {
+  return serverReference.$$location;
+}

packages/react-server/src/ReactFlightServer.js

@@ -64,6 +64,7 @@ import type {
   ReactComponentInfo,
   ReactAsyncInfo,
   ReactStackTrace,
+  ReactCallSite,
 } from 'shared/ReactTypes';
 import type {ReactElement} from 'shared/ReactElementType';
 import type {LazyComponent} from 'react/src/ReactLazy';
@@ -72,6 +73,7 @@ import {
   resolveClientReferenceMetadata,
   getServerReferenceId,
   getServerReferenceBoundArguments,
+  getServerReferenceLocation,
   getClientReferenceKey,
   isClientReference,
   isServerReference,
@@ -1955,17 +1957,47 @@ function serializeServerReference(
     return serializeServerReferenceID(existingId);
   }
 
-  const bound: null | Array<any> = getServerReferenceBoundArguments(
+  const boundArgs: null | Array<any> = getServerReferenceBoundArguments(
     request.bundlerConfig,
     serverReference,
   );
+  const bound = boundArgs === null ? null : Promise.resolve(boundArgs);
+  const id = getServerReferenceId(request.bundlerConfig, serverReference);
+
+  let location: null | ReactCallSite = null;
+  if (__DEV__) {
+    const error = getServerReferenceLocation(
+      request.bundlerConfig,
+      serverReference,
+    );
+    if (error) {
+      const frames = parseStackTrace(error, 1);
+      if (frames.length > 0) {
+        location = frames[0];
+      }
+    }
+  }
+
   const serverReferenceMetadata: {
     id: ServerReferenceId,
     bound: null | Promise<Array<any>>,
-  } = {
-    id: getServerReferenceId(request.bundlerConfig, serverReference),
-    bound: bound ? Promise.resolve(bound) : null,
-  };
+    name?: string, // DEV-only
+    env?: string, // DEV-only
+    location?: ReactCallSite, // DEV-only
+  } =
+    __DEV__ && location !== null
+      ? {
+          id,
+          bound,
+          name:
+            typeof serverReference === 'function' ? serverReference.name : '',
+          env: (0, request.environmentName)(),
+          location,
+        }
+      : {
+          id,
+          bound,
+        };
   const metadataId = outlineModel(request, serverReferenceMetadata);
   writtenServerReferences.set(serverReference, metadataId);
   return serializeServerReferenceID(metadataId);

packages/react-server/src/ReactFlightServerConfigBundlerCustom.js

@@ -23,3 +23,4 @@ export const resolveClientReferenceMetadata =
 export const getServerReferenceId = $$$config.getServerReferenceId;
 export const getServerReferenceBoundArguments =
   $$$config.getServerReferenceBoundArguments;
+export const getServerReferenceLocation = $$$config.getServerReferenceLocation;

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

@@ -90,3 +90,10 @@ export function getServerReferenceBoundArguments<T>(
       'Use a fixed URL for any forms instead.',
   );
 }
+
+export function getServerReferenceLocation<T>(
+  config: ClientManifest,
+  serverReference: ServerReference<T>,
+): void {
+  return undefined;
+}