Improve Error Messages when Access Client References (#26059)

This renames Module References to Client References, since they are in
the server->client direction.

I also changed the Proxies exposed from the `node-register` loader to
provide better error messages. Ideally, some of this should be
replicated in the ESM loader too but neither are the source of truth.
We'll replicate this in the static form in the Next.js loaders. cc
@huozhi @shuding

- All references are now functions so that when you call them on the
server, we can yield a better error message.
- References that are themselves already referring to an export name are
now proxies that error when you dot into them.
- `use(...)` can now be used on a client reference to unwrap it server
side and then pass a reference to the awaited value.

Author: sebmarkbage

packages/react-client/src/ReactFlightClient.js

@@ -11,15 +11,15 @@ import type {Thenable} from 'shared/ReactTypes';
 import type {LazyComponent} from 'react/src/ReactLazy';
 
 import type {
-  ModuleReference,
+  ClientReference,
   ModuleMetaData,
   UninitializedModel,
   Response,
   BundlerConfig,
 } from './ReactFlightClientHostConfig';
 
 import {
-  resolveModuleReference,
+  resolveClientReference,
   preloadModule,
   requireModule,
   parseModel,
@@ -67,7 +67,7 @@ type ResolvedModelChunk<T> = {
 };
 type ResolvedModuleChunk<T> = {
   status: 'resolved_module',
-  value: ModuleReference<T>,
+  value: ClientReference<T>,
   reason: null,
   _response: Response,
   then(resolve: (T) => mixed, reject: (mixed) => mixed): void,
@@ -262,7 +262,7 @@ function createResolvedModelChunk<T>(
 
 function createResolvedModuleChunk<T>(
   response: Response,
-  value: ModuleReference<T>,
+  value: ClientReference<T>,
 ): ResolvedModuleChunk<T> {
   // $FlowFixMe Flow doesn't support functions as constructors
   return new Chunk(RESOLVED_MODULE, value, null, response);
@@ -293,7 +293,7 @@ function resolveModelChunk<T>(
 
 function resolveModuleChunk<T>(
   chunk: SomeChunk<T>,
-  value: ModuleReference<T>,
+  value: ClientReference<T>,
 ): void {
   if (chunk.status !== PENDING && chunk.status !== BLOCKED) {
     // We already resolved. We didn't expect to see this.
@@ -589,7 +589,7 @@ export function resolveModule(
   const chunks = response._chunks;
   const chunk = chunks.get(id);
   const moduleMetaData: ModuleMetaData = parseModel(response, model);
-  const moduleReference = resolveModuleReference(
+  const moduleReference = resolveClientReference(
     response._bundlerConfig,
     moduleMetaData,
   );

packages/react-client/src/__tests__/ReactFlight-test.js

@@ -91,11 +91,16 @@ describe('ReactFlight', () => {
     };
   });
 
-  function moduleReference(value) {
-    return {
-      $$typeof: Symbol.for('react.module.reference'),
-      value: value,
-    };
+  function clientReference(value) {
+    return Object.defineProperties(
+      function() {
+        throw new Error('Cannot call a client function from the server.');
+      },
+      {
+        $$typeof: {value: Symbol.for('react.client.reference')},
+        value: {value: value},
+      },
+    );
   }
 
   it('can render a Server Component', async () => {
@@ -136,7 +141,7 @@ describe('ReactFlight', () => {
         </span>
       );
     }
-    const User = moduleReference(UserClient);
+    const User = clientReference(UserClient);
 
     function Greeting({firstName, lastName}) {
       return <User greeting="Hello" name={firstName + ' ' + lastName} />;
@@ -327,7 +332,7 @@ describe('ReactFlight', () => {
       return <div>I am client</div>;
     }
 
-    const ClientComponentReference = moduleReference(ClientComponent);
+    const ClientComponentReference = clientReference(ClientComponent);
 
     let load = null;
     const loadClientComponentReference = () => {
@@ -369,7 +374,7 @@ describe('ReactFlight', () => {
     function ClientImpl({children}) {
       return children;
     }
-    const Client = moduleReference(ClientImpl);
+    const Client = clientReference(ClientImpl);
 
     function EventHandlerProp() {
       return (
@@ -488,7 +493,7 @@ describe('ReactFlight', () => {
       );
     }
 
-    const ClientComponentReference = moduleReference(ClientComponent);
+    const ClientComponentReference = clientReference(ClientComponent);
 
     function Server() {
       return (
@@ -576,7 +581,7 @@ describe('ReactFlight', () => {
     function ClientImpl({value}) {
       return <div>{value}</div>;
     }
-    const Client = moduleReference(ClientImpl);
+    const Client = clientReference(ClientImpl);
     expect(() => {
       const transport = ReactNoopFlightServer.render(
         <Client value={new Date()} />,
@@ -593,7 +598,7 @@ describe('ReactFlight', () => {
     function ClientImpl({children}) {
       return <div>{children}</div>;
     }
-    const Client = moduleReference(ClientImpl);
+    const Client = clientReference(ClientImpl);
     expect(() => {
       const transport = ReactNoopFlightServer.render(
         <Client>Current date: {new Date()}</Client>,
@@ -612,7 +617,7 @@ describe('ReactFlight', () => {
     function ClientImpl({value}) {
       return <div>{value}</div>;
     }
-    const Client = moduleReference(ClientImpl);
+    const Client = clientReference(ClientImpl);
     expect(() => {
       const transport = ReactNoopFlightServer.render(<Client value={Math} />);
       ReactNoopFlightClient.read(transport);
@@ -629,7 +634,7 @@ describe('ReactFlight', () => {
     function ClientImpl({value}) {
       return <div>{value}</div>;
     }
-    const Client = moduleReference(ClientImpl);
+    const Client = clientReference(ClientImpl);
     expect(() => {
       const transport = ReactNoopFlightServer.render(
         <Client value={{[Symbol.iterator]: {}}} />,
@@ -646,7 +651,7 @@ describe('ReactFlight', () => {
     function ClientImpl({value}) {
       return <div>{value}</div>;
     }
-    const Client = moduleReference(ClientImpl);
+    const Client = clientReference(ClientImpl);
     expect(() => {
       const transport = ReactNoopFlightServer.render(
         <Client value={{hello: Math, title: <h1>hi</h1>}} />,
@@ -665,7 +670,7 @@ describe('ReactFlight', () => {
     function ClientImpl({value}) {
       return <div>{value}</div>;
     }
-    const Client = moduleReference(ClientImpl);
+    const Client = clientReference(ClientImpl);
     expect(() => {
       const transport = ReactNoopFlightServer.render(
         <Client
@@ -702,6 +707,20 @@ describe('ReactFlight', () => {
     );
   });
 
+  it('should warn in DEV if a a client reference is passed to useContext()', () => {
+    const Context = React.createContext();
+    const ClientContext = clientReference(Context);
+    function ServerComponent() {
+      return React.useContext(ClientContext);
+    }
+    expect(() => {
+      const transport = ReactNoopFlightServer.render(<ServerComponent />);
+      ReactNoopFlightClient.read(transport);
+    }).toErrorDev('Cannot read a Client Context from a Server Component.', {
+      withoutStack: true,
+    });
+  });
+
   describe('Hooks', () => {
     function DivWithId({children}) {
       const id = React.useId();
@@ -776,7 +795,7 @@ describe('ReactFlight', () => {
         );
       }
 
-      const ClientDoublerModuleRef = moduleReference(ClientDoubler);
+      const ClientDoublerModuleRef = clientReference(ClientDoubler);
 
       const transport = ReactNoopFlightServer.render(<App />);
       expect(Scheduler).toHaveYielded([]);
@@ -1000,7 +1019,7 @@ describe('ReactFlight', () => {
         return <span>{context}</span>;
       }
 
-      const Bar = moduleReference(ClientBar);
+      const Bar = clientReference(ClientBar);
 
       function Foo() {
         return (
@@ -1077,7 +1096,7 @@ describe('ReactFlight', () => {
         return <div>{value}</div>;
       }
 
-      const Baz = moduleReference(ClientBaz);
+      const Baz = clientReference(ClientBaz);
 
       function Bar() {
         return (

packages/react-client/src/forks/ReactFlightClientHostConfig.custom.js

@@ -28,8 +28,8 @@ declare var $$$hostConfig: any;
 export type Response = any;
 export opaque type BundlerConfig = mixed;
 export opaque type ModuleMetaData = mixed;
-export opaque type ModuleReference<T> = mixed; // eslint-disable-line no-unused-vars
-export const resolveModuleReference = $$$hostConfig.resolveModuleReference;
+export opaque type ClientReference<T> = mixed; // eslint-disable-line no-unused-vars
+export const resolveClientReference = $$$hostConfig.resolveClientReference;
 export const preloadModule = $$$hostConfig.preloadModule;
 export const requireModule = $$$hostConfig.requireModule;
 

packages/react-noop-renderer/src/ReactNoopFlightClient.js

@@ -22,7 +22,7 @@ type Source = Array<string>;
 
 const {createResponse, processStringChunk, getRoot, close} = ReactFlightClient({
   supportsBinaryStreams: false,
-  resolveModuleReference(bundlerConfig: null, idx: string) {
+  resolveClientReference(bundlerConfig: null, idx: string) {
     return idx;
   },
   preloadModule(idx: string) {},

packages/react-noop-renderer/src/ReactNoopFlightServer.js

@@ -48,10 +48,10 @@ const ReactNoopFlightServer = ReactFlightServer({
   clonePrecomputedChunk(chunk: string): string {
     return chunk;
   },
-  isModuleReference(reference: Object): boolean {
-    return reference.$$typeof === Symbol.for('react.module.reference');
+  isClientReference(reference: Object): boolean {
+    return reference.$$typeof === Symbol.for('react.client.reference');
   },
-  getModuleKey(reference: Object): Object {
+  getClientReferenceKey(reference: Object): Object {
     return reference;
   },
   resolveModuleMetaData(

packages/react-server-dom-relay/src/ReactFlightDOMRelayClientHostConfig.js

@@ -13,7 +13,7 @@ import type {JSResourceReference} from 'JSResourceReference';
 
 import type {ModuleMetaData} from 'ReactFlightDOMRelayClientIntegration';
 
-export type ModuleReference<T> = JSResourceReference<T>;
+export type ClientReference<T> = JSResourceReference<T>;
 
 import {
   parseModelString,
@@ -25,7 +25,7 @@ export {
   requireModule,
 } from 'ReactFlightDOMRelayClientIntegration';
 
-import {resolveModuleReference as resolveModuleReferenceImpl} from 'ReactFlightDOMRelayClientIntegration';
+import {resolveClientReference as resolveClientReferenceImpl} from 'ReactFlightDOMRelayClientIntegration';
 
 import isArray from 'shared/isArray';
 
@@ -37,11 +37,11 @@ export type UninitializedModel = JSONValue;
 
 export type Response = ResponseBase;
 
-export function resolveModuleReference<T>(
+export function resolveClientReference<T>(
   bundlerConfig: BundlerConfig,
   moduleData: ModuleMetaData,
-): ModuleReference<T> {
-  return resolveModuleReferenceImpl(moduleData);
+): ClientReference<T> {
+  return resolveClientReferenceImpl(moduleData);
 }
 
 // $FlowFixMe[missing-local-annot]

packages/react-server-dom-relay/src/ReactFlightDOMRelayServerHostConfig.js

@@ -17,7 +17,7 @@ import JSResourceReferenceImpl from 'JSResourceReferenceImpl';
 import hasOwnProperty from 'shared/hasOwnProperty';
 import isArray from 'shared/isArray';
 
-export type ModuleReference<T> = JSResourceReference<T>;
+export type ClientReference<T> = JSResourceReference<T>;
 
 import type {
   Destination,
@@ -39,21 +39,23 @@ export type {
   ModuleMetaData,
 } from 'ReactFlightDOMRelayServerIntegration';
 
-export function isModuleReference(reference: Object): boolean {
+export function isClientReference(reference: Object): boolean {
   return reference instanceof JSResourceReferenceImpl;
 }
 
-export type ModuleKey = ModuleReference<any>;
+export type ClientReferenceKey = ClientReference<any>;
 
-export function getModuleKey(reference: ModuleReference<any>): ModuleKey {
+export function getClientReferenceKey(
+  reference: ClientReference<any>,
+): ClientReferenceKey {
   // We use the reference object itself as the key because we assume the
   // object will be cached by the bundler runtime.
   return reference;
 }
 
 export function resolveModuleMetaData<T>(
   config: BundlerConfig,
-  resource: ModuleReference<T>,
+  resource: ClientReference<T>,
 ): ModuleMetaData {
   return resolveModuleMetaDataImpl(config, resource);
 }

packages/react-server-dom-relay/src/__mocks__/ReactFlightDOMRelayClientIntegration.js

@@ -10,7 +10,7 @@
 import JSResourceReferenceImpl from 'JSResourceReferenceImpl';
 
 const ReactFlightDOMRelayClientIntegration = {
-  resolveModuleReference(moduleData) {
+  resolveClientReference(moduleData) {
     return new JSResourceReferenceImpl(moduleData);
   },
   preloadModule(moduleReference) {},

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

@@ -29,12 +29,12 @@ export opaque type ModuleMetaData = {
 };
 
 // eslint-disable-next-line no-unused-vars
-export opaque type ModuleReference<T> = ModuleMetaData;
+export opaque type ClientReference<T> = ModuleMetaData;
 
-export function resolveModuleReference<T>(
+export function resolveClientReference<T>(
   bundlerConfig: BundlerConfig,
   moduleData: ModuleMetaData,
-): ModuleReference<T> {
+): ClientReference<T> {
   if (bundlerConfig) {
     const resolvedModuleData = bundlerConfig[moduleData.id][moduleData.name];
     if (moduleData.async) {
@@ -64,7 +64,7 @@ function ignoreReject() {
 // Start preloading the modules since we might need them soon.
 // This function doesn't suspend.
 export function preloadModule<T>(
-  moduleData: ModuleReference<T>,
+  moduleData: ClientReference<T>,
 ): null | Thenable<any> {
   const chunks = moduleData.chunks;
   const promises = [];
@@ -117,7 +117,7 @@ export function preloadModule<T>(
 
 // Actually require the module or suspend if it's not yet ready.
 // Increase priority if necessary.
-export function requireModule<T>(moduleData: ModuleReference<T>): T {
+export function requireModule<T>(moduleData: ClientReference<T>): T {
   let moduleExports;
   if (moduleData.async) {
     // We assume that preloadModule has been called before, which