fix: handle RSC reload document responses

Author: agcty

.changeset/rsc-reload-document.md

@@ -0,0 +1,5 @@
+---
+"react-router": patch
+---
+
+Handle reload-document responses in RSC browser fetches without attempting to decode an empty RSC payload.

packages/react-router/__tests__/rsc/browser-test.ts

@@ -0,0 +1,84 @@
+import {
+  claimRSCReloadDocumentAttempt,
+  clearRSCReloadDocumentAttempt,
+  getRSCManifestReloadDocumentTarget,
+  getRSCReloadDocumentTarget,
+  isRSCReloadDocumentResponse,
+} from "../../lib/rsc/browser";
+
+describe("RSC document reload recovery", () => {
+  beforeEach(() => {
+    window.history.replaceState(null, "", "/current?tab=one#section");
+    clearRSCReloadDocumentAttempt();
+  });
+
+  it("recognizes reload-document responses", () => {
+    expect(
+      isRSCReloadDocumentResponse(
+        new Response(null, {
+          status: 204,
+          headers: { "X-Remix-Reload-Document": "true" },
+        }),
+      ),
+    ).toBe(true);
+
+    expect(
+      isRSCReloadDocumentResponse(
+        new Response(null, {
+          status: 200,
+          headers: { "X-Remix-Reload-Document": "true" },
+        }),
+      ),
+    ).toBe(false);
+  });
+
+  it("reloads GET RSC responses at the document request target", () => {
+    expect(
+      getRSCReloadDocumentTarget(
+        new Request("http://localhost/target?panel=notes#source"),
+      ),
+    ).toBe("http://localhost/target?panel=notes#source");
+  });
+
+  it("reloads mutation RSC responses at the current document", () => {
+    expect(
+      getRSCReloadDocumentTarget(
+        new Request("http://localhost/target", { method: "POST" }),
+      ),
+    ).toBe("http://localhost/current?tab=one#section");
+  });
+
+  it("reloads manifest mismatches at the pending navigation target", () => {
+    // @ts-expect-error partial router global for this focused unit test
+    window.__reactRouterDataRouter = {
+      state: {
+        navigation: {
+          location: {
+            pathname: "/target",
+            search: "?panel=notes",
+            hash: "#source",
+          },
+        },
+      },
+    };
+
+    expect(getRSCManifestReloadDocumentTarget("/target")).toBe(
+      "/target?panel=notes#source",
+    );
+  });
+
+  it("reloads fetcher manifest mismatches at the current document", () => {
+    expect(getRSCManifestReloadDocumentTarget("/target", "fetcher")).toBe(
+      "http://localhost/current?tab=one#section",
+    );
+  });
+
+  it("bounds reload attempts by target URL", () => {
+    expect(claimRSCReloadDocumentAttempt("/target")).toBe(true);
+    expect(claimRSCReloadDocumentAttempt("/target")).toBe(false);
+    expect(claimRSCReloadDocumentAttempt("/other")).toBe(true);
+
+    clearRSCReloadDocumentAttempt();
+    expect(claimRSCReloadDocumentAttempt("/target")).toBe(true);
+  });
+});

packages/react-router/lib/rsc/browser.tsx

@@ -5,7 +5,7 @@ import { RouterProvider } from "../components";
 import { RSCRouterContext } from "../context";
 import { FrameworkContext, setIsHydrated } from "../dom/ssr/components";
 import type { FrameworkContextObject } from "../dom/ssr/entry";
-import { createBrowserHistory, invariant } from "../router/history";
+import { createBrowserHistory, createPath, invariant } from "../router/history";
 import type { Router as DataRouter, RouterInit } from "../router/router";
 import {
   createRouter,
@@ -68,6 +68,8 @@ type WindowWithRouterGlobals = Window &
     __routerActionID: number;
   };
 
