[Fizz] Implement `renderDocument` #25970

gnoff · 2023-01-07T01:04:02Z

stacked on #25703

`renderDocument` and `renderDocumentAsPipeableStream`

This PR adds a new rendering mode for rendering an entire Document on the server.

Example

On the server use renderDocument and stream the results to the client

// ReadableStream gets passed to Response or otherwise piped to browser
const stream = renderDocument(
  // children
  <html lang="en">
    <body>
      <div>my primary app</div>
    </body>
  </html>,
  // fallback
  <div>a fallback app</div>
);

Client receives if the Shell does not error for the primary children

<!DOCTYPE html>
<html lang="en">
  <head></head>
  <body>
    <div>my primary app</div>
  </body>
</html>

Client receives the following if the Shell does error for the primary children

<!DOCTYPE html>
<html lang="en">
  <head></head>
  <body>
    <div>a fallback app</div>
  </body>
</html>

Primary Characteristics

There are three primary distinguishing characteristics with the renderDocument implementations that explain why existing functions such as renderToReadableStream were not suitable

It always emits a full HTML document even if you only render some body content. With other render methods you only get what you tell React to render for you so if you render a div with some inner content that is all React will output. Using one of the existing render functions requires you to carefully control what is rendered and if you have intermediate layers (like a framework) in place it can force you into a situation where the App author needs to remember to include the document structure (<html>, <head>, etc...) or not be allowed to provide it at all. The flexibility of embedding whatever renderDocument is given in a full HTML document alleviates this limitation
It will attempt to stream preamble content as early as possible, even before the shell has finished rendering. If we discover a stylesheet or script that can be preloaded or preinitialized while still waiting of the shell to complete rendering we want to send that to the client right away. renderToReadableStream does not provide you with the stream until the shell has finished.
It provides allows you to provide a fallback that will render if the Shell for children errors. While other methods don't flush anything until the Shell finishes and thus you can spin up a separate render call, or handle the error case with a different status code and response content the renderDocument function likely already sent bytes before the Shell has errored so it must coordinate the fallback state more holistically.

Resource Flushing Semantics

Some Resources can flush even before the Shell is finished, including preloads, and scripts. Stylesheets for the first precedence can be flushed as well and we can send preloads for stylesheeets for other precedences. The reason we cannot flush all stylesheets of any precedence early is we need the order to be guaranteed and we don't do any re-ordering on the client so they need to leave the server in the right order unless they are delivered as part of a Suspense Boundary reveal.

Ancillary PR note

A related incidental change accompanies this PR for the other render methods. If we render an <html> tag but do not render a <head> tag, we will emit an <head> tag into the stream just after <html> and before any other rendered content (usually a <body> but you can have non-spec html). It is possible this tag won't be empty because any Resources that get hoisted to the head will emit there. Currently these tags emit after the html tag and before any rendered content which may work based on permissive Browser HTML parsing rules but is not valid HTML. One might try to argue this is a breaking change but relying on there NOT being a <head> is not practically possible given the Browser invents a DOM node for this head anyway

packages/react-dom-bindings/src/server/ReactDOMServerFormatConfig.js

## Summary Should unblock #25970 If the callback for `toWarnDev` was `async` and threw, we didn't ultimately reject the await Promise from the matcher. This resulted in tests failing even though the failure was expected due to a test gate. ## How did you test this change? - [x] tested in #25970 with `yarn test --r=stable --env=development packages/react-dom/src/__tests__/ReactDOMFizzServer-test.js --watch` - [x] `yarn test` - [x] CI

## Summary Should unblock #25970 If the callback for `toWarnDev` was `async` and threw, we didn't ultimately reject the await Promise from the matcher. This resulted in tests failing even though the failure was expected due to a test gate. ## How did you test this change? - [x] tested in #25970 with `yarn test --r=stable --env=development packages/react-dom/src/__tests__/ReactDOMFizzServer-test.js --watch` - [x] `yarn test` - [x] CI DiffTrain build for [4f8ffec](4f8ffec) [View git log for this commit](https://github.com/facebook/react/commits/4f8ffec453c41fcb6e98cb4e003f7319bb1c81b9)

renderIntoContainer allows you to stream react into a specific DOM node identified by a element ID. It returns a ReadableStream but differs from renderToReadableStream in that you get access to the stream syncronously. Since the top level Component gets inserted like a boundary I am calling what would normally be the "Shell" of a React app the Root Boundary when using renderIntoContainer. While the top level Components stream in like a boundary there is not actually a Suspense Boundary wrapper. However it will act like one in that stylesheets will be loaded before the content is revealed in the container Node. If stylehseet loading fails hydration will fall back to client rendering It allows the passing of fallback bootstrap scripts which are used if the Root Boundary errors.

sebmarkbage · 2023-01-16T20:19:27Z

Nit: I get that renderIntoDocument is supposed to mean that document is the container argument but it doesn't make sense unless you also consider the hydrateRoot API so it's a bit weird. It also doesn't provide a difference from renderIntoContainer. Like what if the container is the document?

