From 71f725593739d2cb5866a282a1075d581831722f Mon Sep 17 00:00:00 2001 From: Andrew Clark Date: Thu, 17 Sep 2026 12:27:10 -0400 Subject: [PATCH] [Flight] Server References for arbitrary object types (#37636) Added behind a new experimental flag, `enableFlightObjectReferences`. Extends Server References so that a reference can point to an object, not just a function. An object is registered with a new API, `registerServerObjectReference`, which tags it with its module id the same way `registerServerReference` tags a Server Function. The client receives an opaque handle: reading a property or calling it throws, similar to how Temporary References work inside Server Functions. The only thing the client can do with the handle is pass it back to the server via a Server Function, where it resolves through the server manifest. The motivating use case is letting a framework pass request-scoped values by reference, so it can omit them from the request body. For example, a framework could model `searchParams` as a module export whose value resolves from the current request. This avoids encoding the search params twice (they already appear in the request URL) but it also makes the responses more cacheable: if the search params don't appear elsewhere in the body, then a response cache can omit them from its cache key. This initial PR only exposes the new API in the Turbopack bindings. We will port it to the other bundler configs if the experiment advances. --- .../react-client/src/ReactFlightClient.js | 38 + .../src/ReactFlightReplyClient.js | 105 +++ .../npm/server.browser.js | 1 + .../npm/server.edge.js | 1 + .../npm/server.node.js | 1 + .../server.browser.js | 1 + .../react-server-dom-turbopack/server.edge.js | 1 + .../react-server-dom-turbopack/server.node.js | 1 + .../src/ReactFlightTurbopackReferences.js | 28 + ...FlightTurbopackDOMObjectReferences-test.js | 681 ++++++++++++++++++ .../src/__tests__/utils/TurbopackMock.js | 60 +- .../src/server/ReactFlightDOMServerBrowser.js | 1 + .../src/server/ReactFlightDOMServerEdge.js | 1 + .../src/server/ReactFlightDOMServerNode.js | 1 + .../server/react-flight-dom-server.browser.js | 1 + .../server/react-flight-dom-server.edge.js | 1 + .../server/react-flight-dom-server.node.js | 1 + .../src/ReactFlightReplyServer.js | 316 +++++--- .../react-server/src/ReactFlightServer.js | 125 ++-- packages/shared/ReactFeatureFlags.js | 6 + .../forks/ReactFeatureFlags.native-fb.js | 1 + .../forks/ReactFeatureFlags.native-oss.js | 1 + .../forks/ReactFeatureFlags.test-renderer.js | 1 + ...actFeatureFlags.test-renderer.native-fb.js | 1 + .../ReactFeatureFlags.test-renderer.www.js | 1 + .../shared/forks/ReactFeatureFlags.www.js | 1 + scripts/error-codes/codes.json | 5 +- 27 files changed, 1228 insertions(+), 154 deletions(-) create mode 100644 packages/react-server-dom-turbopack/src/__tests__/ReactFlightTurbopackDOMObjectReferences-test.js diff --git a/packages/react-client/src/ReactFlightClient.js b/packages/react-client/src/ReactFlightClient.js index 8dd5b64d5df5..97703f78ffb2 100644 --- a/packages/react-client/src/ReactFlightClient.js +++ b/packages/react-client/src/ReactFlightClient.js @@ -47,6 +47,7 @@ import { enableComponentPerformanceTrack, enableAsyncDebugInfo, enableFlightWeakThenables, + enableFlightObjectReferences, } from 'shared/ReactFeatureFlags'; import { @@ -69,6 +70,7 @@ import { import { createBoundServerReference, registerBoundServerReference, + createServerObjectReference, } from './ReactFlightReplyClient'; import {readTemporaryReference} from './ReactFlightTemporaryReferences'; @@ -2226,6 +2228,28 @@ function loadServerReference, T>( return null as any; } +function loadServerObjectReference( + response: Response, + metaData: {id: any, $$reference?: Object}, + parentObject: Object, + key: string, +): mixed { + // A Server Reference to an object is always opaque on the client, even if + // we have a module mapping for Server References: unlike a function + // reference, the module that produced it is only meant to be evaluated in a + // true server environment. The reference can only be passed back to the + // server, where it resolves to the object. + // The server reuses this metadata when the same object occurs again. + // Cache its handle so reference equality is preserved within this response. + const existingReference = metaData.$$reference; + if (existingReference !== undefined) { + return existingReference; + } + const reference = createServerObjectReference(metaData.id); + metaData.$$reference = reference; + return reference; +} + function resolveLazy(value: any): mixed { while ( typeof value === 'object' && @@ -2718,6 +2742,20 @@ function parseModelString( loadServerReference, ); } + case 'H': { + if (enableFlightObjectReferences) { + // Server Reference to an object + const ref = value.slice(2); + return getOutlinedModel( + response, + ref, + parentObject, + key, + loadServerObjectReference, + ); + } + return undefined; + } case 'T': { // Temporary Reference const reference = '$' + value.slice(2); diff --git a/packages/react-client/src/ReactFlightReplyClient.js b/packages/react-client/src/ReactFlightReplyClient.js index 20282c441e46..d55053bd14e6 100644 --- a/packages/react-client/src/ReactFlightReplyClient.js +++ b/packages/react-client/src/ReactFlightReplyClient.js @@ -37,6 +37,8 @@ import {writeTemporaryReference} from './ReactFlightTemporaryReferences'; import isArray from 'shared/isArray'; import getPrototypeOf from 'shared/getPrototypeOf'; +import {enableFlightObjectReferences} from 'shared/ReactFeatureFlags'; + const ObjectPrototype = Object.prototype; // Passed to replyLifetimeController.abort(). Nothing reads the reason, but a @@ -78,6 +80,12 @@ type ServerReferenceClosure = { const knownServerReferences: WeakMap = new WeakMap(); +// Server References to objects are tracked separately from function +// references. They have no bound arguments and are never callable, so a +// reference of one kind must not be usable where the other is expected. +const knownServerObjectReferences: WeakMap = + new WeakMap(); + // Serializable values export type ReactServerValue = // References are passed by their value @@ -118,6 +126,10 @@ function serializeServerReferenceID(id: number): string { return '$h' + id.toString(16); } +function serializeServerObjectReferenceID(id: number): string { + return '$H' + id.toString(16); +} + function serializeTemporaryReferenceMarker(): string { return '$T'; } @@ -465,6 +477,40 @@ export function processReply( } if (typeof value === 'object') { + if (enableFlightObjectReferences) { + // Check before traversing the object or falling back to a temporary + // reference. A Server Reference must always be encoded by id. + const objectReferenceId = knownServerObjectReferences.get(value); + if (objectReferenceId !== undefined) { + const existingReference = writtenObjects.get(value); + if (existingReference !== undefined) { + if (modelRoot === value) { + // serializeModel registered this root before we recognized it + // as a Server Reference. Encode its metadata on this first visit. + modelRoot = null; + } else { + return existingReference; + } + } + const referenceJSON = JSON.stringify( + {id: objectReferenceId}, + resolveToJSON, + ); + if (formData === null) { + // Upgrade to use FormData to allow us to stream this value. + formData = new FormData(); + } + // The reference to this object came from the same client so we can + // pass it back to the server where it resolves to the object. + const refId = nextPartId++; + formData.set(formFieldPrefix + refId, referenceJSON); + const serverObjectReferenceId = + serializeServerObjectReferenceID(refId); + // Store the reference ID for deduplication. + writtenObjects.set(value, serverObjectReferenceId); + return serverObjectReferenceId; + } + } switch ((value as any).$$typeof) { case REACT_ELEMENT_TYPE: { if (temporaryReferences !== undefined && key.indexOf(':') === -1) { @@ -1301,6 +1347,65 @@ export function registerServerReference( return reference; } +const serverObjectReferenceProxyHandlers: Proxy$traps = { + get: function (target: Object, name: string | symbol) { + switch (name) { + // These names are read by the Flight runtime if you end up passing this + // reference along. + case '$$typeof': + return target.$$typeof; + case 'name': + return undefined; + case 'displayName': + return undefined; + // We need to special case this because createElement reads it if we pass this + // reference. + case 'defaultProps': + return undefined; + // React looks for debugInfo on thenables. + case '_debugInfo': + return undefined; + // React also probes streamed objects for async iterator debug info. + case ASYNC_ITERATOR: + return undefined; + // Avoid this attempting to be serialized. + case 'toJSON': + return undefined; + case Symbol.toPrimitive: + // $FlowFixMe[prop-missing] + return Object.prototype[Symbol.toPrimitive]; + case Symbol.toStringTag: + // $FlowFixMe[prop-missing] + return Object.prototype[Symbol.toStringTag]; + case 'then': + // Even if the referenced object is a Promise, it must not appear + // thenable on the client or it would be awaited instead of passed + // along by reference. + return undefined; + } + throw new Error( + // eslint-disable-next-line react-internal/safe-string-coercion + `Cannot access ${String(name)} on the client. ` + + 'You cannot read a Server Reference to an object on the client. ' + + 'You can only pass it back to the server.', + ); + }, + set: function () { + throw new Error( + 'Cannot assign to a Server Reference to an object on the client.', + ); + }, +}; + +export function createServerObjectReference(id: ServerReferenceId): Object { + const reference = new Proxy({}, serverObjectReferenceProxyHandlers); + // Register the reference so that passing it back to the server encodes it + // by id. Object references are tracked separately from function references + // so that one kind can never be encoded as the other. + knownServerObjectReferences.set(reference, id); + return reference; +} + // $FlowFixMe[method-unbinding] const FunctionBind = Function.prototype.bind; // $FlowFixMe[method-unbinding] diff --git a/packages/react-server-dom-turbopack/npm/server.browser.js b/packages/react-server-dom-turbopack/npm/server.browser.js index ec8d6b013e0b..04867fd800bf 100644 --- a/packages/react-server-dom-turbopack/npm/server.browser.js +++ b/packages/react-server-dom-turbopack/npm/server.browser.js @@ -12,6 +12,7 @@ exports.decodeReply = s.decodeReply; exports.decodeAction = s.decodeAction; exports.decodeFormState = s.decodeFormState; exports.registerServerReference = s.registerServerReference; +exports.registerServerObjectReference = s.registerServerObjectReference; exports.registerClientReference = s.registerClientReference; exports.createClientModuleProxy = s.createClientModuleProxy; exports.createTemporaryReferenceSet = s.createTemporaryReferenceSet; diff --git a/packages/react-server-dom-turbopack/npm/server.edge.js b/packages/react-server-dom-turbopack/npm/server.edge.js index c832080079dd..b25bb99d6382 100644 --- a/packages/react-server-dom-turbopack/npm/server.edge.js +++ b/packages/react-server-dom-turbopack/npm/server.edge.js @@ -13,6 +13,7 @@ exports.decodeReplyFromAsyncIterable = s.decodeReplyFromAsyncIterable; exports.decodeAction = s.decodeAction; exports.decodeFormState = s.decodeFormState; exports.registerServerReference = s.registerServerReference; +exports.registerServerObjectReference = s.registerServerObjectReference; exports.registerClientReference = s.registerClientReference; exports.createClientModuleProxy = s.createClientModuleProxy; exports.createTemporaryReferenceSet = s.createTemporaryReferenceSet; diff --git a/packages/react-server-dom-turbopack/npm/server.node.js b/packages/react-server-dom-turbopack/npm/server.node.js index 950763954048..f5199197cbf6 100644 --- a/packages/react-server-dom-turbopack/npm/server.node.js +++ b/packages/react-server-dom-turbopack/npm/server.node.js @@ -15,6 +15,7 @@ exports.decodeReplyFromAsyncIterable = s.decodeReplyFromAsyncIterable; exports.decodeAction = s.decodeAction; exports.decodeFormState = s.decodeFormState; exports.registerServerReference = s.registerServerReference; +exports.registerServerObjectReference = s.registerServerObjectReference; exports.registerClientReference = s.registerClientReference; exports.createClientModuleProxy = s.createClientModuleProxy; exports.createTemporaryReferenceSet = s.createTemporaryReferenceSet; diff --git a/packages/react-server-dom-turbopack/server.browser.js b/packages/react-server-dom-turbopack/server.browser.js index 46f5b906104b..ef9e0c3a0355 100644 --- a/packages/react-server-dom-turbopack/server.browser.js +++ b/packages/react-server-dom-turbopack/server.browser.js @@ -13,6 +13,7 @@ export { decodeAction, decodeFormState, registerServerReference, + registerServerObjectReference, registerClientReference, createClientModuleProxy, createTemporaryReferenceSet, diff --git a/packages/react-server-dom-turbopack/server.edge.js b/packages/react-server-dom-turbopack/server.edge.js index 8f0347cd7b5a..3bba9613a803 100644 --- a/packages/react-server-dom-turbopack/server.edge.js +++ b/packages/react-server-dom-turbopack/server.edge.js @@ -14,6 +14,7 @@ export { decodeAction, decodeFormState, registerServerReference, + registerServerObjectReference, registerClientReference, createClientModuleProxy, createTemporaryReferenceSet, diff --git a/packages/react-server-dom-turbopack/server.node.js b/packages/react-server-dom-turbopack/server.node.js index bd00ba7275c1..d51e07ed7fc5 100644 --- a/packages/react-server-dom-turbopack/server.node.js +++ b/packages/react-server-dom-turbopack/server.node.js @@ -16,6 +16,7 @@ export { decodeAction, decodeFormState, registerServerReference, + registerServerObjectReference, registerClientReference, createClientModuleProxy, createTemporaryReferenceSet, diff --git a/packages/react-server-dom-turbopack/src/ReactFlightTurbopackReferences.js b/packages/react-server-dom-turbopack/src/ReactFlightTurbopackReferences.js index 189c76617ff1..b82128d09d46 100644 --- a/packages/react-server-dom-turbopack/src/ReactFlightTurbopackReferences.js +++ b/packages/react-server-dom-turbopack/src/ReactFlightTurbopackReferences.js @@ -143,6 +143,34 @@ export function registerServerReference( ); } +export type ServerObjectReference = T & { + $$typeof: symbol, + $$id: string, +}; + +export function registerServerObjectReference( + reference: T, + id: string, + exportName: null | string, +): ServerObjectReference { + if (__DEV__) { + if (typeof reference === 'function') { + console.error( + 'registerServerObjectReference: The reference is a function. Use ' + + 'registerServerReference to register a function as a Server ' + + 'Reference.', + ); + } + } + return Object.defineProperties(reference as any, { + $$typeof: {value: SERVER_REFERENCE_TAG}, + $$id: { + value: exportName === null ? id : id + '#' + exportName, + configurable: true, + }, + }); +} + const PROMISE_PROTOTYPE = Promise.prototype; const deepProxyHandlers: Proxy$traps = { diff --git a/packages/react-server-dom-turbopack/src/__tests__/ReactFlightTurbopackDOMObjectReferences-test.js b/packages/react-server-dom-turbopack/src/__tests__/ReactFlightTurbopackDOMObjectReferences-test.js new file mode 100644 index 000000000000..93017108e58e --- /dev/null +++ b/packages/react-server-dom-turbopack/src/__tests__/ReactFlightTurbopackDOMObjectReferences-test.js @@ -0,0 +1,681 @@ +/** + * 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. + * + * @emails react-core + */ + +'use strict'; + +import {patchMessageChannel} from '../../../../scripts/jest/patchMessageChannel'; + +// Polyfills for test environment +global.ReadableStream = + require('web-streams-polyfill/ponyfill/es6').ReadableStream; +global.TextEncoder = require('util').TextEncoder; +global.TextDecoder = require('util').TextDecoder; + +let serverExports; +let serverObjectExports; +let turbopackMap; +let turbopackServerMap; +let ReactServerDOMServer; +let ReactServerDOMClient; +let ReactServerScheduler; +let serverAct; + +describe('ReactFlightTurbopackDOMObjectReferences', () => { + beforeEach(() => { + jest.resetModules(); + + ReactServerScheduler = require('scheduler'); + patchMessageChannel(ReactServerScheduler); + serverAct = require('internal-test-utils').serverAct; + + // Simulate the condition resolution + jest.mock('react', () => require('react/react.react-server')); + jest.mock('react-server-dom-turbopack/server', () => + require('react-server-dom-turbopack/server.browser'), + ); + + const TurbopackMock = require('./utils/TurbopackMock'); + serverExports = TurbopackMock.serverExports; + serverObjectExports = TurbopackMock.serverObjectExports; + turbopackMap = TurbopackMock.turbopackMap; + turbopackServerMap = TurbopackMock.turbopackServerMap; + + ReactServerDOMServer = require('react-server-dom-turbopack/server.browser'); + + __unmockReact(); + jest.resetModules(); + ReactServerDOMClient = require('react-server-dom-turbopack/client.browser'); + }); + + // @gate enableFlightObjectReferences + it('passes an object reference to the client and back to the server where it resolves', async () => { + const settings = {theme: 'dark'}; + const ServerModule = serverObjectExports({settings}); + + const stream = await serverAct(() => + ReactServerDOMServer.renderToReadableStream( + {ref: ServerModule.settings}, + turbopackMap, + ), + ); + const result = await ReactServerDOMClient.createFromReadableStream(stream); + const token = result.ref; + expect(typeof token).toBe('object'); + + // The client representation is opaque. The object never crossed the wire, + // and reading any property throws. + expect(() => token.theme).toThrow( + 'Cannot access theme on the client. ' + + 'You cannot read a Server Reference to an object on the client. ' + + 'You can only pass it back to the server.', + ); + // It is not callable either; it is not a Server Function. + expect(() => token()).toThrow(TypeError); + + // React must treat it as a state value, not call it as an initializer. + const React = require('react'); + const ReactDOMServer = require('react-dom/server'); + function Client() { + const [value] = React.useState(token); + expect(value).toBe(token); + return null; + } + ReactDOMServer.renderToString(React.createElement(Client)); + + // Passing it back resolves the object through the server manifest. + const body = await ReactServerDOMClient.encodeReply({ref: token}); + const decoded = await ReactServerDOMServer.decodeReply( + body, + turbopackServerMap, + ); + expect(decoded.ref).toBe(settings); + }); + + // @gate enableFlightObjectReferences + it('encodes an object reference at the root, including with temporary references', async () => { + const settings = {theme: 'dark'}; + const ServerModule = serverObjectExports({settings}); + const stream = await serverAct(() => + ReactServerDOMServer.renderToReadableStream( + {ref: ServerModule.settings}, + turbopackMap, + ), + ); + const {ref} = await ReactServerDOMClient.createFromReadableStream(stream); + + const temporaryReferenceSets = [ + undefined, + ReactServerDOMClient.createTemporaryReferenceSet(), + ]; + for (let i = 0; i < temporaryReferenceSets.length; i++) { + const temporaryReferences = temporaryReferenceSets[i]; + const body = await ReactServerDOMClient.encodeReply(ref, { + temporaryReferences, + }); + const decoded = await ReactServerDOMServer.decodeReply( + body, + turbopackServerMap, + ); + expect(decoded).toBe(settings); + + const nestedBody = await ReactServerDOMClient.encodeReply( + {first: ref, second: ref, promised: Promise.resolve(ref)}, + {temporaryReferences}, + ); + const nested = await ReactServerDOMServer.decodeReply( + nestedBody, + turbopackServerMap, + ); + expect(nested.first).toBe(settings); + expect(nested.second).toBe(settings); + expect(await nested.promised).toBe(settings); + } + }); + + // @gate enableFlightObjectReferences + it('does not await an object reference that is a Promise', async () => { + const promise = Promise.resolve('server secret'); + const ServerModule = serverObjectExports({promise}); + + const stream = await serverAct(() => + ReactServerDOMServer.renderToReadableStream( + {ref: ServerModule.promise}, + turbopackMap, + ), + ); + const result = await ReactServerDOMClient.createFromReadableStream(stream); + const token = result.ref; + expect(typeof token).toBe('object'); + + // The token must not appear thenable, or awaiting it would hang or leak. + // Awaiting it just yields the token itself. + expect(await token).toBe(token); + expect(() => token.value).toThrow('Cannot access value on the client.'); + + const body = await ReactServerDOMClient.encodeReply({ref: token}); + const decoded = await ReactServerDOMServer.decodeReply( + body, + turbopackServerMap, + ); + expect(decoded.ref).toBe(promise); + expect(await decoded.ref).toBe('server secret'); + }); + + // @gate enableFlightObjectReferences + it('resolves to the current value of the module export, not a snapshot', async () => { + let current = {version: 1}; + const ServerModule = serverObjectExports({ + get value() { + return current; + }, + }); + + const stream = await serverAct(() => + ReactServerDOMServer.renderToReadableStream( + {ref: ServerModule.value}, + turbopackMap, + ), + ); + const result = await ReactServerDOMClient.createFromReadableStream(stream); + const token = result.ref; + expect(typeof token).toBe('object'); + + const body1 = await ReactServerDOMClient.encodeReply({ref: token}); + const decoded1 = await ReactServerDOMServer.decodeReply( + body1, + turbopackServerMap, + ); + expect(decoded1.ref).toBe(current); + expect(decoded1.ref.version).toBe(1); + + // Simulate a later request where the module export resolves to a fresh + // value. The same reference must resolve to the new value. + current = {version: 2}; + const body2 = await ReactServerDOMClient.encodeReply({ref: token}); + const decoded2 = await ReactServerDOMServer.decodeReply( + body2, + turbopackServerMap, + ); + expect(decoded2.ref).toBe(current); + expect(decoded2.ref.version).toBe(2); + }); + + // @gate enableFlightObjectReferences + it('is not turned into a temporary reference when a TemporaryReferenceSet is passed', async () => { + const settings = {theme: 'dark'}; + const ServerModule = serverObjectExports({settings}); + + const stream = await serverAct(() => + ReactServerDOMServer.renderToReadableStream( + {ref: ServerModule.settings}, + turbopackMap, + ), + ); + const result = await ReactServerDOMClient.createFromReadableStream(stream); + const token = result.ref; + expect(typeof token).toBe('object'); + + // A Server Reference is never turned into a temporary reference, even + // when a TemporaryReferenceSet is provided. It must encode as an object + // reference so the server resolves it through the manifest. + const temporaryReferences = + ReactServerDOMClient.createTemporaryReferenceSet(); + const body = await ReactServerDOMClient.encodeReply( + {ref: token}, + {temporaryReferences}, + ); + const decoded = await ReactServerDOMServer.decodeReply( + body, + turbopackServerMap, + ); + expect(decoded.ref).toBe(settings); + }); + + // @gate enableFlightObjectReferences + it('keeps Dates and objects with toJSON opaque', async () => { + const date = new Date('2026-09-14T00:00:00.000Z'); + const custom = { + get toJSON() { + throw new Error('Must not read toJSON on a registered object.'); + }, + }; + const ServerModule = serverObjectExports({date, custom}); + const stream = await serverAct(() => + ReactServerDOMServer.renderToReadableStream(ServerModule, turbopackMap), + ); + const result = await ReactServerDOMClient.createFromReadableStream(stream); + expect(typeof result.date).toBe('object'); + expect(() => result.date.toISOString()).toThrow( + 'Cannot access toISOString on the client.', + ); + expect(typeof result.custom).toBe('object'); + + const body = await ReactServerDOMClient.encodeReply(result); + const decoded = await ReactServerDOMServer.decodeReply( + body, + turbopackServerMap, + ); + expect(decoded.date).toBe(date); + expect(decoded.custom).toBe(custom); + }); + + // @gate enableFlightObjectReferences + it('preserves identity across repeated references and streamed values', async () => { + const settings = {theme: 'dark'}; + serverObjectExports({settings}); + let resolveLater; + const later = new Promise(resolve => { + resolveLater = resolve; + }); + const stream = await serverAct(() => + ReactServerDOMServer.renderToReadableStream( + { + first: settings, + second: settings, + map: new Map([[settings, 'value']]), + later, + }, + turbopackMap, + ), + ); + const result = await ReactServerDOMClient.createFromReadableStream(stream); + expect(result.first).toBe(result.second); + expect(result.map.get(result.first)).toBe('value'); + await serverAct(() => resolveLater(settings)); + expect(await result.later).toBe(result.first); + expect(() => result.first.theme).toThrow( + 'Cannot access theme on the client.', + ); + }); + + // @gate enableFlightObjectReferences + it('round-trips an object reference under then after its module loads', async () => { + let resolveModule; + const blockOnChunk = new Promise(resolve => { + resolveModule = resolve; + }); + const settings = {theme: 'dark'}; + const ServerModule = serverObjectExports({settings}, blockOnChunk); + const stream = await serverAct(() => + ReactServerDOMServer.renderToReadableStream( + {ref: ServerModule.settings}, + turbopackMap, + ), + ); + const {ref} = await ReactServerDOMClient.createFromReadableStream(stream); + const body = await ReactServerDOMClient.encodeReply({ + first: ref, + then: ref, + }); + const pending = ReactServerDOMServer.decodeReply(body, turbopackServerMap); + await resolveModule(); + const decoded = await pending; + expect(decoded.first).toBe(settings); + expect(decoded.then).toBe(settings); + + const decodedAgain = await ReactServerDOMServer.decodeReply( + body, + turbopackServerMap, + ); + expect(decodedAgain.first).toBe(settings); + expect(decodedAgain.then).toBe(settings); + }); + + // Produce an ordinary alias using the encoder, then extend only its path. + // Map entries are outlined, so this also exercises delayed path resolution + // when the referenced module has not loaded yet. Chunk IDs come from the encoder. + async function encodePropertyRead(ref, property) { + const container = {ref}; + const body = await ReactServerDOMClient.encodeReply({ + map: new Map([['container', container]]), + selected: container, + }); + const model = JSON.parse(body.get('0')); + model.selected += ':ref:' + property; + body.set('0', JSON.stringify(model)); + return body; + } + + describe.each(['object', 'array'])('reply paths into a server %s', shape => { + describe.each(['loaded', 'delayed'])('with a %s module', loading => { + async function checkPropertyRead(registerExports, initialValue) { + let resolveModule; + const blockOnChunk = + loading === 'delayed' + ? new Promise(resolve => { + resolveModule = resolve; + }) + : undefined; + let current = initialValue; + const ServerModule = registerExports( + { + get value() { + return current; + }, + }, + blockOnChunk, + ); + const stream = await serverAct(() => + ReactServerDOMServer.renderToReadableStream( + {ref: ServerModule.value}, + turbopackMap, + ), + ); + const {ref} = + await ReactServerDOMClient.createFromReadableStream(stream); + const readProperty = jest.fn(() => 'server value'); + const property = shape === 'array' ? '0' : 'value'; + // Model the next request supplying a fresh module export. It has + // never been registered or sent to the client. + current = Object.defineProperty(shape === 'array' ? [] : {}, property, { + get: readProperty, + }); + const body = await encodePropertyRead(ref, property); + const pending = ReactServerDOMServer.decodeReply( + body, + turbopackServerMap, + ); + if (resolveModule) { + await resolveModule(); + } + await expect(Promise.resolve(pending)).rejects.toThrow( + 'Invalid reference.', + ); + expect(readProperty).not.toHaveBeenCalled(); + + const container = {ref}; + const validBody = await ReactServerDOMClient.encodeReply({ + container, + alias: container, + }); + const decoded = await ReactServerDOMServer.decodeReply( + validBody, + turbopackServerMap, + ); + expect(decoded.container).toBe(decoded.alias); + expect(decoded.container.ref).toBe(current); + } + + // @gate enableFlightObjectReferences + it('rejects property access through an object reference', async () => { + await checkPropertyRead(serverObjectExports, {}); + }); + + it('rejects property access through a function reference whose export is now an object', async () => { + await checkPropertyRead(serverExports, function action() {}); + }); + }); + }); + + it('still resolves aliases through client objects and arrays', async () => { + const child = {value: 'client value'}; + const container = [child]; + const body = await ReactServerDOMClient.encodeReply({ + map: new Map([['container', container]]), + container, + child, + }); + const decoded = await ReactServerDOMServer.decodeReply( + body, + turbopackServerMap, + ); + expect(decoded.container).toBe(decoded.map.get('container')); + expect(decoded.child).toBe(decoded.container[0]); + expect(decoded.child.value).toBe('client value'); + }); + + // A consuming decoder (Map, Set, iterator) reads its initializer array + // directly, without walking a property path, so the opacity guard in the + // path walkers doesn't cover it. Pointing one at a chunk that resolves to a + // server-owned array would otherwise spill its contents into the reply. Map + // stands in for all three; they share one `isServerReferenceObject` guard in + // `createMap`/`createSet`/`extractIterator`. + // @gate enableFlightObjectReferences + it('rejects a reply that decodes a server object as a Map', async () => { + const leaked = [['leaked', 'secret']]; + const ServerModule = serverObjectExports({value: leaked}); + const stream = await serverAct(() => + ReactServerDOMServer.renderToReadableStream( + {ref: ServerModule.value}, + turbopackMap, + ), + ); + const {ref} = await ReactServerDOMClient.createFromReadableStream(stream); + + // Point a Map decoder at a fresh row that resolves to the server array, so + // the Map initializer is the server-owned array itself (isArray is true) + // and it's specifically the opacity guard that rejects, not the + // not-an-array path. Row 7 is an unused id we add for this indirection. + const body = await ReactServerDOMClient.encodeReply({ref}); + const referenceMarker = JSON.parse(body.get('0')).ref; + body.set('0', JSON.stringify('$Q7')); + body.set('7', JSON.stringify(referenceMarker)); + + const pending = ReactServerDOMServer.decodeReply(body, turbopackServerMap); + await expect(Promise.resolve(pending)).rejects.toThrow( + 'Invalid Map initializer.', + ); + // The rejection happened before the decoder marked the server-owned array + // as consumed, so its state is untouched. + expect(leaked.$$consumed).toBe(undefined); + }); + + // @gate enableFlightObjectReferences + it('keeps registered binary values opaque when yielded by an async iterable', async () => { + async function* items(value) { + yield value; + yield value; + } + const values = [new Uint8Array([1, 2, 3]), new ArrayBuffer(3)]; + for (let i = 0; i < values.length; i++) { + const value = values[i]; + serverObjectExports({value}); + const stream = await serverAct(() => + ReactServerDOMServer.renderToReadableStream( + {ref: value, items: items(value)}, + turbopackMap, + ), + ); + const result = + await ReactServerDOMClient.createFromReadableStream(stream); + const iterator = result.items[Symbol.asyncIterator](); + const first = await iterator.next(); + const second = await iterator.next(); + expect(first.value === result.ref).toBe(true); + expect(second.value === result.ref).toBe(true); + expect((await iterator.next()).done).toBe(true); + expect(() => first.value.byteLength).toThrow( + 'Cannot access byteLength on the client.', + ); + const body = await ReactServerDOMClient.encodeReply({ref: first.value}); + const decoded = await ReactServerDOMServer.decodeReply( + body, + turbopackServerMap, + ); + expect(decoded.ref).toBe(value); + } + }); + + describe.each(['loaded', 'delayed'])( + 'invalid object references with a %s module', + loading => { + // @gate enableFlightObjectReferences + it('rejects a function encoded as an object reference', async () => { + let resolveModule; + const blockOnChunk = + loading === 'delayed' + ? new Promise(resolve => { + resolveModule = resolve; + }) + : undefined; + const fn = jest.fn(); + const ServerModule = serverExports({fn}, blockOnChunk); + const stream = await serverAct(() => + ReactServerDOMServer.renderToReadableStream( + {fn: ServerModule.fn}, + turbopackMap, + ), + ); + const result = + await ReactServerDOMClient.createFromReadableStream(stream); + const body = await ReactServerDOMClient.encodeReply({ + fn: result.fn, + ref: result.fn, + }); + const model = JSON.parse(body.get('0')); + // Keep the function occurrence, but submit the same reference as an + // object under "then" too. It must not become a callable thenable. + model.then = model.ref.replace('$h', '$H'); + delete model.ref; + body.set('0', JSON.stringify(model)); + const pending = ReactServerDOMServer.decodeReply( + body, + turbopackServerMap, + ); + if (resolveModule) { + await resolveModule(); + } + await expect(Promise.resolve(pending)).rejects.toThrow( + 'Expected a Server Reference to an object to resolve to an object.', + ); + expect(fn).not.toHaveBeenCalled(); + }); + }, + ); + + // @gate enableFlightObjectReferences + it('does not bind arguments supplied with object reference metadata', async () => { + const bind = jest.fn(); + const settings = {bind}; + const ServerModule = serverObjectExports({settings}); + const stream = await serverAct(() => + ReactServerDOMServer.renderToReadableStream( + {ref: ServerModule.settings}, + turbopackMap, + ), + ); + const {ref} = await ReactServerDOMClient.createFromReadableStream(stream); + const body = await ReactServerDOMClient.encodeReply({ + ref, + args: Promise.resolve([]), + }); + const model = JSON.parse(body.get('0')); + // Use the encoder's metadata and promise IDs; add only the unsupported + // bound-arguments field to the object reference. + const metadataKey = model.ref.slice(2); + const metadata = JSON.parse(body.get(metadataKey)); + metadata.bound = model.args; + body.set(metadataKey, JSON.stringify(metadata)); + const decoded = await ReactServerDOMServer.decodeReply( + body, + turbopackServerMap, + ); + expect(decoded.ref).toBe(settings); + expect(bind).not.toHaveBeenCalled(); + }); + + // @gate enableFlightObjectReferences + it('rejects an object reference missing from the receiving server manifest', async () => { + const settings = {theme: 'dark'}; + const ServerModule = serverObjectExports({settings}); + const stream = await serverAct(() => + ReactServerDOMServer.renderToReadableStream( + {ref: ServerModule.settings}, + turbopackMap, + ), + ); + const {ref} = await ReactServerDOMClient.createFromReadableStream(stream); + const body = await ReactServerDOMClient.encodeReply({ref}); + await expect( + Promise.resolve(ReactServerDOMServer.decodeReply(body, {})), + ).rejects.toThrow('Could not find the module'); + }); + + // @gate !enableFlightObjectReferences + it('serializes a registered Promise as a thenable when the flag is off', async () => { + const promise = Promise.resolve('resolved'); + const ServerModule = serverObjectExports({promise}); + + const stream = await serverAct(() => + ReactServerDOMServer.renderToReadableStream( + {promise: ServerModule.promise}, + turbopackMap, + ), + ); + const result = await ReactServerDOMClient.createFromReadableStream(stream); + + // Without the flag, a registered Promise is awaited like any other + // thenable and its value crosses to the client. + expect(await result.promise).toBe('resolved'); + }); + + // @gate enableFlightObjectReferences + it('round-trips objects and bound functions together', async () => { + const settings = {theme: 'dark'}; + function describe(theme, name) { + return theme + ': ' + name; + } + const ServerModule = serverObjectExports({settings, describe}); + const stream = await serverAct(() => + ReactServerDOMServer.renderToReadableStream( + { + settings: ServerModule.settings, + again: ServerModule.settings, + describe: ServerModule.describe, + bound: ServerModule.describe.bind(null, 'dark'), + }, + turbopackMap, + ), + ); + const result = await ReactServerDOMClient.createFromReadableStream(stream); + expect(typeof result.settings).toBe('object'); + expect(() => result.settings.theme).toThrow( + 'Cannot access theme on the client.', + ); + expect(result.again).toBe(result.settings); + expect(typeof result.describe).toBe('function'); + expect(typeof result.bound).toBe('function'); + + const body = await ReactServerDOMClient.encodeReply(result); + const decoded = await ReactServerDOMServer.decodeReply( + body, + turbopackServerMap, + ); + expect(decoded.settings).toBe(settings); + expect(decoded.again).toBe(settings); + expect(decoded.describe).toBe(describe); + expect(decoded.bound('Alice')).toBe('dark: Alice'); + }); + + it('still round-trips function server references', async () => { + function greet(name) { + return 'hi, ' + name; + } + const ServerModule = serverExports({greet}); + + const stream = await serverAct(() => + ReactServerDOMServer.renderToReadableStream( + {method: ServerModule.greet}, + turbopackMap, + ), + ); + const result = await ReactServerDOMClient.createFromReadableStream(stream); + expect(typeof result.method).toBe('function'); + + const body = await ReactServerDOMClient.encodeReply({ + method: result.method, + }); + const decoded = await ReactServerDOMServer.decodeReply( + body, + turbopackServerMap, + ); + expect(decoded.method).toBe(greet); + expect(decoded.method('there')).toBe('hi, there'); + }); +}); diff --git a/packages/react-server-dom-turbopack/src/__tests__/utils/TurbopackMock.js b/packages/react-server-dom-turbopack/src/__tests__/utils/TurbopackMock.js index 2e81d55fa692..1915e7f7c799 100644 --- a/packages/react-server-dom-turbopack/src/__tests__/utils/TurbopackMock.js +++ b/packages/react-server-dom-turbopack/src/__tests__/utils/TurbopackMock.js @@ -15,6 +15,10 @@ const turbopackClientModules = {}; const turbopackErroredModules = {}; const turbopackServerMap = {}; const turbopackClientMap = {}; +const turbopackChunkMap = {}; +global.__turbopack_load_by_url__ = function (id) { + return turbopackChunkMap[id]; +}; global.__turbopack_require__ = function (id) { if (turbopackErroredModules[id]) { throw turbopackErroredModules[id]; @@ -25,6 +29,7 @@ global.__turbopack_require__ = function (id) { const Server = require('react-server-dom-turbopack/server'); const registerClientReference = Server.registerClientReference; const registerServerReference = Server.registerServerReference; +const registerServerObjectReference = Server.registerServerObjectReference; const createClientModuleProxy = Server.createClientModuleProxy; exports.turbopackMap = turbopackClientMap; @@ -144,13 +149,19 @@ exports.clientExportsESM = function clientExportsESM( }; // This tests server to server references. There's another case of client to server references. -exports.serverExports = function serverExports(moduleExports) { +exports.serverExports = function serverExports(moduleExports, blockOnChunk) { const idx = '' + turbopackModuleIdx++; turbopackServerModules[idx] = moduleExports; const path = url.pathToFileURL(idx).href; + const chunks = []; + if (blockOnChunk) { + const chunk = idx + '.js'; + turbopackChunkMap[chunk] = blockOnChunk; + chunks.push(chunk); + } turbopackServerMap[path] = { id: idx, - chunks: [], + chunks, name: '*', }; // We only add this if this test is testing ESM compat. @@ -174,24 +185,57 @@ exports.serverExports = function serverExports(moduleExports) { }; } - if (typeof exports === 'function') { + if (typeof moduleExports === 'function') { // The module exports a function directly, registerServerReference( - (exports: any), - idx, + (moduleExports: any), + path, // Represents the whole Module object instead of a particular import. null, ); } else { - const keys = Object.keys(exports); + const keys = Object.keys(moduleExports); for (let i = 0; i < keys.length; i++) { const key = keys[i]; - const value = exports[keys[i]]; + const value = moduleExports[key]; if (typeof value === 'function') { - registerServerReference((value: any), idx, key); + registerServerReference((value: any), path, key); } } } return moduleExports; }; + +// Simulates a "use server" module whose exports include objects, which are +// registered as object Server References. +exports.serverObjectExports = function serverObjectExports( + moduleExports, + blockOnChunk, +) { + const idx = '' + turbopackModuleIdx++; + turbopackServerModules[idx] = moduleExports; + const path = url.pathToFileURL(idx).href; + const chunks = []; + if (blockOnChunk) { + const chunk = idx + '.js'; + turbopackChunkMap[chunk] = blockOnChunk; + chunks.push(chunk); + } + turbopackServerMap[path] = { + id: idx, + chunks, + name: '*', + }; + const keys = Object.keys(moduleExports); + for (let i = 0; i < keys.length; i++) { + const key = keys[i]; + const value = moduleExports[key]; + if (typeof value === 'function') { + registerServerReference((value: any), path, key); + } else { + registerServerObjectReference((value: any), path, key); + } + } + return moduleExports; +}; diff --git a/packages/react-server-dom-turbopack/src/server/ReactFlightDOMServerBrowser.js b/packages/react-server-dom-turbopack/src/server/ReactFlightDOMServerBrowser.js index 84bd3d6f2901..a0c911742895 100644 --- a/packages/react-server-dom-turbopack/src/server/ReactFlightDOMServerBrowser.js +++ b/packages/react-server-dom-turbopack/src/server/ReactFlightDOMServerBrowser.js @@ -41,6 +41,7 @@ import { export { registerServerReference, + registerServerObjectReference, registerClientReference, createClientModuleProxy, } from '../ReactFlightTurbopackReferences'; diff --git a/packages/react-server-dom-turbopack/src/server/ReactFlightDOMServerEdge.js b/packages/react-server-dom-turbopack/src/server/ReactFlightDOMServerEdge.js index e92697ed5d46..f4559ef643d6 100644 --- a/packages/react-server-dom-turbopack/src/server/ReactFlightDOMServerEdge.js +++ b/packages/react-server-dom-turbopack/src/server/ReactFlightDOMServerEdge.js @@ -47,6 +47,7 @@ import { export { registerServerReference, + registerServerObjectReference, registerClientReference, createClientModuleProxy, } from '../ReactFlightTurbopackReferences'; diff --git a/packages/react-server-dom-turbopack/src/server/ReactFlightDOMServerNode.js b/packages/react-server-dom-turbopack/src/server/ReactFlightDOMServerNode.js index 2c5c987a70ba..9c0a149d4239 100644 --- a/packages/react-server-dom-turbopack/src/server/ReactFlightDOMServerNode.js +++ b/packages/react-server-dom-turbopack/src/server/ReactFlightDOMServerNode.js @@ -57,6 +57,7 @@ import { export { registerServerReference, + registerServerObjectReference, registerClientReference, createClientModuleProxy, } from '../ReactFlightTurbopackReferences'; diff --git a/packages/react-server-dom-turbopack/src/server/react-flight-dom-server.browser.js b/packages/react-server-dom-turbopack/src/server/react-flight-dom-server.browser.js index d8373ec551bc..cff378cecbef 100644 --- a/packages/react-server-dom-turbopack/src/server/react-flight-dom-server.browser.js +++ b/packages/react-server-dom-turbopack/src/server/react-flight-dom-server.browser.js @@ -14,6 +14,7 @@ export { decodeAction, decodeFormState, registerServerReference, + registerServerObjectReference, registerClientReference, createClientModuleProxy, createTemporaryReferenceSet, diff --git a/packages/react-server-dom-turbopack/src/server/react-flight-dom-server.edge.js b/packages/react-server-dom-turbopack/src/server/react-flight-dom-server.edge.js index e103ff761913..50aab0027d16 100644 --- a/packages/react-server-dom-turbopack/src/server/react-flight-dom-server.edge.js +++ b/packages/react-server-dom-turbopack/src/server/react-flight-dom-server.edge.js @@ -15,6 +15,7 @@ export { decodeAction, decodeFormState, registerServerReference, + registerServerObjectReference, registerClientReference, createClientModuleProxy, createTemporaryReferenceSet, diff --git a/packages/react-server-dom-turbopack/src/server/react-flight-dom-server.node.js b/packages/react-server-dom-turbopack/src/server/react-flight-dom-server.node.js index 3c2b9e512c7c..ec87c5d15d14 100644 --- a/packages/react-server-dom-turbopack/src/server/react-flight-dom-server.node.js +++ b/packages/react-server-dom-turbopack/src/server/react-flight-dom-server.node.js @@ -18,6 +18,7 @@ export { decodeAction, decodeFormState, registerServerReference, + registerServerObjectReference, registerClientReference, createClientModuleProxy, createTemporaryReferenceSet, diff --git a/packages/react-server/src/ReactFlightReplyServer.js b/packages/react-server/src/ReactFlightReplyServer.js index aa4ef53fa384..eb3d93bcc147 100644 --- a/packages/react-server/src/ReactFlightReplyServer.js +++ b/packages/react-server/src/ReactFlightReplyServer.js @@ -42,6 +42,7 @@ import { registerTemporaryReference, } from './ReactFlightServerTemporaryReferences'; import {ASYNC_ITERATOR} from 'shared/ReactSymbols'; +import {enableFlightObjectReferences} from 'shared/ReactFeatureFlags'; import hasOwnProperty from 'shared/hasOwnProperty'; import getPrototypeOf from 'shared/getPrototypeOf'; @@ -220,6 +221,9 @@ export type Response = { _closed: boolean, _closedReason: mixed, _temporaryReferences: void | TemporaryReferenceSet, + _serverReferenceObjects: null | WeakSet, + _serverReferenceCache: WeakMap>, + _serverObjectReferenceCache: WeakMap>, _rootArrayContexts: WeakMap<$ReadOnlyArray, NestedArrayContext>, _arraySizeLimit: number, }; @@ -441,48 +445,25 @@ function loadServerReference, T>( // Check for a cached promise from a previous call with the same metadata. // This handles deduplication when the same server reference appears multiple - // times in the payload. - const cachedPromise: SomeChunk | void = (metaData as any).$$promise; + // times in the payload. The cache is a response-scoped map keyed by the + // metadata object rather than a field on it, so a client-supplied metadata + // field can't inject a resolved value and bypass the manifest lookup below. + const cachedPromise: SomeChunk | void = + response._serverReferenceCache.get(metaData); if (cachedPromise !== undefined) { - if (cachedPromise.status === INITIALIZED) { - // The value was already resolved by a previous call. - const resolvedValue: T = cachedPromise.value; - if (key === __PROTO__) { - return null as any; - } - parentObject[key] = resolvedValue; - return resolvedValue as any; - } - - // The promise is still blocked. Increment the handler dependency count ... - let handler: InitializationHandler; - if (initializingHandler) { - handler = initializingHandler; - handler.deps++; - } else { - handler = initializingHandler = { - chunk: null, - value: null, - reason: null, - deps: 1, - errored: false, - }; - } - // ... and register resolve and reject listeners on the promise. - cachedPromise.then( - resolveReference.bind(null, response, handler, parentObject, key), - rejectReference.bind(null, response, handler), - ); - - // Return a place holder value for now. - return null as any; + return readServerReference( + response, + cachedPromise, + parentObject, + key, + ) as any; } // This is the first call for this server reference metadata. Create a cached // promise to be used for subsequent calls. // $FlowFixMe[invalid-constructor] Flow doesn't support functions as constructors const blockedPromise: BlockedChunk = new ReactPromise(BLOCKED, null, null); - (metaData as any).$$promise = blockedPromise; + response._serverReferenceCache.set(metaData, blockedPromise); const serverReference: ServerReference = resolveServerReference<$FlowFixMe>(response._bundlerConfig, id); @@ -496,92 +477,180 @@ function loadServerReference, T>( if (bound instanceof ReactPromise) { serverReferencePromise = Promise.resolve(bound); } else { - const resolvedValue = requireModule(serverReference) as any; - // Resolve the cached promise synchronously. - const initializedPromise: InitializedChunk = blockedPromise as any; - initializedPromise.status = INITIALIZED; - initializedPromise.value = resolvedValue; - initializedPromise.reason = null; - return resolvedValue; + // Nothing to preload and no bound arguments to wait for, so we can + // resolve the reference synchronously. + const value = requireServerReference(response, serverReference) as any; + resolveServerReferenceChunk(response, blockedPromise, value); + return readServerReference( + response, + blockedPromise, + parentObject, + key, + ) as any; } } else if (bound instanceof ReactPromise) { serverReferencePromise = Promise.all([serverReferencePromise, bound]); } - let handler: InitializationHandler; - if (initializingHandler) { - handler = initializingHandler; - handler.deps++; - } else { - handler = initializingHandler = { - chunk: null, - value: null, - reason: null, - deps: 1, - errored: false, - }; - } - function fulfill(): void { - let resolvedValue = requireModule(serverReference) as any; - - if (metaData.bound) { - // This promise is coming from us and should have initialized by now. - const promiseValue = (metaData.bound as any).value; - const boundArgs: Array = isArray(promiseValue) - ? promiseValue.slice(0) - : []; - if (boundArgs.length > MAX_BOUND_ARGS) { - reject( - new Error( + let value; + try { + value = requireServerReference(response, serverReference) as any; + if (metaData.bound) { + // This promise is coming from us and should have initialized by now. + const promiseValue = (metaData.bound as any).value; + const boundArgs: Array = isArray(promiseValue) + ? promiseValue.slice(0) + : []; + if (boundArgs.length > MAX_BOUND_ARGS) { + throw new Error( 'Server Function has too many bound arguments. Received ' + boundArgs.length + ' but the limit is ' + MAX_BOUND_ARGS + '.', - ), - ); - return; + ); + } + boundArgs.unshift(null); // this + value = value.bind.apply(value, boundArgs); } - boundArgs.unshift(null); // this - resolvedValue = resolvedValue.bind.apply(resolvedValue, boundArgs); + } catch (error) { + triggerErrorOnChunk(response, blockedPromise, error); + return; } + resolveServerReferenceChunk(response, blockedPromise, value); + } + serverReferencePromise.then(fulfill, error => { + triggerErrorOnChunk(response, blockedPromise, error); + }); + return readServerReference( + response, + blockedPromise, + parentObject, + key, + ) as any; +} - // Resolve the cached promise so subsequent references can use the value. - const resolveListeners = blockedPromise.value; - const initializedPromise: InitializedChunk = blockedPromise as any; - initializedPromise.status = INITIALIZED; - initializedPromise.value = resolvedValue; - initializedPromise.reason = null; - if (resolveListeners !== null) { - // Notify any resolve listeners that were added via .then() from - // subsequent loadServerReference calls for the same reference. - wakeChunk(response, resolveListeners, resolvedValue, initializedPromise); +function requireServerReference( + response: Response, + reference: ServerReference, +): T { + const value = requireModule(reference); + if ( + typeof value === 'object' && + // $FlowFixMe[invalid-compare] Module exports can be null at runtime. + value !== null + ) { + // A manifest export can be a fresh, untagged object. Remember its origin + // so reply property paths cannot read it as if it came from the client. + let serverReferenceObjects = response._serverReferenceObjects; + if (serverReferenceObjects === null) { + serverReferenceObjects = response._serverReferenceObjects = new WeakSet(); } + serverReferenceObjects.add(value); + } + return value; +} - resolveReference(response, handler, parentObject, key, resolvedValue); +function resolveServerReferenceChunk( + response: Response, + chunk: BlockedChunk, + value: T, +): void { + const resolveListeners = chunk.value; + const initializedChunk: InitializedChunk = chunk as any; + initializedChunk.status = INITIALIZED; + initializedChunk.value = value; + initializedChunk.reason = null; + if (resolveListeners !== null) { + wakeChunk(response, resolveListeners, value, initializedChunk); } +} - function reject(error: mixed): void { - // Mark the cached promise as errored so subsequent references fail too. - const rejectListeners = blockedPromise.reason; - const erroredPromise: ErroredChunk = blockedPromise as any; - erroredPromise.status = ERRORED; - erroredPromise.value = null; - erroredPromise.reason = error; - if (rejectListeners !== null) { - // Notify any reject listeners that were added via .then() from subsequent - // loadServerReference calls for the same reference. - rejectChunk(response, rejectListeners, error); - } +function readServerReference( + response: Response, + chunk: SomeChunk, + parentObject: Object, + key: string, +): T { + switch (chunk.status) { + case INITIALIZED: + return chunk.value; + case BLOCKED: + return waitForReference( + response, + chunk, + parentObject, + key, + null, + createModel, + [], + ); + default: + throw chunk.reason; + } +} - rejectReference(response, handler, error); +function loadServerObjectReference( + response: Response, + metaData: {id: any}, + parentObject: Object, + key: string, +): mixed { + const id: ServerReferenceId = metaData.id; + if (typeof id !== 'string') { + return null; } - serverReferencePromise.then(fulfill, reject); + // Object references are cached in a separate response-scoped map from + // function references. The same metadata object can be referenced both ways, + // and each path must read only its own cache so it always applies its own + // validation instead of the other's cached value. + const cachedPromise: SomeChunk | void = + response._serverObjectReferenceCache.get(metaData); + if (cachedPromise !== undefined) { + return readServerReference(response, cachedPromise, parentObject, key); + } - // Return a place holder value for now. - return null as any; + // $FlowFixMe[invalid-constructor] Flow doesn't support functions as constructors + const blockedPromise: BlockedChunk = new ReactPromise( + BLOCKED, + null, + null, + ); + response._serverObjectReferenceCache.set(metaData, blockedPromise); + + const serverReference = resolveServerReference<$FlowFixMe>( + response._bundlerConfig, + id, + ); + const serverReferencePromise = preloadModule(serverReference); + + function fulfill(): void { + let value; + try { + value = requireServerReference(response, serverReference); + // Objects can appear under "then", but a function here would turn + // the containing object into a thenable during reply decoding. + if (typeof value !== 'object' || value === null) { + throw new Error( + 'Expected a Server Reference to an object to resolve to an object.', + ); + } + } catch (error) { + triggerErrorOnChunk(response, blockedPromise, error); + return; + } + resolveServerReferenceChunk(response, blockedPromise, value); + } + if (serverReferencePromise === null) { + fulfill(); + } else { + serverReferencePromise.then(fulfill, error => { + triggerErrorOnChunk(response, blockedPromise, error); + }); + } + return readServerReference(response, blockedPromise, parentObject, key); } function reviveModel( @@ -867,12 +936,15 @@ function fulfillReference( try { let localLength: number = 0; const rootArrayContexts = response._rootArrayContexts; + const serverReferenceObjects = response._serverReferenceObjects; for (let i = 1; i < path.length; i++) { // The server doesn't have any lazy references so we don't expect to go through a Promise. const name = path[i]; if ( typeof value === 'object' && value !== null && + (serverReferenceObjects === null || + !serverReferenceObjects.has(value)) && (getPrototypeOf(value) === ObjectPrototype || getPrototypeOf(value) === ArrayPrototype) && hasOwnProperty.call(value, name) @@ -1075,12 +1147,15 @@ function getOutlinedModel( let localLength: number = 0; const rootArrayContexts = response._rootArrayContexts; + const serverReferenceObjects = response._serverReferenceObjects; for (let i = 1; i < path.length; i++) { const name = path[i]; if ( typeof value === 'object' && // $FlowFixMe[invalid-compare] This check is still needed at runtime. value !== null && + (serverReferenceObjects === null || + !serverReferenceObjects.has(value)) && (getPrototypeOf(value) === ObjectPrototype || getPrototypeOf(value) === ArrayPrototype) && hasOwnProperty.call(value, name) @@ -1169,11 +1244,27 @@ function getOutlinedModel( } } +function isServerReferenceObject(response: Response, value: mixed): boolean { + // A Server Reference to an object is opaque: the client may only pass it + // back to the server, never have its contents read out. The consuming + // decoders below (Map, Set, iterator) read their initializer array directly, + // without traversing a property path, so the opacity guard in the path + // walkers doesn't cover them. They reject a server-owned array up front, + // before consuming or mutating it, by checking this alongside `isArray`. + const serverReferenceObjects = response._serverReferenceObjects; + return ( + serverReferenceObjects !== null && + typeof value === 'object' && + value !== null && + serverReferenceObjects.has(value) + ); +} + function createMap( response: Response, model: Array<[any, any]>, ): Map { - if (!isArray(model)) { + if (!isArray(model) || isServerReferenceObject(response, model)) { throw new Error('Invalid Map initializer.'); } if ((model as any).$$consumed === true) { @@ -1186,7 +1277,7 @@ function createMap( } function createSet(response: Response, model: Array): Set { - if (!isArray(model)) { + if (!isArray(model) || isServerReferenceObject(response, model)) { throw new Error('Invalid Set initializer.'); } if ((model as any).$$consumed === true) { @@ -1199,7 +1290,7 @@ function createSet(response: Response, model: Array): Set { } function extractIterator(response: Response, model: Array): Iterator { - if (!isArray(model)) { + if (!isArray(model) || isServerReferenceObject(response, model)) { throw new Error('Invalid Iterator initializer.'); } if ((model as any).$$consumed === true) { @@ -1625,6 +1716,24 @@ function parseModelString( loadServerReference, ); } + case 'H': { + if (enableFlightObjectReferences) { + // Server Reference to an object. Its metadata carries only an id — + // no bound arguments — and it resolves through the same manifest + // lookup as a function reference, which returns the module export + // without calling it. + const ref = value.slice(2); + return getOutlinedModel( + response, + ref, + obj, + key, + null, + loadServerObjectReference, + ); + } + return undefined; + } case 'T': { // Temporary Reference if ( @@ -1937,6 +2046,9 @@ export function createResponse( _closed: false, _closedReason: null, _temporaryReferences: temporaryReferences, + _serverReferenceObjects: null, + _serverReferenceCache: new WeakMap(), + _serverObjectReferenceCache: new WeakMap(), _rootArrayContexts: new WeakMap(), _arraySizeLimit: arraySizeLimit, }; diff --git a/packages/react-server/src/ReactFlightServer.js b/packages/react-server/src/ReactFlightServer.js index e3893a75de3b..3bd2d581ae98 100644 --- a/packages/react-server/src/ReactFlightServer.js +++ b/packages/react-server/src/ReactFlightServer.js @@ -17,6 +17,7 @@ import { enableComponentPerformanceTrack, enableAsyncDebugInfo, enableFlightWeakThenables, + enableFlightObjectReferences, } from 'shared/ReactFeatureFlags'; import { @@ -2962,6 +2963,8 @@ function resolveModel( if ( value !== null && typeof value === 'object' && + // Registered objects are opaque, including objects with a toJSON method. + !(enableFlightObjectReferences && isServerReference(value)) && // $FlowFixMe[method-unbinding] typeof value.toJSON === 'function' ) { @@ -3087,6 +3090,10 @@ function serializeServerReferenceID(id: number): string { return '$h' + id.toString(16); } +function serializeServerObjectReferenceID(id: number): string { + return '$H' + id.toString(16); +} + function serializeSymbolReference(name: string): string { return '$S' + name; } @@ -3307,63 +3314,76 @@ function serializeServerReference( request: Request, serverReference: ServerReference, ): string { + const isObjectReference = + enableFlightObjectReferences && typeof serverReference === 'object'; const writtenServerReferences = request.writtenServerReferences; const existingId = writtenServerReferences.get(serverReference); if (existingId !== undefined) { - return serializeServerReferenceID(existingId); + return isObjectReference + ? serializeServerObjectReferenceID(existingId) + : serializeServerReferenceID(existingId); } - const boundArgs: null | Array = getServerReferenceBoundArguments( - request.bundlerConfig, - serverReference, - ); - const bound = boundArgs === null ? null : Promise.resolve(boundArgs); const id = getServerReferenceId(request.bundlerConfig, serverReference); - - let location: null | ReactFunctionLocation = null; - if (__DEV__) { - const error = getServerReferenceLocation( + let serverReferenceMetadata: { + id: ServerReferenceId, + bound?: null | Promise>, + name?: string, // DEV-only + env?: string, // DEV-only + location?: ReactFunctionLocation, // DEV-only + }; + if (isObjectReference) { + // Objects share the manifest lookup with functions, but have no bound + // arguments or function debug metadata. + serverReferenceMetadata = {id}; + } else { + const boundArgs: null | Array = getServerReferenceBoundArguments( request.bundlerConfig, serverReference, ); - // $FlowFixMe[constant-condition] - if (error) { - const frames = parseStackTrace(error, 1); - if (frames.length > 0) { - const firstFrame = frames[0]; - location = [ - firstFrame[0], - firstFrame[1], - firstFrame[2], // The line and col of the callsite represents the - firstFrame[3], // enclosing line and col of the function. - ]; + const bound = boundArgs === null ? null : Promise.resolve(boundArgs); + + let location: null | ReactFunctionLocation = null; + if (__DEV__) { + const error = getServerReferenceLocation( + request.bundlerConfig, + serverReference, + ); + // $FlowFixMe[constant-condition] + if (error) { + const frames = parseStackTrace(error, 1); + if (frames.length > 0) { + const firstFrame = frames[0]; + location = [ + firstFrame[0], + firstFrame[1], + firstFrame[2], // The line and col of the callsite represents the + firstFrame[3], // enclosing line and col of the function. + ]; + } } } - } - const serverReferenceMetadata: { - id: ServerReferenceId, - bound: null | Promise>, - name?: string, // DEV-only - env?: string, // DEV-only - location?: ReactFunctionLocation, // DEV-only - } = - __DEV__ && location !== null - ? { - id, - bound, - name: - typeof serverReference === 'function' ? serverReference.name : '', - env: (0, request.environmentName)(), - location, - } - : { - id, - bound, - }; + serverReferenceMetadata = + __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); + return isObjectReference + ? serializeServerObjectReferenceID(metadataId) + : serializeServerReferenceID(metadataId); } function serializeTemporaryReference( @@ -3994,6 +4014,13 @@ function renderModelDestructive( ); } + if (enableFlightObjectReferences && isServerReference(value)) { + // An object registered as a Server Reference. This must be checked + // before the thenable case below so that a reference that happens to + // be a Promise is serialized by reference instead of being awaited. + return serializeServerReference(request, value as any); + } + if (request.temporaryReferences !== undefined) { const tempRef = resolveTemporaryReference( request.temporaryReferences, @@ -6167,6 +6194,18 @@ function emitChunk( emitTextChunk(request, id, value, false); return; } + if ( + enableFlightObjectReferences && + typeof value === 'object' && + value !== null && + isServerReference(value) + ) { + // Streamed values reach this function before model serialization. Keep + // registered binary objects opaque instead of emitting their bytes. + const json = stringify(serializeServerReference(request, value as any)); + emitModelChunk(request, id, json); + return; + } if (value instanceof ArrayBuffer) { emitTypedArrayChunk(request, id, 'A', new Uint8Array(value), false); return; diff --git a/packages/shared/ReactFeatureFlags.js b/packages/shared/ReactFeatureFlags.js index 33076ed502f7..e1f55b69a966 100644 --- a/packages/shared/ReactFeatureFlags.js +++ b/packages/shared/ReactFeatureFlags.js @@ -85,6 +85,12 @@ export const enableAsyncIterableChildren = __EXPERIMENTAL__; // left unfulfilled. export const enableFlightWeakThenables = __EXPERIMENTAL__; +// Support Server References that point to objects (including Promises), not +// just functions. On the server the reference is the real object; on the +// client it's an opaque handle that can only be passed back to the server, +// where it resolves via the manifest. +export const enableFlightObjectReferences = __EXPERIMENTAL__; + export const enableTaint = __EXPERIMENTAL__; export const enableViewTransition: boolean = true; diff --git a/packages/shared/forks/ReactFeatureFlags.native-fb.js b/packages/shared/forks/ReactFeatureFlags.native-fb.js index 2c7e8655c578..6b68a3e634dc 100644 --- a/packages/shared/forks/ReactFeatureFlags.native-fb.js +++ b/packages/shared/forks/ReactFeatureFlags.native-fb.js @@ -40,6 +40,7 @@ export const disableTextareaChildren: boolean = false; export const enableAsyncDebugInfo: boolean = true; export const enableAsyncIterableChildren: boolean = false; export const enableFlightWeakThenables: boolean = false; +export const enableFlightObjectReferences: boolean = false; export const enableCPUSuspense: boolean = true; export const enableCreateEventHandleAPI: boolean = false; export const enableBrowserAPI: boolean = true; diff --git a/packages/shared/forks/ReactFeatureFlags.native-oss.js b/packages/shared/forks/ReactFeatureFlags.native-oss.js index e9ca0bec7f0a..7b1449469855 100644 --- a/packages/shared/forks/ReactFeatureFlags.native-oss.js +++ b/packages/shared/forks/ReactFeatureFlags.native-oss.js @@ -27,6 +27,7 @@ export const disableTextareaChildren: boolean = false; export const enableAsyncDebugInfo: boolean = true; export const enableAsyncIterableChildren: boolean = false; export const enableFlightWeakThenables: boolean = false; +export const enableFlightObjectReferences: boolean = false; export const enableCPUSuspense: boolean = false; export const enableCreateEventHandleAPI: boolean = false; export const enableBrowserAPI: boolean = true; diff --git a/packages/shared/forks/ReactFeatureFlags.test-renderer.js b/packages/shared/forks/ReactFeatureFlags.test-renderer.js index 0a6a4b098dd0..6c41b3dc8a41 100644 --- a/packages/shared/forks/ReactFeatureFlags.test-renderer.js +++ b/packages/shared/forks/ReactFeatureFlags.test-renderer.js @@ -21,6 +21,7 @@ export const enableUpdaterTracking: boolean = false; export const enableLegacyCache: boolean = __EXPERIMENTAL__; export const enableAsyncIterableChildren: boolean = false; export const enableFlightWeakThenables: boolean = false; +export const enableFlightObjectReferences: boolean = false; export const enableTaint: boolean = true; export const disableCommentsAsDOMContainers: boolean = true; export const disableInputAttributeSyncing: boolean = false; diff --git a/packages/shared/forks/ReactFeatureFlags.test-renderer.native-fb.js b/packages/shared/forks/ReactFeatureFlags.test-renderer.native-fb.js index df401fdc2a10..1fa612e47dc6 100644 --- a/packages/shared/forks/ReactFeatureFlags.test-renderer.native-fb.js +++ b/packages/shared/forks/ReactFeatureFlags.test-renderer.native-fb.js @@ -22,6 +22,7 @@ export const disableTextareaChildren = false; export const enableAsyncDebugInfo = true; export const enableAsyncIterableChildren = false; export const enableFlightWeakThenables = false; +export const enableFlightObjectReferences = false; export const enableCPUSuspense = true; export const enableCreateEventHandleAPI = false; export const enableBrowserAPI = true; diff --git a/packages/shared/forks/ReactFeatureFlags.test-renderer.www.js b/packages/shared/forks/ReactFeatureFlags.test-renderer.www.js index 0854641c6133..f93a881904c7 100644 --- a/packages/shared/forks/ReactFeatureFlags.test-renderer.www.js +++ b/packages/shared/forks/ReactFeatureFlags.test-renderer.www.js @@ -21,6 +21,7 @@ export const enableUpdaterTracking: boolean = false; export const enableLegacyCache: boolean = true; export const enableAsyncIterableChildren: boolean = false; export const enableFlightWeakThenables: boolean = false; +export const enableFlightObjectReferences: boolean = false; export const enableTaint: boolean = true; export const disableCommentsAsDOMContainers: boolean = true; export const disableInputAttributeSyncing: boolean = false; diff --git a/packages/shared/forks/ReactFeatureFlags.www.js b/packages/shared/forks/ReactFeatureFlags.www.js index 3d83feb32885..aa79cb725ca9 100644 --- a/packages/shared/forks/ReactFeatureFlags.www.js +++ b/packages/shared/forks/ReactFeatureFlags.www.js @@ -71,6 +71,7 @@ export const enableLegacyCache: boolean = true; export const enableAsyncIterableChildren: boolean = false; export const enableFlightWeakThenables: boolean = false; +export const enableFlightObjectReferences: boolean = false; export const enableTaint: boolean = false; diff --git a/scripts/error-codes/codes.json b/scripts/error-codes/codes.json index ba39b2b6acc5..4ed82252c8ae 100644 --- a/scripts/error-codes/codes.json +++ b/scripts/error-codes/codes.json @@ -593,5 +593,8 @@ "605": "Recoverable Exception: This is not a real error! It's an implementation detail of `use` to interrupt the current render so a downstream renderer can recover it. You must either rethrow it immediately, or move the `use` call outside of the `try/catch` block. Capturing without rethrowing will lead to unexpected behavior.", "606": "Expected a suspended recoverable. This is a bug in React. Please file an issue.", "607": "This library called use() to suspend in a previous render but did not call use() when it finished. This indicates an incorrect use of use(). Learn more: https://react.dev/warnings/conditional-use-of-use", - "608": "A client reference was blocked on a row that has not been received yet. This is a bug in React." + "608": "A client reference was blocked on a row that has not been received yet. This is a bug in React.", + "609": "Cannot access %s on the client. You cannot read a Server Reference to an object on the client. You can only pass it back to the server.", + "610": "Cannot assign to a Server Reference to an object on the client.", + "611": "Expected a Server Reference to an object to resolve to an object." }