+const RSC_RELOAD_DOCUMENT_STORAGE_KEY = "react-router-rsc-reload-document";
+
 /**
  * Create a React `callServer` implementation for React Router.
  *
@@ -123,23 +125,30 @@ export function createCallServer({
       (globalVar.__routerActionID ??= 0) + 1);
 
     const temporaryReferences = createTemporaryReferenceSet();
-    const payloadPromise = fetchImplementation(
-      new Request(location.href, {
-        body: await encodeReply(args, { temporaryReferences }),
-        method: "POST",
-        headers: {
-          Accept: "text/x-component",
-          "rsc-action-id": id,
-        },
-      }),
-    ).then((response) => {
-      if (!response.body) {
-        throw new Error("No response body");
-      }
-      return createFromReadableStream(response.body, {
-        temporaryReferences,
-      }) as Promise<RSCPayload>;
+    const request = new Request(location.href, {
+      body: await encodeReply(args, { temporaryReferences }),
+      method: "POST",
+      headers: {
+        Accept: "text/x-component",
+        "rsc-action-id": id,
+      },
     });
+    const payloadPromise = fetchImplementation(request).then(
+      async (response) => {
+        if (isRSCReloadDocumentResponse(response)) {
+          await reloadRSCResponseDocument(getRSCReloadDocumentTarget(request));
+        }
+
+        clearRSCReloadDocumentAttempt();
+
+        if (!response.body) {
+          throw new Error("No response body");
+        }
+        return createFromReadableStream(response.body, {
+          temporaryReferences,
+        }) as Promise<RSCPayload>;
+      },
+    );
 
     React.startTransition(() =>
       // @ts-expect-error - Needs React 19 types
@@ -301,7 +310,7 @@ function createRouterFromPayload({
       basename: payload.basename,
       isSpaMode: false,
     }),
-    async patchRoutesOnNavigation({ path, signal }) {
+    async patchRoutesOnNavigation({ path, signal, fetcherKey }) {
       if (payload.routeDiscovery.mode === "initial") {
         if (!applyPatchesPromise) {
           applyPatchesPromise = (async () => {
@@ -334,6 +343,7 @@ function createRouterFromPayload({
         createFromReadableStream,
         fetchImplementation,
         signal,
+        getRSCManifestReloadDocumentTarget(path, fetcherKey),
       );
     },
     // FIXME: Pass `build.ssr` into this function
@@ -560,6 +570,12 @@ function getFetchAndDecodeViaRSC(
       new Request(url, await createRequestInit(request)),
     );
 
+    if (isRSCReloadDocumentResponse(res)) {
+      await reloadRSCResponseDocument(getRSCReloadDocumentTarget(request));
+    }
+
+    clearRSCReloadDocumentAttempt();
+
     // If this error'd without hitting the running server, then bubble a normal
     // `ErrorResponse` and don't try to decode the body with `turbo-stream`.
     //
@@ -1039,6 +1055,7 @@ async function fetchAndApplyManifestPatches(
   createFromReadableStream: BrowserCreateFromReadableStreamFunction,
   fetchImplementation: (request: Request) => Promise<Response>,
   signal?: AbortSignal,
+  reloadDocumentPath?: string,
 ) {
   let url = getManifestUrl(paths);
   if (url == null) {
@@ -1054,6 +1071,19 @@ async function fetchAndApplyManifestPatches(
   }
 
   let response = await fetchImplementation(new Request(url, { signal }));
+  if (isRSCReloadDocumentResponse(response)) {
+    if (reloadDocumentPath) {
+      await reloadRSCResponseDocument(reloadDocumentPath);
+    }
+    console.warn(
+      "Detected an RSC manifest version mismatch during eager route discovery. " +
+        "The next navigation to an undiscovered route will reload the document.",
+    );
+    return;
+  }
+
+  clearRSCReloadDocumentAttempt();
+
   if (!response.body || response.status < 200 || response.status >= 300) {
     throw new Error("Unable to fetch new route matches from the server");
   }
@@ -1090,6 +1120,74 @@ function addToFifoQueue(path: string, queue: Set<string>) {
   queue.add(path);
 }
 
+export function isRSCReloadDocumentResponse(response: Response): boolean {
+  return (
+    response.status === 204 && response.headers.has("X-Remix-Reload-Document")
+  );
+}
+
+export function getRSCReloadDocumentTarget(request: Request): string {
+  if (request.method === "GET") {
+    return new URL(request.url, window.location.href).toString();
+  }
+
+  return window.location.href;
+}
+
+export function getRSCManifestReloadDocumentTarget(
+  path: string,
+  fetcherKey?: string,
+): string {
+  if (fetcherKey) {
+    return window.location.href;
+  }
+
+  let navigation = (window as WindowWithRouterGlobals).__reactRouterDataRouter
+    ?.state.navigation;
+  if (navigation?.location) {
+    return createPath(navigation.location);
+  }
+
+  return path;
+}
+
+export function claimRSCReloadDocumentAttempt(target: string): boolean {
+  let href = new URL(target, window.location.href).toString();
+  try {
+    if (sessionStorage.getItem(RSC_RELOAD_DOCUMENT_STORAGE_KEY) === href) {
+      return false;
+    }
+    sessionStorage.setItem(RSC_RELOAD_DOCUMENT_STORAGE_KEY, href);
+  } catch {
+    // If sessionStorage is unavailable, still attempt the reload.
+  }
+  return true;
+}
+
+export function clearRSCReloadDocumentAttempt(): void {
+  try {
+    sessionStorage.removeItem(RSC_RELOAD_DOCUMENT_STORAGE_KEY);
+  } catch {
+    // Session storage unavailable
+  }
+}
+
+async function reloadRSCResponseDocument(target: string): Promise<never> {
+  let href = new URL(target, window.location.href).toString();
+  if (!claimRSCReloadDocumentAttempt(href)) {
+    console.error("Unable to reload document due to RSC version mismatch.");
+    throw new Error("Unable to reload document due to RSC version mismatch.");
+  }
+
+  window.location.assign(href);
+  console.warn("Detected RSC version mismatch, reloading...");
+
+  // Stall here and let the browser reload, avoiding an ErrorBoundary flash.
+  return await new Promise<never>(() => {
+    // Intentionally never resolves.
+  });
+}
+
 // Thanks Josh!
 // https://www.joshwcomeau.com/snippets/javascript/debounce/
 function debounce(callback: (...args: unknown[]) => unknown, wait: number) {