@rangojs/router 0.0.0-experimental.eb0645d3 → 0.0.0-experimental.f1468e3c

package/src/rsc/server-action.ts

@@ -16,37 +16,36 @@
  */
 
 import {
-  requireRequestContext,
+  getRequestContext,
   setRequestContextParams,
-  getLocationState,
 } from "../server/request-context.js";
-import { resolveLocationStateEntries } from "../browser/react/location-state-shared.js";
 import { appendMetric } from "../router/metrics.js";
+import { observePhase, PHASES } from "../router/instrument.js";
+import { gateTransitions } from "./transition-gate.js";
 import type { RscPayload } from "./types.js";
 import {
   hasBodyContent,
   createResponseWithMergedHeaders,
   createSimpleRedirectResponse,
-  carryOverRedirectHeaders,
+  interceptRedirectForPartial,
+  attachLocationStateIfPresent,
 } from "./helpers.js";
+import { warnNonRedirectActionResponse } from "./runtime-warnings.js";
 import type { HandlerContext } from "./handler-context.js";
-
-/**
- * Attach location state set during the action to a payload's metadata.
- * No-op if no location state was set.
- */
-function attachLocationState(payload: RscPayload): void {
-  const locationState = getLocationState();
-  if (locationState) {
-    payload.metadata!.locationState =
-      resolveLocationStateEntries(locationState);
-  }
-}
+import type { MatchResult } from "../types.js";
 
 /**
  * Data flowing from action execution to the revalidation phase.
- * When the action completes without redirect/error-boundary, the handler
- * passes this to route middleware → revalidateAfterAction.
+ * When the action completes without redirect, the handler passes this to route
+ * middleware → revalidateAfterAction.
+ *
+ * `errorBoundary` carries the matched error-boundary result when the action
+ * threw and a boundary matched. The error-boundary render is then performed in
+ * the revalidation phase so it runs INSIDE the same route-middleware wrapper as
+ * a successful revalidation — route middleware (context vars, headers, cookies)
+ * must apply to the error render too, matching the module doc's "identical to a
+ * normal render". When `errorBoundary` is set, `actionContext` is unused (the
+ * boundary is already matched; no matchPartial is run).
  */
 export interface ActionContinuation {
   returnValue: { ok: boolean; data: unknown };
@@ -60,6 +59,7 @@ export interface ActionContinuation {
     actionResult: unknown;
     formData?: FormData;
   };
+  errorBoundary?: MatchResult;
 }
 
 /**
@@ -75,7 +75,7 @@ export async function executeServerAction<TEnv>(
   env: TEnv,
   url: URL,
   actionId: string,
-  handleStore: ReturnType<typeof requireRequestContext>["_handleStore"],
+  handleStore: ReturnType<typeof getRequestContext>["_handleStore"],
 ): Promise<Response | ActionContinuation> {
   const temporaryReferences = ctx.createTemporaryReferenceSet();
 
@@ -89,17 +89,82 @@ export async function executeServerAction<TEnv>(
       ? await request.formData()
       : await request.text();
 
-    if (body instanceof FormData) {
-      actionFormData = body;
-    }
-
     if (hasBodyContent(body)) {
       args = await ctx.decodeReply(body, { temporaryReferences });
     }
+
+    // Surface the action's FormData to shouldRevalidate({ formData }) for a JS
+    // server action, matching the PE path (progressive-enhancement.ts populates
+    // formData from request.formData()). A form-driven action is invoked as
+    // action(formData) (direct) or action(prevState, formData) (useActionState),
+    // so the FormData arrives INSIDE the decoded args. Use the LAST FormData arg:
+    // for useActionState the submitted form is the final arg, and a prior state
+    // that is itself a FormData would otherwise be picked first.
+    //
+    // The raw request body is NOT usable here: encodeReply wraps a FormData arg
+    // in a multipart envelope whose keys are Flight-encoded (e.g. `_1_name`,
+    // `0`), so request.formData() would hand shouldRevalidate a FormData with
+    // internal keys instead of the consumer's `name`. The decoded arg has the
+    // original keys.
+    for (let i = args.length - 1; i >= 0; i--) {
+      if (args[i] instanceof FormData) {
+        actionFormData = args[i] as FormData;
+        break;
+      }
+    }
   } catch (error) {
-    throw new Error(`Failed to decode action arguments: ${error}`, {
+    // Keep the original error as `cause` for server-side logging, but do not
+    // interpolate it into the message: that string can surface to the client
+    // and may leak decode internals.
+    const decodeError = new Error("Failed to decode action arguments", {
       cause: error,
     });
+
+    // Produce a router-controlled response instead of re-throwing into the
+    // host (which would surface as an opaque 500). This mirrors the no-JS PE
+    // path, where a malformed form body renders the route error boundary or
+    // returns an explicit 400 (progressive-enhancement.ts). Attempt boundary
+    // rendering first; if a boundary matches, defer the render to the
+    // revalidation phase (errorBoundary continuation) so it runs inside route
+    // middleware, identical to the action-threw path below. Otherwise return a
+    // plain 400 — the JS and no-JS paths now converge on the same outcome.
+    let decodeBoundary: MatchResult | undefined;
+    try {
+      decodeBoundary =
+        (await ctx.router.matchError(request, { env }, decodeError, "route")) ??
+        undefined;
+    } catch {
+      // matchError itself failed — fall through to the plain 400 below.
+      decodeBoundary = undefined;
+    }
+
+    ctx.callOnError(decodeError, "action", {
+      request,
+      url,
+      env,
+      actionId,
+      handledByBoundary: !!decodeBoundary,
+    });
+
+    if (decodeBoundary) {
+      return {
+        returnValue: { ok: false, data: decodeError },
+        // 400: malformed action request, matching the PE explicit-400 status
+        // class (the action-threw path uses 500; a decode failure is a bad
+        // request, not an action runtime error).
+        actionStatus: 400,
+        temporaryReferences,
+        actionContext: {
+          actionId,
+          actionUrl: new URL(url),
+          actionResult: decodeError,
+          formData: actionFormData,
+        },
+        errorBoundary: decodeBoundary,
+      };
+    }
+
+    return createResponseWithMergedHeaders(null, { status: 400 });
   }
 
   // Execute the server action
@@ -109,51 +174,37 @@ export async function executeServerAction<TEnv>(
 
   try {
     loadedAction = await ctx.loadServerAction(actionId);
-    const data = await loadedAction!.apply(null, args);
+    let data = await loadedAction!.apply(null, args);
 
-    // Intercept redirect responses from actions. Without this, the redirect
-    // Response would be serialized as the action returnValue (which fails)
-    // and the revalidation step would run unnecessarily.
+    // Intercept redirect Responses: serializing one as the action returnValue
+    // would fail, and revalidation would run needlessly.
     if (data instanceof Response) {
-      const redirectUrl = data.headers.get("Location");
-      const isRedirect = data.status >= 300 && data.status < 400 && redirectUrl;
-      if (isRedirect) {
-        const locationState = getLocationState();
-        let redirect: Response;
-        if (locationState) {
-          redirect = ctx.createRedirectFlightResponse(
-            redirectUrl,
-            resolveLocationStateEntries(locationState),
-          );
-        } else {
-          redirect = createSimpleRedirectResponse(redirectUrl);
-        }
-        carryOverRedirectHeaders(data, redirect);
-        return redirect;
+      const intercepted = interceptRedirectForPartial(
+        data,
+        ctx.createRedirectFlightResponse,
+      );
+      if (intercepted) return intercepted;
+
+      // Non-redirect Response returned (not thrown): a raw Response cannot be
+      // serialized into Flight. Discard it and re-render — mirroring the PE
+      // path (progressive-enhancement.ts) so JS and no-JS behave identically.
+      if (process.env.NODE_ENV !== "production") {
+        warnNonRedirectActionResponse(actionId);
       }
+      data = undefined;
     }
 
     returnValue = { ok: true, data };
   } catch (error) {
+    let actionResultData: unknown = error;
+
     // Handle thrown redirect (e.g., throw redirect('/path'))
     if (error instanceof Response) {
-      const redirectUrl = error.headers.get("Location");
-      const isRedirect =
-        error.status >= 300 && error.status < 400 && redirectUrl;
-      if (isRedirect) {
-        const locationState = getLocationState();
-        let redirect: Response;
-        if (locationState) {
-          redirect = ctx.createRedirectFlightResponse(
-            redirectUrl,
-            resolveLocationStateEntries(locationState),
-          );
-        } else {
-          redirect = createSimpleRedirectResponse(redirectUrl);
-        }
-        carryOverRedirectHeaders(error, redirect);
-        return redirect;
-      }
+      const intercepted = interceptRedirectForPartial(
+        error,
+        ctx.createRedirectFlightResponse,
+      );
+      if (intercepted) return intercepted;
 
       // Non-redirect Response thrown from action — this will be treated
       // as a regular error and routed to the error boundary. Warn in dev
@@ -166,9 +217,18 @@ export async function executeServerAction<TEnv>(
             `Use \`throw redirect('/path')\` for redirects.`,
         );
       }
+
+      // A raw Response cannot be serialized into Flight; storing it as the
+      // action returnValue.data would make the error payload serialization
+      // throw and mask the boundary render. Replace it with a serializable
+      // error (mirrors the discard of a returned non-redirect Response above).
+      // matchError/onError still receive the original Response.
+      actionResultData = new Error(
+        `Server action "${actionId}" threw a non-redirect Response (status ${error.status})`,
+      );
     }
 
-    returnValue = { ok: false, data: error };
+    returnValue = { ok: false, data: actionResultData };
     actionStatus = 500;
 
     // Try to render error boundary.
@@ -203,55 +263,46 @@ export async function executeServerAction<TEnv>(
     });
 
     if (errorResult) {
-      setRequestContextParams(errorResult.params, errorResult.routeName);
-
-      const payload: RscPayload = {
-        metadata: {
-          pathname: url.pathname,
-          routerId: ctx.router.id,
-          segments: errorResult.segments,
-          isPartial: true,
-          matched: errorResult.matched,
-          diff: errorResult.diff,
-          params: errorResult.params,
-          isError: true,
-          handles: handleStore.stream(),
-          version: ctx.version,
-        },
+      // Defer the error-boundary render to the revalidation phase so it runs
+      // inside the same route-middleware wrapper as a successful revalidation
+      // (handler.ts executeRenderWithMiddleware). Building + returning the
+      // Response here would bypass route middleware: context vars, headers, and
+      // cookies set by route middleware would NOT apply to the error render,
+      // diverging from the success path and from the module doc's "identical to
+      // a normal render". The boundary is already matched; the render in
+      // revalidateAfterAction uses errorResult directly (no matchPartial).
+      return {
         returnValue,
-      };
-
-      // Intentionally omit attachLocationState for error payloads:
-      // location state is a success-only semantic. Error boundary responses
-      // update the error UI but should not mutate browser history state.
-
-      const rscStream = ctx.renderToReadableStream<RscPayload>(payload, {
+        actionStatus,
         temporaryReferences,
-        onError: (error: unknown) => {
-          ctx.callOnError(error, "rendering", { request, url, env });
+        // actionContext is unused on the errorBoundary path (no matchPartial).
+        actionContext: {
+          actionId,
+          actionUrl: new URL(url),
+          actionResult: returnValue.data,
+          formData: actionFormData,
         },
-      });
-
-      return createResponseWithMergedHeaders(rscStream, {
-        status: actionStatus,
-        headers: { "content-type": "text/x-component;charset=utf-8" },
-      });
+        errorBoundary: errorResult,
+      };
     }
   }
 
   // Build continuation for the revalidation phase
-  const resolvedActionId =
-    (loadedAction as { $id?: string; $$id?: string } | undefined)?.$id ??
-    (loadedAction as { $$id?: string } | undefined)?.$$id ??
-    actionId;
+  const actionMeta = loadedAction as
+    | { $id?: string; $$id?: string }
+    | undefined;
+  const resolvedActionId = actionMeta?.$id ?? actionMeta?.$$id ?? actionId;
 
   return {
     returnValue,
     actionStatus,
     temporaryReferences,
     actionContext: {
+      // Defensive copy of the already-parsed url (avoids re-parsing
+      // request.url). actionUrl is persisted into the continuation and later
+      // flows into matchPartial, so it must not alias the handler's live url.
       actionId: resolvedActionId,
-      actionUrl: new URL(request.url),
+      actionUrl: new URL(url),
       actionResult: returnValue.data,
       formData: actionFormData,
     },
@@ -270,19 +321,122 @@ export async function executeServerAction<TEnv>(
  * provide. Redirects are the only non-partial outcome and are handled via
  * X-RSC-Redirect headers before Flight deserialization.
  */