If you just consider the SSR document it's more like you render the "whole" document.

renderDocument or renderWholeDocument might make the distinction clearer.

sebmarkbage · 2023-01-16T21:49:57Z

packages/shared/forks/ReactFeatureFlags.www.js

@@ -109,6 +109,7 @@ export const useModernStrictMode = false;
 export const enableFizzExternalRuntime = true;

 export const enableFizzIntoContainer = __EXPERIMENTAL__;
+export const enableFizzIntoDocument = __EXPERIMENTAL__;


Same as the other one, might as well turn this one on since its use is optional.

sebmarkbage · 2023-01-16T21:50:19Z

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

@@ -87,6 +87,7 @@ export const useModernStrictMode = false;
 export const enableFizzExternalRuntime = false;

 export const enableFizzIntoContainer = false;
+export const enableFizzIntoDocument = false;


Turn the flag on in anything that's not expected to use it.

sebmarkbage · 2023-01-16T21:54:00Z

packages/react-dom-bindings/src/server/ReactDOMServerFormatConfig.js

@@ -123,6 +123,9 @@ const DataStreamingFormat: StreamingFormat = 1;
 export type ResponseState = {
  bootstrapChunks: Array<Chunk | PrecomputedChunk>,
  fallbackBootstrapChunks: void | Array<Chunk | PrecomputedChunk>,
+  requiresEmbedding: boolean,
+  hasHead: boolean,
+  hasHtml: boolean,


Sometimes V8 will deopt objects with more than 16 properties or something like that. It's probably time to consolidate these to a bitmask.

Same thing with sentXFunction can probably just be a bitmask of which ones have been sent.

I've force pushed a number of updates since this was in the commits. I think I sent you a commit range but that has been outdated for a while. I worry you probably reviewed a quite outdated version of the implemenation. For this bit of feedback in particular I already updated to a bitmask. I could consolidate further since I'm not using very many of the bits

sebmarkbage · 2023-01-16T22:16:29Z

packages/react-server/src/ReactFizzServer.js

@@ -2301,18 +2305,15 @@ function flushCompletedQueues(
      if (request.pendingRootTasks === 0) {
        if (enableFloat) {
          const preamble = request.preamble;
-          for (i = 0; i < preamble.length; i++) {
-            // we expect the preamble to be tiny and will ignore backpressure


This comment is still relevant.

sebmarkbage · 2023-01-16T22:36:04Z

packages/react-server/src/ReactFizzServer.js

@@ -2301,18 +2305,15 @@ function flushCompletedQueues(
      if (request.pendingRootTasks === 0) {
        if (enableFloat) {
          const preamble = request.preamble;


It's probably time to rethink the concept of request.preamble. It was an elegant way to solve this problem before, but now it's way more complicated so it's not elegant and just unnecessary. The information is encoded on the responseState anyway.

sebmarkbage · 2023-01-16T22:39:29Z

packages/react-dom-bindings/src/server/ReactDOMServerFormatConfig.js

+    let includedAttributeProps = false;
+
+    if (!responseState.hasHead) {
+      responseState.hasHead = true;


<head> should not allow any attributes in this mode. It's too flaky in case we flush the preamble before it's discovered so it would have different semantics in different cases depending on data. So it should never have attributes to avoid you accidentally relying on it.

In other words, this can all be much more simplified because in this mode, you never write head when pushing.

You can always write head when you're writing the HTML tag. Whether it's implicit or not.

That means that the whole thing gets much more simplified because the whole preamble is just a boolean. Whether you have html+head or not.

…in instruction writing

This commit adds the function renderIntoDocument in react-dom/server and adds the ability to embed the rendered children in the necessary html tags to repereset a full document. this means you can render "<html>...</html>" or "<div>...</div>" and either way the render will emit html, head, and body tags as necessary to describe a valid and complete HTML page. Like renderIntoContainer, renderIntoDocument provides a stream immediately. While there is a shell of sorts this fucntion will start writing content from the preamble (html and head tags, plus resources that flush in the head) before finishing the shell. Additionally renderIntoContainer accepts fallback children and fallback bootstrap script options. If the Shell errors the fallback children will render instead of children. The expectation is that the client will attempt to render fresh on the client.

gnoff · 2023-01-18T18:59:11Z

Nit: I get that renderIntoDocument is supposed to mean that document is the container argument but it doesn't make sense unless you also consider the hydrateRoot API so it's a bit weird. It also doesn't provide a difference from renderIntoContainer. Like what if the container is the document?

If you just consider the SSR document it's more like you render the "whole" document.

renderDocument or renderWholeDocument might make the distinction clearer.

I updated to renderDocument. rationale makes sense

gnoff · 2023-12-07T18:41:53Z

With the implementation of onHeaders this new API is less necessary since we can do some preloading of resources even if we don't have a shell. There is still work to do to optimize flushing of the head early and some evolution of the promise API for render but going to close this PR and pursue that in other forms

## Summary Should unblock facebook/react#25970 If the callback for `toWarnDev` was `async` and threw, we didn't ultimately reject the await Promise from the matcher. This resulted in tests failing even though the failure was expected due to a test gate. ## How did you test this change? - [x] tested in facebook/react#25970 with `yarn test --r=stable --env=development packages/react-dom/src/__tests__/ReactDOMFizzServer-test.js --watch` - [x] `yarn test` - [x] CI DiffTrain build for [4f8ffec453c41fcb6e98cb4e003f7319bb1c81b9](facebook/react@4f8ffec) [View git log for this commit](https://github.com/facebook/react/commits/4f8ffec453c41fcb6e98cb4e003f7319bb1c81b9)

facebook-github-bot added CLA Signed React Core Team Opened by a member of the React Core Team labels Jan 7, 2023

gnoff marked this pull request as draft January 7, 2023 01:04

gnoff force-pushed the fizz-into-document branch from bb08b6d to 65cf1fa Compare January 8, 2023 01:16

gnoff commented Jan 8, 2023

View reviewed changes

packages/react-dom-bindings/src/server/ReactDOMServerFormatConfig.js Outdated Show resolved Hide resolved

gnoff force-pushed the fizz-into-document branch 2 times, most recently from 6309c30 to 74de63c Compare January 10, 2023 22:49

gnoff marked this pull request as ready for review January 11, 2023 02:27

gnoff requested review from sebmarkbage and mofeiZ January 11, 2023 02:27

gnoff force-pushed the fizz-into-document branch 4 times, most recently from 5abeef7 to 308599c Compare January 12, 2023 21:29

eps1lon mentioned this pull request Jan 15, 2023

Rejct toWarnDev if given callback throws #26003

Merged

3 tasks

gnoff force-pushed the fizz-into-document branch from a835230 to 7373264 Compare January 15, 2023 23:04

gnoff added 4 commits January 16, 2023 09:39

only expose renderIntoContainer* when feature flag is on

d19b102

refactor external runtime instruction execution

0c2c4a3

refactor inline runtime for style insertion

8be28e5

gnoff force-pushed the fizz-into-document branch from 7373264 to 45a1577 Compare January 16, 2023 17:39

sebmarkbage reviewed Jan 16, 2023

View reviewed changes

gnoff added 5 commits January 17, 2023 12:21

refactor root boundary ID out of responseState and eliminate forking …

f472e4b

…in instruction writing

update export to statically exclude renderIntoContainer in stable build

d6002cf

revert change to ReactVersion

3273db7

reduce stack assignment

9bad42a

refactor external runtime instructions for density

8e5cd60

gnoff force-pushed the fizz-into-document branch from 45a1577 to 3ec1561 Compare January 18, 2023 18:53

gnoff changed the title ~~[Fizz] Implement renderIntoDocument~~ [Fizz] Implement renderDocument Jan 18, 2023

rename renderIntoDocument as renderDocument

15e4c45

gnoff force-pushed the fizz-into-document branch from af13a1c to 15e4c45 Compare January 18, 2023 19:04

gnoff closed this Dec 7, 2023

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

[Fizz] Implement `renderDocument` #25970

[Fizz] Implement `renderDocument` #25970

gnoff commented Jan 7, 2023 •

edited

Loading

sebmarkbage commented Jan 16, 2023

sebmarkbage Jan 16, 2023

sebmarkbage Jan 16, 2023

sebmarkbage Jan 16, 2023

gnoff Jan 16, 2023

sebmarkbage Jan 16, 2023

sebmarkbage Jan 16, 2023

sebmarkbage Jan 16, 2023

gnoff commented Jan 18, 2023

gnoff commented Dec 7, 2023

[Fizz] Implement renderDocument #25970

[Fizz] Implement renderDocument #25970

Conversation

gnoff commented Jan 7, 2023 • edited Loading

renderDocument and renderDocumentAsPipeableStream

Example

Primary Characteristics

Resource Flushing Semantics

Ancillary PR note

sebmarkbage commented Jan 16, 2023

sebmarkbage Jan 16, 2023

Choose a reason for hiding this comment

sebmarkbage Jan 16, 2023

Choose a reason for hiding this comment

sebmarkbage Jan 16, 2023

Choose a reason for hiding this comment

gnoff Jan 16, 2023

Choose a reason for hiding this comment

sebmarkbage Jan 16, 2023

Choose a reason for hiding this comment

sebmarkbage Jan 16, 2023

Choose a reason for hiding this comment

sebmarkbage Jan 16, 2023

Choose a reason for hiding this comment

gnoff commented Jan 18, 2023

gnoff commented Dec 7, 2023

[Fizz] Implement `renderDocument` #25970

[Fizz] Implement `renderDocument` #25970

gnoff commented Jan 7, 2023 •

edited

Loading

`renderDocument` and `renderDocumentAsPipeableStream`