@rangojs/router 0.0.0-experimental.bd6e11bc → 0.0.0-experimental.bdaf10aa

package/src/rsc/progressive-enhancement.ts

@@ -7,12 +7,15 @@
  */
 
 import {
-  requireRequestContext,
+  getRequestContext,
   setRequestContextParams,
 } from "../server/request-context.js";
 import { getSSRSetup } from "./ssr-setup.js";
 import type { MiddlewareFn } from "../router/middleware.js";
 import { executeMiddleware } from "../router/middleware.js";
+import { observePhase, PHASES } from "../router/instrument.js";
+import { gateTransitions } from "./transition-gate.js";
+import { resolvedHandleStream } from "../handles/deferred-resolution.js";
 import type { RscPayload, ReactFormState } from "./types.js";
 import {
   createResponseWithMergedHeaders,
@@ -44,7 +47,7 @@ export async function handleProgressiveEnhancement<TEnv>(
   env: TEnv,
   url: URL,
   isAction: boolean,
-  handleStore: ReturnType<typeof requireRequestContext>["_handleStore"],
+  handleStore: ReturnType<typeof getRequestContext>["_handleStore"],
   nonce: string | undefined,
   routeMwInfo?: PeRouteMiddlewareInfo,
 ): Promise<Response | null> {
@@ -115,6 +118,13 @@ export async function handleProgressiveEnhancement<TEnv>(
   // Execute action and return HTML
   let actionResult: unknown = undefined;
   let reactFormState: ReactFormState | null = null;
+  // Status for the fall-through re-render after a boundaryless action error.
+  // When an action throws and NO error boundary matches, the PE path re-renders
+  // the page (below) the same way it would after a successful action. Without
+  // this the re-render serves HTTP 200, diverging from the JS path which serves
+  // 500 (server-action.ts sets actionStatus=500 for the same boundaryless error).
+  // 500 is carried only into the final HTML response, never the redirect branch.
+  let boundarylessErrorStatus: number | undefined;
 
   if (isUseActionState) {
     // Decode and extract action identity before execution so error
@@ -124,7 +134,11 @@ export async function handleProgressiveEnhancement<TEnv>(
       const boundAction = await ctx.decodeAction(formData);
       // React's custom .bind() preserves $$id on server references.
       useActionStateId = (boundAction as { $$id?: string }).$$id ?? undefined;
-      actionResult = await boundAction();
+      // Meter the no-JS form action as the action phase, same as the JS path.
+      actionResult = await observePhase(
+        PHASES.action(useActionStateId ?? "useActionState"),
+        () => boundAction(),
+      );
     } catch (error) {
       // Handle thrown redirect (e.g., throw redirect('/path'))
       const redirectResponse = extractRedirectResponse(error);
@@ -140,6 +154,7 @@ export async function handleProgressiveEnhancement<TEnv>(
         handleStore,
         nonce,
         useActionStateId,
+        true, // an action ran and threw
       );
       if (errorHtml) return errorHtml;
 
@@ -151,10 +166,21 @@ export async function handleProgressiveEnhancement<TEnv>(
         handledByBoundary: false,
       });
       console.error("[RSC] Progressive enhancement action error:", error);
+      // No boundary matched — the fall-through re-render must carry 500 to match
+      // the JS path's boundaryless-error status (server-action.ts).
+      boundarylessErrorStatus = 500;
     }
   } else if (isDirectAction && directActionId) {
     const temporaryReferences = ctx.createTemporaryReferenceSet();
 
+    // INTENTIONAL JS/PE divergence (do NOT "fix" to match the JS reject path).
+    // On the JS path React Flight-encodes the action args, so decodeReply
+    // succeeds or a failure means a malformed body (rejected). On the no-JS PE
+    // path the browser submits a raw <form action={fn}> POST with NO encoded
+    // args, so decodeReply throws by design and the raw FormData IS the action
+    // argument (the React form-action convention: fn(formData)). Removing this
+    // fallback breaks every unbound no-JS form action (verified: it fails the
+    // progressive-enhancement dev+prod e2e suite). See #572 (decided: keep).
     let args: unknown[] = [];
     try {
       args = await ctx.decodeReply(formData, { temporaryReferences });
@@ -164,7 +190,9 @@ export async function handleProgressiveEnhancement<TEnv>(
 
     try {
       const loadedAction = await ctx.loadServerAction(directActionId);
-      actionResult = await loadedAction.apply(null, args);
+      actionResult = await observePhase(PHASES.action(directActionId), () =>
+        loadedAction.apply(null, args),
+      );
     } catch (error) {
       // Handle thrown redirect (e.g., throw redirect('/path'))
       const redirectResponse = extractRedirectResponse(error);
@@ -180,6 +208,7 @@ export async function handleProgressiveEnhancement<TEnv>(
         handleStore,
         nonce,
         directActionId,
+        true, // an action ran and threw
       );
       if (errorHtml) return errorHtml;
 
@@ -191,6 +220,9 @@ export async function handleProgressiveEnhancement<TEnv>(
         handledByBoundary: false,
       });
       console.error("[RSC] Progressive enhancement action error:", error);
+      // No boundary matched — the fall-through re-render must carry 500 to match
+      // the JS path's boundaryless-error status (server-action.ts).
+      boundarylessErrorStatus = 500;
     }
   }
 
@@ -226,11 +258,29 @@ export async function handleProgressiveEnhancement<TEnv>(
   // cookies set by route middleware are available during re-render — matching
   // the behavior of JS-enabled requests.
   const renderPage = async (): Promise<Response> => {
+    // Preserve the original POST request's headers (Authorization, Cookie,
+    // custom headers) so loaders that read request headers/cookies behave
+    // identically under PE and the JS action path. Drop body-framing headers
+    // from the bodyless GET and force the HTML accept.
+    const headers = new Headers(request.headers);
+    headers.delete("content-type");
+    headers.delete("content-length");
+    headers.delete("content-encoding");
+    headers.delete("transfer-encoding");
+    headers.set("accept", "text/html");
     const renderRequest = new Request(url.toString(), {
       method: "GET",
-      headers: new Headers({ accept: "text/html" }),
+      headers,
     });
 
+    // JS/PE parity: this is an action's revalidation render, so mark it BEFORE
+    // matching — a stale `foregroundOnAction` cache entry must re-execute in the
+    // foreground during the re-render, exactly as the JS path's
+    // revalidateAfterAction does. The transition({ when }) gate fields below are
+    // set post-match (the gate reads them after rendering); foregroundOnAction
+    // reads _inActionRevalidation during the match, so it must be set here.
+    getRequestContext()._inActionRevalidation = true;
+
     const match = await ctx.router.match(renderRequest, { env });
 
     if (match.redirect) {
@@ -240,25 +290,41 @@ export async function handleProgressiveEnhancement<TEnv>(
       });
     }
 
+    // Expose the no-JS action to the transition({ when }) gate. currentUrl/Params
+    // are absent on this full-render path (no navigation snapshot); useActionState
+    // ids are block-scoped, so only a direct action id is available here.
+    // actionUrl is the page the action was submitted from (this request's url).
+    const peReqCtx = getRequestContext();
+    peReqCtx._gateActionId = directActionId ?? undefined;
+    peReqCtx._gateActionUrl = new URL(url);
+    peReqCtx._gateActionResult = actionResult;
+    peReqCtx._gateFormData = formData;
+
     const payload: RscPayload = {
       metadata: {
         pathname: url.pathname,
         routerId: ctx.router.id,
         basename: ctx.router.basename,
-        segments: match.segments,
+        segments: gateTransitions(
+          match.segments,
+          getRequestContext(),
+          ctx.router.onError,
+        ),
         matched: match.matched,
         diff: match.diff,
         resolvedIds: match.resolvedIds,
         params: match.params,
         isPartial: false,
         rootLayout: ctx.router.rootLayout,
-        handles: handleStore.stream(),
+        // PE full render: resolve deferred handle values server-side.
+        handles: resolvedHandleStream(handleStore),
         version: ctx.version,
+        stateCookieName: ctx.router.resolvedStateCookieName,
         themeConfig: ctx.router.themeConfig,
         warmupEnabled: ctx.router.warmupEnabled,
-        initialTheme: requireRequestContext().theme,
+        strictMode: ctx.router.strictMode,
+        initialTheme: getRequestContext().theme,
       },
-      formState: actionResult,
     };
 
     const rscStream = ctx.renderToReadableStream<RscPayload>(payload, {
@@ -276,6 +342,8 @@ export async function handleProgressiveEnhancement<TEnv>(
       url,
       undefined,
     );
+    // reactFormState carries the useActionState payload via the SSR-option path
+    // (renderToReadableStream({ formState })); it does NOT travel on RscPayload.
     const htmlStream = await ssrModule.renderHTML(rscStream, {
       formState: reactFormState,
       nonce,
@@ -283,6 +351,13 @@ export async function handleProgressiveEnhancement<TEnv>(
     });
 
     return createResponseWithMergedHeaders(htmlStream, {
+      // boundarylessErrorStatus is set only when the action threw and no error
+      // boundary matched; it makes the re-render carry 500 like the JS path.
+      // The redirect branch above returns before this, so a redirect re-render
+      // keeps its 308 and is never overridden.
+      ...(boundarylessErrorStatus !== undefined
+        ? { status: boundarylessErrorStatus }
+        : {}),
       headers: { "content-type": "text/html;charset=utf-8" },
     });
   };
@@ -317,10 +392,25 @@ async function renderPeErrorBoundary<TEnv>(
   env: TEnv,
   url: URL,
   error: unknown,
-  handleStore: ReturnType<typeof requireRequestContext>["_handleStore"],
+  handleStore: ReturnType<typeof getRequestContext>["_handleStore"],
   nonce: string | undefined,
   actionId?: string | null,
+  // True when an action actually ran and threw (vs a malformed form body, where
+  // no action executed). Drives _inActionRevalidation for JS/PE parity — it must
+  // NOT be inferred from actionId, since a useActionState bound action can run
+  // and throw with no $$id (actionId === undefined) yet still be an action error.
+  actionRan = false,
 ): Promise<Response | null> {
+  // JS/PE parity for an action-triggered error re-render: a stale
+  // `foregroundOnAction` cache entry inside the error boundary must foreground
+  // too, exactly as the JS path (revalidateAfterAction sets this unconditionally
+  // before rendering the error boundary). Set BEFORE matchError (the cached fn
+  // runs during it). Gated on actionRan, NOT actionId — a malformed form body
+  // (actionRan=false) ran no action and must keep SWR.
+  if (actionRan) {
+    getRequestContext()._inActionRevalidation = true;
+  }
+
   let errorResult;
   try {
     errorResult = await ctx.router.matchError(request, { env }, error, "route");
@@ -347,12 +437,26 @@ async function renderPeErrorBoundary<TEnv>(
 
   setRequestContextParams(errorResult.params, errorResult.routeName);
 
+  // Only the failing action id + URL are in scope here (no formData/actionResult
+  // thread into this helper). Expose the URL only when the action id is known:
+  // this helper also handles malformed form bodies before action detection, and
+  // those should not look like action-triggered renders to transition({ when }).
+  if (actionId != null) {
+    const peErrCtx = getRequestContext();
+    peErrCtx._gateActionId = actionId;
+    peErrCtx._gateActionUrl = new URL(url);
+  }
+
   const payload: RscPayload = {
     metadata: {
       pathname: url.pathname,
       routerId: ctx.router.id,
       basename: ctx.router.basename,
-      segments: errorResult.segments,
+      segments: gateTransitions(
+        errorResult.segments,
+        getRequestContext(),
+        ctx.router.onError,
+      ),
       matched: errorResult.matched,
       diff: errorResult.diff,
       resolvedIds: errorResult.resolvedIds,
@@ -360,11 +464,14 @@ async function renderPeErrorBoundary<TEnv>(
       isPartial: false,
       isError: true,
       rootLayout: ctx.router.rootLayout,
-      handles: handleStore.stream(),
+      // PE error-boundary full render: resolve deferred handle values server-side.
+      handles: resolvedHandleStream(handleStore),
       version: ctx.version,
+      stateCookieName: ctx.router.resolvedStateCookieName,
       themeConfig: ctx.router.themeConfig,
       warmupEnabled: ctx.router.warmupEnabled,
-      initialTheme: requireRequestContext().theme,
+      strictMode: ctx.router.strictMode,
+      initialTheme: getRequestContext().theme,
     },
   };
 

package/src/rsc/redirect-guard.ts

@@ -0,0 +1,100 @@
+/**
+ * Server-side open-redirect guard.
+ *
+ * Applied to the FINAL handler response (the single top-level return in
+ * `handler.ts`) so every browser-followed redirect honors the same same-origin
+ * rule the client enforces (`browser/validate-redirect-origin.ts`), via the one
+ * shared resolver in `redirect-origin.ts`. This is the server half of the
+ * client's existing guard: the client can only validate redirects its own JS
+ * navigates to (the SPA/fetch channel), so document-native redirects -- a no-JS
+ * PE form POST, a full-page GET `match.redirect`, a middleware `redirect()`
+ * short-circuit, a response-route 3xx -- reach the browser with no client in the
+ * loop. They all funnel through one handler return, so guarding there covers
+ * every one and any future redirect exit.
+ *
+ * Soft (SPA/Flight) redirects are 200/204 responses (`X-RSC-Redirect` header or
+ * `metadata.redirect` payload) and are NOT redirect Responses, so they never
+ * reach this guard -- they stay validated client-side.
+ *
+ * Behavior on a `Location` header:
+ * - same-origin / relative  -> passes through unchanged
+ * - `redirect(url, { external: true })` (out-of-band brand present) and an
+ *   http(s) target -> allowed (explicit, auditable, unforgeable opt-in)
+ * - branded but a non-http(s) target (e.g. `javascript:`) -> neutralized: the
+ *   opt-in waives the same-origin rule, NOT scheme safety
+ * - cross-origin without the brand -> Location rewritten to the basename root
+ *   (a safe same-origin landing, the document analog of the client's "stay put");
+ *   dev logs the blocked target and points to `{ external: true }`.
+ *
+ * The opt-in is an out-of-band brand on the Response object (isExternalRedirect),
+ * never a wire header: a header is forgeable by an attacker-controlled upstream
+ * response a proxy-style response route copies through, which would defeat the
+ * guard without app code ever opting in. The reserved header name is stripped
+ * defensively so a forged value can never reach the browser.
+ */
+
+import { isRedirectResponse } from "../response-utils.js";
+import {
+  resolveSameOriginRedirect,
+  resolveExternalRedirect,
+  isExternalRedirect,
+  safeSameOriginLanding,
+  EXTERNAL_REDIRECT_MARKER,
+} from "../redirect-origin.js";
+import { carryOverRedirectHeaders } from "./helpers.js";
+
+export function guardOutgoingRedirect(
+  response: Response,
+  requestOrigin: string,
+  basename: string | undefined,
+): Response {
+  // Only 3xx + Location responses (document-native redirects) are guarded.
+  if (!isRedirectResponse(response)) {
+    return response;
+  }
+
+  // The reserved marker is never a trust signal. Strip any value -- forged by a
+  // proxied upstream or otherwise -- so it can never reach the browser. Trust
+  // comes solely from the out-of-band brand below.
+  try {
+    response.headers.delete(EXTERNAL_REDIRECT_MARKER);
+  } catch {
+    // Some platform responses carry immutable headers; the header is inert on
+    // the browser, so a failed strip is harmless.
+  }
+
+  // isRedirectResponse guarantees a truthy Location.
+  const location = response.headers.get("Location")!;
+
+  // Explicit opt-in via redirect(url, { external: true }): allow an off-host
+  // target, but only an http(s) one. external waives the same-origin rule, not
+  // scheme safety -- a branded javascript:/data: target falls through to be
+  // neutralized so it can never become a scriptable navigation downstream.
+  if (isExternalRedirect(response)) {
+    if (resolveExternalRedirect(location, requestOrigin) !== null) {
+      return response;
+    }
+  } else if (resolveSameOriginRedirect(location, requestOrigin) !== null) {
+    return response;
+  }
+
+  // Cross-origin (or unsafe-scheme external): neutralize to a safe same-origin
+  // landing.
+  const safeTarget = safeSameOriginLanding(basename);
+  if (process.env.NODE_ENV !== "production") {
+    console.error(
+      `[rango] Blocked cross-origin redirect to "${location}"; sent to ` +
+        `"${safeTarget}" instead. To redirect off-host on purpose, use ` +
+        `redirect(url, { external: true }).`,
+    );
+  }
+
+  const blocked = new Response(null, {
+    status: response.status,
+    headers: { Location: safeTarget },
+  });
+  // Preserve cookies and any other headers (Set-Cookie, Server-Timing, ...);
+  // carryOverRedirectHeaders intentionally skips Location.
+  carryOverRedirectHeaders(response, blocked);
+  return blocked;
+}

package/src/rsc/response-cache-serve.ts

@@ -0,0 +1,238 @@
+/**
+ * Shared response-route cache serve.
+ *
+ * Owns the single response-cache contract — cache-scope resolution from the
+ * matched entry tree, condition eval, key resolution (route key() > store
+ * keyGenerator > default), tag resolution, pre-handler-callback timing, and the
+ * fresh-hit / SWR-revalidate / miss-write branches — for BOTH the production
+ * response-route handler (rsc/response-route-handler.ts) and the dispatch testing
+ * primitive (testing/dispatch.ts), so the two can never drift.
+ *
+ * Plugin-rsc hazard: cache-scope.ts pulls @vitejs/plugin-rsc (via segment-codec),
+ * which the non-Vite unit-test runner cannot resolve, and this module is on the
+ * testing barrel's EAGER graph (dispatch imports it). So `createCacheScope` and
+ * `resolveCacheTags` are NOT imported here at runtime — they are INJECTED by the
+ * caller (production imports them statically; dispatch lazy-imports them only once
+ * a response route matches). The only runtime imports here are plugin-rsc-free
+ * (helpers' isCacheableStatus/finalizeResponse, traverseBack); cache-scope is a
+ * type-only import (erased at build).
+ */
+
+import type { CacheScope } from "../cache/cache-scope.js";
+import type { PartialCacheOptions } from "../types.js";
+import type { RequestContext } from "../server/request-context.js";
+import type { SegmentCacheStore } from "../cache/types.js";
+import type { EntryCacheConfig, EntryData } from "../server/context.js";
+import { traverseBack } from "../router/pattern-matching.js";
+import { isCacheableStatus, finalizeResponse } from "./helpers.js";
+import { reportCacheError } from "../cache/cache-error.js";
+
+/** Injected cache-scope builders (kept off this module's runtime import graph). */
+export interface CacheScopeDeps {
+  createCacheScope: (
+    config: EntryCacheConfig | undefined,
+    parent?: CacheScope | null,
+  ) => CacheScope | null;
+  resolveCacheTags: (
+    config: PartialCacheOptions | false,
+    ctx: RequestContext | undefined,
+  ) => string[] | undefined;
+}
+
+export interface ServeResponseRouteWithCacheArgs {
+  reqCtx: RequestContext;
+  manifestEntry: EntryData;
+  responseType: string;
+  url: URL;
+  /** callHandler wrapped by route-level middleware — the unit the cache wraps. */
+  executeHandler: () => Promise<Response>;
+  deps: CacheScopeDeps;
+}
+
+/**
+ * Serve a response route through its cache, or return `undefined` when no cache
+ * applies (no scope, disabled, condition false, or store lacks get/putResponse)
+ * so the caller falls through to a plain `executeHandler()` run.
+ *
+ * Must run inside runWithRequestContext (reads the ambient request context via
+ * the helpers and reqCtx.waitUntil for background writes).
+ */
+export async function serveResponseRouteWithCache(
+  args: ServeResponseRouteWithCacheArgs,
+): Promise<Response | undefined> {
+  const { reqCtx, manifestEntry, responseType, url, executeHandler, deps } =
+    args;
+
+  let cacheScope: CacheScope | null = null;
+  for (const entry of traverseBack(manifestEntry)) {
+    if (entry.cache) {
+      cacheScope = deps.createCacheScope(entry.cache, cacheScope);
+    }
+  }
+
+  if (!cacheScope?.enabled) return undefined;
+
+  // Evaluate condition — skip the response cache when condition returns false.
+  let conditionPassed = true;
+  if (cacheScope.config !== false && cacheScope.config.condition) {
+    try {
+      conditionPassed = !!cacheScope.config.condition(reqCtx);
+    } catch {
+      conditionPassed = false;
+    }
+  }
+
+  const store = cacheScope.getStore() ?? reqCtx._cacheStore;
+  if (!conditionPassed || !store?.getResponse || !store?.putResponse) {
+    return undefined;
+  }
+
+  // Build cache key with the response:{type}: prefix (avoids collision with
+  // segment keys); include host + url.search so query-driven and multi-host
+  // responses cache separately.
+  let cacheKey = `response:${responseType}:${url.host}${url.pathname}${url.search}`;
+
+  // Priority 1: route-level key() (full override). Priority 2: store-level
+  // keyGenerator (modifies the default key).
+  //
+  // A CONFIGURED key()/keyGenerator that THROWS must DEGRADE TO A MISS, not fall
+  // back to the broad default key. The default key
+  // `response:${type}:${host}${path}${search}` is intentionally broad; if the
+  // configured key encodes tenant/user/auth state, falling back to the broad key
+  // would cache PERSONALIZED output under it and serve it cross-user (cache
+  // poisoning). Mirrors the segment-cache behavior (cache-scope.ts lookupRoute):
+  // a throwing key degrades to a cache miss, never a collision onto the default
+  // slot. The no-key default path is left untouched (the broad key is correct
+  // when no key is configured).
+  let keyResolutionFailed = false;
+  if (cacheScope.config !== false && cacheScope.config.key) {
+    try {
+      const customKey = await cacheScope.config.key(reqCtx);
+      cacheKey = `response:${customKey}`;
+    } catch (error) {
+      keyResolutionFailed = true;
+      reportCacheError(
+        error,
+        "cache-read",
+        "[ResponseCache] Key resolution failed",
+        reqCtx,
+      );
+    }
+  } else if (store.keyGenerator) {
+    try {
+      cacheKey = await store.keyGenerator(reqCtx, cacheKey);
+    } catch (error) {
+      keyResolutionFailed = true;
+      reportCacheError(
+        error,
+        "cache-read",
+        "[ResponseCache] keyGenerator failed",
+        reqCtx,
+      );
+    }
+  }
+
+  // Degrade to a MISS: return undefined so the caller runs the route UNCACHED.
+  // This early-returns BEFORE _onResponseCallbacks is saved/cleared below, so the
+  // pre-handler onResponse callbacks are still intact for the uncached run.
+  if (keyResolutionFailed) {
+    return undefined;
+  }
+
+  // Resolve cache tags for this document entry (static or dynamic) while the
+  // request context is available, so the stored entry is tag-invalidatable.
+  const responseTags = deps.resolveCacheTags(cacheScope.config, reqCtx);
+
+  // Pre-handler callbacks (registered by app-level middleware before the cache
+  // block) are saved and the live array is cleared:
+  // createResponseWithMergedHeaders inside the handler eagerly drains whatever is
+  // in _onResponseCallbacks, so handler-registered callbacks bake into the cached
+  // artifact, while these pre-handler callbacks are applied once per serve on
+  // every path (hit + miss).
+  const savedCallbacks = reqCtx._onResponseCallbacks;
+  reqCtx._onResponseCallbacks = [];
+  const applyPreHandlerCallbacks = (response: Response): Response => {
+    let result = response;
+    for (const callback of savedCallbacks) {
+      result = callback(result) ?? result;
+    }
+    return result;
+  };
+
+  const putFresh = (
+    store2: SegmentCacheStore,
+    fresh: Response,
+  ): Promise<void> =>
+    store2.putResponse!(
+      cacheKey,
+      fresh.clone(),
+      cacheScope!.ttl,
+      cacheScope!.swr,
+      responseTags,
+    );
+
+  try {
+    const cached = await store.getResponse(cacheKey);
+    if (cached && isCacheableStatus(cached.response.status)) {
+      if (!cached.shouldRevalidate) {
+        return applyPreHandlerCallbacks(cached.response);
+      }
+      // Stale hit (SWR): return cached, revalidate in background.
+      reqCtx.waitUntil(async () => {
+        try {
+          const fresh = finalizeResponse(await executeHandler());
+          if (isCacheableStatus(fresh.status)) await putFresh(store, fresh);
+        } catch (error) {
+          reportCacheError(
+            error,
+            "stale-revalidation",
+            "[ResponseCache] background revalidation",
+            reqCtx,
+          );
+        }
+      });
+      return applyPreHandlerCallbacks(cached.response);
+    }
+  } catch (error) {
+    reportCacheError(
+      error,
+      "cache-read",
+      "[ResponseCache] Cache lookup failed",
+      reqCtx,
+    );
+  }
+
+  // Cache miss: execute the handler and cache the result.
+  const response = finalizeResponse(await executeHandler());
+  if (isCacheableStatus(response.status)) {
+    // Clone SYNCHRONOUSLY here, before returning. The original `response` is
+    // handed back to the middleware chain, where mergeResponse rebuilds it as
+    // `new Response(response.body, ...)`. Deferring the clone into the waitUntil
+    // callback (putFresh(response), which clones inside the async body) raced
+    // that rebuild: the background clone() and the foreground body read could
+    // interleave and throw "Response body object should not be disturbed or
+    // locked" (a flaky 500). Teeing now keeps the returned body independent of
+    // the cache write. The SWR path above is unaffected (its `fresh` is created
+    // inside the background callback and never returned to the caller).
+    const toCache = response.clone();
+    reqCtx.waitUntil(async () => {
+      try {
+        await store.putResponse!(
+          cacheKey,
+          toCache,
+          cacheScope!.ttl,
+          cacheScope!.swr,
+          responseTags,
+        );
+      } catch (error) {
+        reportCacheError(
+          error,
+          "cache-write",
+          "[ResponseCache] Cache write failed",
+          reqCtx,
+        );
+      }
+    });
+  }
+  return applyPreHandlerCallbacks(response);
+}