-export async function revalidateAfterAction<TEnv>(
+export function revalidateAfterAction<TEnv>(
   ctx: HandlerContext<TEnv>,
   request: Request,
   env: TEnv,
   url: URL,
-  handleStore: ReturnType<typeof requireRequestContext>["_handleStore"],
+  handleStore: ReturnType<typeof getRequestContext>["_handleStore"],
   continuation: ActionContinuation,
 ): Promise<Response> {
-  const { returnValue, actionStatus, temporaryReferences, actionContext } =
-    continuation;
-  const reqCtx = requireRequestContext();
+  // Instrument the action-revalidation render through the unified phase API,
+  // exactly like a normal navigation render (handleRscRendering). It records
+  // "render:total" AND opens "rango.render" from one boundary covering
+  // matchPartial -> serialize, so the revalidation loaders' rango.loader spans
+  // nest under a rango.render parent instead of dangling at the request root.
+  return observePhase(PHASES.render, () =>
+    revalidateAfterActionInner(
+      ctx,
+      request,
+      env,
+      url,
+      handleStore,
+      continuation,
+    ),
+  );
+}
+
+async function revalidateAfterActionInner<TEnv>(
+  ctx: HandlerContext<TEnv>,
+  request: Request,
+  env: TEnv,
+  url: URL,
+  handleStore: ReturnType<typeof getRequestContext>["_handleStore"],
+  continuation: ActionContinuation,
+): Promise<Response> {
+  const {
+    returnValue,
+    actionStatus,
+    temporaryReferences,
+    actionContext,
+    errorBoundary,
+  } = continuation;
+  const reqCtx = getRequestContext();
   const metricsStore = reqCtx._metricsStore;
 
+  // Expose the action that triggered this revalidation to the transition({ when })
+  // gate (covers both the error-boundary and success gate calls below). Mirrors
+  // the action fields a revalidate() predicate sees.
+  reqCtx._gateActionId = actionContext?.actionId;
+  reqCtx._gateActionUrl = actionContext?.actionUrl;
+  reqCtx._gateActionResult = actionContext?.actionResult;
+  reqCtx._gateFormData = actionContext?.formData;
+
+  // Mark the rest of this request as an action revalidation render. The "use
+  // cache" runtime reads this to re-execute a stale entry in the foreground
+  // (fresh data in the action response) rather than serving stale + revalidating
+  // in the background. See registerCachedFunction in cache/cache-runtime.ts.
+  reqCtx._inActionRevalidation = true;
+
+  // Action threw and a boundary matched: render the (already-matched) error
+  // boundary here so it runs inside the route-middleware wrapper, exactly like
+  // the success branch below. setRequestContextParams + the payload mirror the
+  // pre-deferral render that executeServerAction used to do inline.
+  if (errorBoundary) {
+    setRequestContextParams(errorBoundary.params, errorBoundary.routeName);
+
+    const errorPayload: RscPayload = {
+      metadata: {
+        pathname: url.pathname,
+        // routerId exposed for the frontend (current app identity); see
+        // rsc-rendering.ts partial branch.
+        routerId: ctx.router.id,
+        segments: gateTransitions(
+          errorBoundary.segments,
+          reqCtx,
+          ctx.router.onError,
+        ),
+        isPartial: true,
+        matched: errorBoundary.matched,
+        diff: errorBoundary.diff,
+        resolvedIds: errorBoundary.resolvedIds,
+        params: errorBoundary.params,
+        isError: true,
+        handles: handleStore.stream(),
+        version: ctx.version,
+      },
+      returnValue,
+    };
+
+    // Intentionally omit attachLocationState for error payloads: location state
+    // is a success-only semantic. Error boundary responses update the error UI
+    // but should not mutate browser history state.
+
+    const errorStart = performance.now();
+    const errorStream = ctx.renderToReadableStream<RscPayload>(errorPayload, {
+      temporaryReferences,
+      onError: (error: unknown) => {
+        ctx.callOnError(error, "rendering", { request, url, env });
+      },
+    });
+    appendMetric(
+      metricsStore,
+      "rsc-serialize",
+      errorStart,
+      performance.now() - errorStart,
+    );
+
+    return createResponseWithMergedHeaders(errorStream, {
+      status: actionStatus,
+      headers: {
+        "content-type": "text/x-component;charset=utf-8",
+        // Router identity for the client's pre-decode integrity check (the
+        // action apply path has no post-decode guard). See response-adapter.
+        "X-RSC-Router-Id": ctx.router.id,
+      },
+    });
+  }
+
   const matchResult = await ctx.router.matchPartial(
     request,
     { env },
@@ -290,8 +444,8 @@ export async function revalidateAfterAction<TEnv>(
   );
 
   if (!matchResult) {
-    // matchPartial returns null when the route is a redirect or the request
-    // is missing required headers (previousUrl). Check for redirect first.
+    // matchPartial returns null when the route is a redirect or no previous-URL
+    // context could be resolved. Check for redirect first.
     const fullMatch = await ctx.router.match(request, { env });
     setRequestContextParams(fullMatch.params, fullMatch.routeName);
 
@@ -302,14 +456,17 @@ export async function revalidateAfterAction<TEnv>(
       return createSimpleRedirectResponse(fullMatch.redirect);
     }
 
-    // Non-redirect: this branch is only reachable when the action request
-    // is missing the X-RSC-Router-Client-Path header (defensive). The
-    // client requires isPartial for action responses, so producing a full
-    // payload here would be rejected. Return 500 instead.
+    // Non-redirect: this branch is only reachable when no previous URL could
+    // be resolved (neither X-RSC-Router-Client-Path nor a usable Referer), or
+    // the previous URL was unparseable (defensive). The client requires
+    // isPartial for action responses, so producing a full payload here would
+    // be rejected. Return 500 instead.
     throw new Error(
       `[RSC] matchPartial returned null for a non-redirect route ` +
         `during action revalidation (${url.pathname}). This indicates ` +
-        `a malformed action request (missing X-RSC-Router-Client-Path header).`,
+        `a malformed action request: no previous-URL context could be ` +
+        `resolved (neither X-RSC-Router-Client-Path nor a usable Referer), ` +
+        `or the previous URL was unparseable.`,
     );
   }
 
@@ -319,11 +476,18 @@ export async function revalidateAfterAction<TEnv>(
   const payload: RscPayload = {
     metadata: {
       pathname: url.pathname,
+      // routerId exposed for the frontend (current app identity); see
+      // rsc-rendering.ts partial branch.
       routerId: ctx.router.id,
-      segments: matchResult.segments,
+      segments: gateTransitions(
+        matchResult.segments,
+        reqCtx,
+        ctx.router.onError,
+      ),
       isPartial: true,
       matched: matchResult.matched,
       diff: matchResult.diff,
+      resolvedIds: matchResult.resolvedIds,
       params: matchResult.params,
       slots: matchResult.slots,
       handles: handleStore.stream(),
@@ -332,7 +496,7 @@ export async function revalidateAfterAction<TEnv>(
     returnValue,
   };
 
-  attachLocationState(payload);
+  attachLocationStateIfPresent(payload);
 
   const renderStart = performance.now();
   const rscStream = ctx.renderToReadableStream<RscPayload>(payload, {
@@ -343,16 +507,16 @@ export async function revalidateAfterAction<TEnv>(
   });
   const rscSerializeDur = performance.now() - renderStart;
   // This measures synchronous stream creation, not end-to-end stream consumption.
+  // render:total is recorded by the observePhase wrapper in revalidateAfterAction.
   appendMetric(metricsStore, "rsc-serialize", renderStart, rscSerializeDur);
-  appendMetric(
-    metricsStore,
-    "render:total",
-    renderStart,
-    performance.now() - renderStart,
-  );
 
   return createResponseWithMergedHeaders(rscStream, {
     status: actionStatus,
-    headers: { "content-type": "text/x-component;charset=utf-8" },
+    headers: {
+      "content-type": "text/x-component;charset=utf-8",
+      // Router identity for the client's pre-decode integrity check (the action
+      // apply path has no post-decode guard). See response-adapter.
+      "X-RSC-Router-Id": ctx.router.id,
+    },
   });
 }

package/src/rsc/ssr-setup.ts

@@ -126,3 +126,19 @@ export function mayNeedSSR(request: Request, url: URL): boolean {
 
   return true;
 }
+
+// Final render-time decision: is the response an RSC stream (vs HTML)? Distinct
+// from mayNeedSSR, which is a conservative pre-classifier (it treats a missing
+// Accept header as needing SSR; this treats it as RSC).
+export function isRscRequest(
+  request: Request,
+  url: URL,
+  isPartial: boolean,
+): boolean {
+  return (
+    isPartial ||
+    (!request.headers.get("accept")?.includes("text/html") &&
+      !url.searchParams.has("__html")) ||
+    url.searchParams.has("__rsc")
+  );
+}

package/src/rsc/transition-gate.ts

@@ -0,0 +1,89 @@
+import type { MatchResult } from "../types.js";
+import type { TransitionWhenContext } from "../types/segments.js";
+import type { getRequestContext } from "../server/request-context.js";
+import { invokeOnError } from "../router/error-handling.js";
+import type { OnErrorCallback } from "../types/error-types.js";
+
+/**
+ * Apply transition({ when }) gates to a payload's segments.
+ *
+ * The predicates were collected during resolution (keyed by segment id) and
+ * stripped from the serialized config; here — after handlers ran and outside any
+ * cache scope — we evaluate each and drop the segment's transition when the
+ * predicate does not hold, so the navigation streams its loading fallback
+ * instead of holding the previous content. A predicate that throws is reported
+ * to the router's onError (phase "rendering") and then treated as "do not hold"
+ * (conservative), so a buggy predicate degrades to no transition rather than
+ * failing the response.
+ *
+ * Mutating the segments here is safe: the segment cache stores a serialized copy
+ * (segment-codec), written during match() BEFORE this gate runs, so dropping a
+ * transition never corrupts a cache entry. The flip side is that a cache hit
+ * skips resolution, collects no predicate, and replays the cached transition
+ * as-is (it was serialized before the gate) — combining transition({ when })
+ * with cache() on the same segment freezes the gate to its cached state, so
+ * avoid caching a route whose transition decision is request-dependent.
+ *
+ * Returns the same array (mutated) for inline use at the payload's `segments`
+ * field.
+ */
+export function gateTransitions(
+  segments: MatchResult["segments"],
+  ctx: ReturnType<typeof getRequestContext>,
+  onError?: OnErrorCallback,
+): MatchResult["segments"] {
+  const predicates = ctx._transitionWhen;
+  if (predicates && predicates.length) {
+    for (const { id, when } of predicates) {
+      let drop: boolean;
+      try {
+        // Assemble the ShouldRevalidateFn-shaped predicate context from the
+        // request context. Source fields (currentUrl/currentParams/fromRouteName)
+        // were stashed at match time from the navigation snapshot; action fields
+        // at the action-bearing gate call sites. nextUrl/nextParams/toRouteName/
+        // method/get/env come straight off ctx (setRequestContextParams ran
+        // before the gate). Source/action fields are undefined when absent —
+        // never fabricated (see TransitionWhenContext).
+        const whenCtx: TransitionWhenContext = {
+          currentUrl: ctx._gateCurrentUrl,
+          currentParams: ctx._gateCurrentParams,
+          fromRouteName:
+            ctx._prevRouteKey as TransitionWhenContext["fromRouteName"],
+          nextUrl: ctx.url,
+          nextParams: ctx.params,
+          toRouteName: ctx.routeName,
+          actionId: ctx._gateActionId,
+          actionUrl: ctx._gateActionUrl,
+          actionResult: ctx._gateActionResult,
+          formData: ctx._gateFormData,
+          method: ctx.request.method,
+          get: ctx.get,
+          env: ctx.env,
+        };
+        drop = when(whenCtx) === false;
+      } catch (error) {
+        // A throwing predicate must not fail the response: report it and treat
+        // the transition as gated off (do not hold). invokeOnError no-ops when
+        // onError is undefined.
+        drop = true;
+        invokeOnError(
+          onError,
+          error,
+          "rendering",
+          {
+            request: ctx.request,
+            url: ctx.url,
+            params: ctx.params,
+            segmentId: id,
+          },
+          "RSC",
+        );
+      }
+      if (drop) {
+        const seg = segments.find((s) => s.id === id);
+        if (seg) seg.transition = undefined;
+      }
+    }
+  }
+  return segments;
+}