@rangojs/router 0.24.3 → 0.25.0

package/src/rsc/progressive-enhancement.ts

@@ -6,7 +6,7 @@
  * reference. We detect these and return HTML instead of RSC stream.
  */
 
-import { requestHeaders } from "../server/request-headers.js";
+import { bodylessHeaders, requestHeaders } from "../server/request-headers.js";
 import {
   getRequestContext,
   setRequestContextParams,
@@ -16,10 +16,12 @@ import type { MiddlewareFn } from "../router/middleware.js";
 import { executeMiddleware } from "../router/middleware.js";
 import { observePhase, PHASES } from "../router/instrument.js";
 import { attachTransitionWhen } from "./attach-transition-when.js";
-import { payloadInitialTheme } from "./full-payload.js";
+import { payloadInitialTheme, payloadLocation } from "./full-payload.js";
 import { resolvedHandleStream } from "../handles/deferred-resolution.js";
 import type { RscPayload, ReactFormState } from "./types.js";
+import type { MatchResult } from "../types.js";
 import {
+  actionRenderRequest,
   createResponseWithMergedHeaders,
   finalizeResponse,
   buildRouteMiddlewareEntries,
@@ -78,17 +80,30 @@ export async function handleProgressiveEnhancement<TEnv>(
   // renders and the re-render), so a PE request prints ONE tree. A non-PE form
   // POST (no $ACTION fields) drives no plan and stays silent.
   const trace = INTERNAL_RANGO_DEBUG ? createRoutineTrace("pe") : undefined;
+  const input: PeRequestInput<TEnv> = {
+    ctx,
+    request,
+    env,
+    url,
+    handleStore,
+    nonce,
+    routeMwInfo,
+    trace,
+  };
   try {
-    return await handleProgressiveEnhancementInner(
-      ctx,
-      request,
-      env,
-      url,
-      handleStore,
-      nonce,
-      routeMwInfo,
-      trace,
-    );
+    const reqCtx = getRequestContext();
+    // A rewrite pass after the form's action ran: re-render, never run it again.
+    const ran = reqCtx._actionRan;
+    if (ran?.kind === "form") {
+      return await rerenderAfterFormAction(
+        input,
+        await outcomeForRewritePass(input, ran.outcome),
+      );
+    }
+    const outcome = await runFormAction(input);
+    if (!outcome || outcome instanceof Response) return outcome;
+    reqCtx._actionRan = { kind: "form", outcome };
+    return await rerenderAfterFormAction(input, outcome);
   } finally {
     if (trace && trace.entries.length > 0) {
       console.log(
@@ -98,16 +113,27 @@ export async function handleProgressiveEnhancement<TEnv>(
   }
 }
 
-async function handleProgressiveEnhancementInner<TEnv>(
-  ctx: HandlerContext<TEnv>,
-  request: Request,
-  env: TEnv,
-  url: URL,
-  handleStore: ReturnType<typeof getRequestContext>["_handleStore"],
-  nonce: string | undefined,
-  routeMwInfo: PeRouteMiddlewareInfo | undefined,
-  trace: RoutineTrace | undefined,
-): Promise<Response | null> {
+/** One PE request's inputs, shared by the action run and the re-render. */
+interface PeRequestInput<TEnv> {
+  ctx: HandlerContext<TEnv>;
+  request: Request;
+  env: TEnv;
+  url: URL;
+  handleStore: ReturnType<typeof getRequestContext>["_handleStore"];
+  nonce: string | undefined;
+  routeMwInfo: PeRouteMiddlewareInfo | undefined;
+  trace: RoutineTrace | undefined;
+}
+
+/**
+ * Run the no-JS form's action, outside route middleware. Returns the outcome
+ * the re-render renders from, a Response that ends the request (a redirect, a
+ * 400 for an unparseable body), or null for a POST that is not a form action.
+ */
+async function runFormAction<TEnv>(
+  input: PeRequestInput<TEnv>,
+): Promise<FormActionOutcome | Response | null> {
+  const { ctx, request, env, url } = input;
   // Clone the request to read FormData without consuming it.
   // Wrap in try-catch so malformed POST bodies are reported as action
   // errors, not routing errors from the outer catch in handler.ts.
@@ -116,32 +142,10 @@ async function handleProgressiveEnhancementInner<TEnv>(
     formData = await request.clone().formData();
   } catch (error) {
     // Attempt error boundary rendering so the user sees a meaningful page.
-    const errorHtml = await renderPeErrorBoundary(
-      ctx,
-      request,
-      env,
-      url,
-      error,
-      handleStore,
-      nonce,
-      trace,
-    );
-    if (errorHtml) {
-      ctx.callOnError(error, "action", {
-        request,
-        url,
-        env,
-        handledByBoundary: true,
-      });
-      return errorHtml;
+    const failure = await matchPeFailure(input, error, undefined, false);
+    if (failure.boundary) {
+      return { reactFormState: null, directActionId: null, failure };
     }
-
-    ctx.callOnError(error, "action", {
-      request,
-      url,
-      env,
-      handledByBoundary: false,
-    });
     console.error("[RSC] Progressive enhancement form parse error:", error);
     return createResponseWithMergedHeaders(null, { status: 400 });
   }
@@ -167,13 +171,7 @@ async function handleProgressiveEnhancementInner<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;
+  let failure: PeFailure | undefined;
 
   if (isUseActionState) {
     // Decode and extract action identity before execution so error
@@ -192,33 +190,7 @@ async function handleProgressiveEnhancementInner<TEnv>(
       // Handle thrown redirect (e.g., throw redirect('/path'))
       const redirectResponse = extractRedirectResponse(error);
       if (redirectResponse) return redirectResponse;
-
-      // Attempt error boundary rendering for the PE path
-      const errorHtml = await renderPeErrorBoundary(
-        ctx,
-        request,
-        env,
-        url,
-        error,
-        handleStore,
-        nonce,
-        trace,
-        useActionStateId,
-        true, // an action ran and threw
-      );
-      if (errorHtml) return errorHtml;
-
-      ctx.callOnError(error, "action", {
-        request,
-        url,
-        env,
-        actionId: useActionStateId,
-        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;
+      failure = await matchPeFailure(input, error, useActionStateId, true);
     }
   } else if (isDirectAction && directActionId) {
     const temporaryReferences = ctx.createTemporaryReferenceSet();
@@ -247,36 +219,17 @@ async function handleProgressiveEnhancementInner<TEnv>(
       // Handle thrown redirect (e.g., throw redirect('/path'))
       const redirectResponse = extractRedirectResponse(error);
       if (redirectResponse) return redirectResponse;
-
-      // Attempt error boundary rendering for the PE path
-      const errorHtml = await renderPeErrorBoundary(
-        ctx,
-        request,
-        env,
-        url,
-        error,
-        handleStore,
-        nonce,
-        trace,
-        directActionId,
-        true, // an action ran and threw
-      );
-      if (errorHtml) return errorHtml;
-
-      ctx.callOnError(error, "action", {
-        request,
-        url,
-        env,
-        actionId: directActionId,
-        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;
+      failure = await matchPeFailure(input, error, directActionId, true);
     }
   }
 
+  if (failure?.boundary) {
+    return { reactFormState: null, directActionId, failure };
+  }
+  if (failure) {
+    console.error("[RSC] Progressive enhancement action error:", failure.error);
+  }
+
   // Handle Response returned from action during PE.
   // In the JS path, executeServerAction intercepts redirect Responses and
   // short-circuits. The PE path must handle them too.
@@ -304,6 +257,58 @@ async function handleProgressiveEnhancementInner<TEnv>(
     console.error("[RSC] Failed to decode form state:", error);
   }
 
+  return { reactFormState, directActionId, failure };
+}
+
+/** What a no-JS form post's action left for the re-render (`_actionRan`). */
+export interface FormActionOutcome {
+  reactFormState: ReactFormState | null;
+  directActionId: string | null;
+  /** The action threw, or the form body did not parse. */
+  failure?: PeFailure;
+}
+
+/**
+ * A failed no-JS form post and the error boundary matched for it. The boundary
+ * renders in place of the page, inside route middleware as the JS path renders
+ * its own (server-action.ts `errorBoundary`). With none, the page re-renders
+ * with 500, the JS path's status for the same boundaryless error.
+ */
+export interface PeFailure {
+  error: unknown;
+  actionId: string | null | undefined;
+  boundary: MatchResult | null;
+}
+
+/**
+ * The outcome for a rewrite pass: a failure's boundary is re-matched on the
+ * target, since pass 1 matched (or missed) the rewriting route's
+ * (`continuationForRewritePass` in server-action.ts).
+ */
+async function outcomeForRewritePass<TEnv>(
+  input: PeRequestInput<TEnv>,
+  outcome: FormActionOutcome,
+): Promise<FormActionOutcome> {
+  const { failure } = outcome;
+  if (!failure) return outcome;
+  const boundary = await input.ctx.router.matchError(
+    input.request,
+    { env: input.env },
+    failure.error,
+    "route",
+  );
+  return { ...outcome, failure: { ...failure, boundary } };
+}
+
+/** The re-render after a no-JS form post's action, wrapped in route middleware. */
+async function rerenderAfterFormAction<TEnv>(
+  input: PeRequestInput<TEnv>,
+  outcome: FormActionOutcome,
+): Promise<Response> {
+  const { ctx, request, env, url, handleStore, nonce, routeMwInfo, trace } =
+    input;
+  const { failure } = outcome;
+
   // Re-render the page and return HTML.
   // Route middleware wraps the render so context variables, headers, and
   // cookies set by route middleware are available during re-render — matching
@@ -313,11 +318,7 @@ async function handleProgressiveEnhancementInner<TEnv>(
     // 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(requestHeaders(request));
-    headers.delete("content-type");
-    headers.delete("content-length");
-    headers.delete("content-encoding");
-    headers.delete("transfer-encoding");
+    const headers = bodylessHeaders(request);
     headers.set("accept", "text/html");
     const renderRequest = new Request(url.toString(), {
       method: "GET",
@@ -340,14 +341,17 @@ async function handleProgressiveEnhancementInner<TEnv>(
         renderRequest,
         handleStore,
         nonce,
-        reactFormState,
-        boundarylessErrorStatus,
-        directActionId,
+        ...outcome,
       }),
       { trace, owner: getRequestContext() },
     );
   };
 
+  const boundary = failure?.boundary;
+  const render = boundary
+    ? () => renderPeErrorBoundary(input, failure?.actionId, boundary)
+    : renderPage;
+
   // Execute route middleware wrapping the render, if any.
   // finalizeResponse drains onResponse callbacks that middleware short-circuits
   // may leave behind (executeMiddleware does not finalize them itself).
@@ -355,19 +359,19 @@ async function handleProgressiveEnhancementInner<TEnv>(
     return finalizeResponse(
       await executeMiddleware(
         buildRouteMiddlewareEntries(routeMwInfo.routeMiddleware),
-        request,
+        actionRenderRequest(request),
         env,
         routeMwInfo.variables,
-        renderPage,
+        render,
         routeMwInfo.routeReverse,
       ),
     );
   }
 
-  return renderPage();
+  return render();
 }
 
-interface PeRenderInput<TEnv> {
+interface PeRenderInput<TEnv> extends FormActionOutcome {
   ctx: HandlerContext<TEnv>;
   request: Request;
   env: TEnv;
@@ -375,9 +379,6 @@ interface PeRenderInput<TEnv> {
   renderRequest: Request;
   handleStore: ReturnType<typeof getRequestContext>["_handleStore"];
   nonce: string | undefined;
-  reactFormState: ReactFormState | null;
-  boundarylessErrorStatus: number | undefined;
-  directActionId: string | null;
 }
 
 /** PE re-render: match the bodyless GET mirror, then render full HTML. */
@@ -413,13 +414,13 @@ function renderPeResponse<TEnv>(
     handleStore,
     nonce,
     reactFormState,
-    boundarylessErrorStatus,
+    failure,
     directActionId,
   } = input;
 
   const payload: RscPayload = {
     metadata: {
-      pathname: url.pathname,
+      ...payloadLocation(getRequestContext(), url),
       routerId: ctx.router.id,
       basename: ctx.router.basename,
       segments: attachTransitionWhen(match.segments, getRequestContext()),
@@ -461,13 +462,10 @@ function renderPeResponse<TEnv>(
       url,
       payload,
       init: {
-        // 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 in peRenderPlan returns before this, so a redirect
-        // re-render keeps its 308 and is never overridden.
-        ...(boundarylessErrorStatus !== undefined
-          ? { status: boundarylessErrorStatus }
-          : {}),
+        // A failure reaching the page render matched no boundary: 500, like
+        // the JS path. The redirect branch in peRenderPlan returns before
+        // this, so a redirect re-render keeps its 308.
+        ...(failure ? { status: 500 } : {}),
         headers: { "content-type": "text/html;charset=utf-8" },
       },
       tracking: stageTracking,
@@ -487,80 +485,22 @@ function renderPeResponse<TEnv>(
   );
 }
 
-interface PeErrorBoundaryInput<TEnv> {
-  ctx: HandlerContext<TEnv>;
-  request: Request;
-  env: TEnv;
-  url: URL;
-  error: unknown;
-  handleStore: ReturnType<typeof getRequestContext>["_handleStore"];
-  nonce: string | undefined;
-  actionId: string | null | undefined;
-  actionRan: boolean;
-}
-
-type PeErrorMatch<TEnv> = NonNullable<
-  Awaited<ReturnType<HandlerContext<TEnv>["router"]["matchError"]>>
->;
-
 /**
- * Attempt to render an error boundary as full HTML for the PE path.
- * Returns null if no error boundary is found (caller falls through to
- * normal page re-render).
+ * Match an error boundary for a failed PE post and report the error, handled
+ * or not. A matchError failure reports the ORIGINAL error as unhandled and
+ * rethrows the match failure.
  */
-async function renderPeErrorBoundary<TEnv>(
-  ctx: HandlerContext<TEnv>,
-  request: Request,
-  env: TEnv,
-  url: URL,
+async function matchPeFailure<TEnv>(
+  input: PeRequestInput<TEnv>,
   error: unknown,
-  handleStore: ReturnType<typeof getRequestContext>["_handleStore"],
-  nonce: string | undefined,
-  trace: RoutineTrace | undefined,
-  actionId?: string | null,
+  actionId: string | null | undefined,
   // 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> {
-  return runRoutine(
-    peErrorBoundaryPlan({
-      ctx,
-      request,
-      env,
-      url,
-      error,
-      handleStore,
-      nonce,
-      actionId,
-      actionRan,
-    }),
-    { trace, owner: getRequestContext() },
-  );
-}
-
-/** PE error boundary: match a boundary for the thrown error, then render it. */
-function* peErrorBoundaryPlan<TEnv>(
-  input: PeErrorBoundaryInput<TEnv>,
-): RoutinePlan<Response | null> {
-  const boundary = yield* step("match:error", () =>
-    matchPeErrorBoundary(input),
-  );
-  if (!boundary) return null;
-  return yield* step("render", () => renderPeErrorResponse(input, boundary));
-}
-
-/**
- * Match an error boundary for the PE path, owning the reporting protocol:
- * a matchError failure reports the ORIGINAL error as unhandled and rethrows
- * the match failure; a miss returns null; a hit reports handled and stamps
- * params + action gate context before the render.
- */
-async function matchPeErrorBoundary<TEnv>(
-  input: PeErrorBoundaryInput<TEnv>,
-): Promise<PeErrorMatch<TEnv> | null> {
-  const { ctx, request, env, url, error, actionId, actionRan } = input;
+  actionRan: boolean,
+): Promise<PeFailure> {
+  const { ctx, request, env, url } = input;
 
   // JS/PE parity for an action-triggered error re-render: a stale
   // `foregroundOnAction` cache entry inside the error boundary must foreground
@@ -572,9 +512,9 @@ async function matchPeErrorBoundary<TEnv>(
     getRequestContext()._inActionRevalidation = true;
   }
 
-  let errorResult;
+  let boundary: MatchResult | null;
   try {
-    errorResult = await ctx.router.matchError(request, { env }, error, "route");
+    boundary = await ctx.router.matchError(request, { env }, error, "route");
   } catch (matchErr) {
     ctx.callOnError(error, "action", {
       request,
@@ -586,31 +526,41 @@ async function matchPeErrorBoundary<TEnv>(
     throw matchErr;
   }
 
-  if (!errorResult) return null;
-
   ctx.callOnError(error, "action", {
     request,
     url,
     env,
     actionId: actionId ?? undefined,
-    handledByBoundary: true,
+    handledByBoundary: !!boundary,
   });
+  return { error, actionId, boundary };
+}
 
-  setRequestContextParams(errorResult.params, errorResult.routeName);
-
-  return errorResult;
+/** Render a failed PE post's boundary, inside route middleware. */
+function renderPeErrorBoundary<TEnv>(
+  input: PeRequestInput<TEnv>,
+  actionId: string | null | undefined,
+  boundary: MatchResult,
+): Promise<Response> {
+  return runRoutine(
+    step("render", () => renderPeErrorResponse(input, actionId, boundary)),
+    { trace: input.trace, owner: getRequestContext() },
+  );
 }
 
 /** Render the matched PE error boundary as a full HTML document. */
 function renderPeErrorResponse<TEnv>(
-  input: PeErrorBoundaryInput<TEnv>,
-  errorResult: PeErrorMatch<TEnv>,
+  input: PeRequestInput<TEnv>,
+  actionId: string | null | undefined,
+  errorResult: MatchResult,
 ): Promise<Response> {
-  const { ctx, request, env, url, handleStore, nonce, actionId } = input;
+  const { ctx, request, env, url, handleStore, nonce } = input;
+
+  setRequestContextParams(errorResult.params, errorResult.routeName);
 
   const payload: RscPayload = {
     metadata: {
-      pathname: url.pathname,
+      ...payloadLocation(getRequestContext(), url),
       routerId: ctx.router.id,
       basename: ctx.router.basename,
       segments: attachTransitionWhen(errorResult.segments, getRequestContext()),

package/src/rsc/rewrite-passes.ts

@@ -21,7 +21,11 @@ import {
   rebaseRequestContext,
   type RequestContext,
 } from "../server/request-context.js";
-import { recordRewriteHop } from "../server/rewrite-trail.js";
+import { bodylessRequest } from "../server/request-headers.js";
+import {
+  recordRewriteHop,
+  recordRewriteShell,
+} from "../server/rewrite-trail.js";
 
 /** Response header naming the route path a rewritten request rendered. */
 export const REWRITE_HEADER = "x-rango-rewrite";
@@ -45,11 +49,9 @@ export function resolveRewriteTarget(
   const path =
     "path" in target
       ? prefixBasename(target.path, basename)
-      : // `{}`, not undefined: a route with params then throws for the
-        // missing ones instead of resolving to its raw pattern.
-        createReverseFunction(routeMap)(
+      : createReverseFunction(routeMap)(
           target.name,
-          target.params ?? {},
+          target.params,
           target.search,
         );
   const resolved = stripInternalParams(new URL(path, base.origin));
@@ -94,11 +96,38 @@ export interface RewritePass {
   hops: number;
 }
 
+let lateLockReported = false;
+
+/**
+ * `.disallowMutations()` thrown after the action ran cannot refuse it. Dev
+ * warns on every throw; production logs one error per isolate, so a lock
+ * that never refused anything is not silent there.
+ */
+function reportLateLock(rewrite: Rewrite): void {
+  const message = `[rango] ${describeRewriteTarget(rewrite.target)}.disallowMutations() came after the server action or form post ran, so it cannot refuse it: route middleware, and global middleware on a later rewritten pass, run only after the action. The render moves to the target. To refuse mutations, throw it from global middleware (router.use()) matched on the URL the form posts to.`;
+  if (process.env.NODE_ENV !== "production") {
+    console.warn(message);
+  } else if (!lateLockReported) {
+    lateLockReported = true;
+    console.error(message);
+  }
+}
+
 /**
  * Move the request context to `rewrite`'s target for the next pass: check
  * that this request can be rewritten, resolve the target, count the hop,
- * then rebase the context. Throws the site error for a mutation or a loader
- * fetch, a resolution error, and RewriteLoopError.
+ * then rebase the context. Throws the site error for a loader fetch, a
+ * refused mutation or one whose body middleware read before its action ran,
+ * a resolution error, and RewriteLoopError.
+ *
+ * A mutation moves too (#1145). Before its action ran (a rewrite from global
+ * middleware) it moves with its body, and the target's pass runs the action
+ * after the target's global middleware, as a direct post there would. After
+ * it ran (route middleware wraps only the re-render), the target's pass
+ * re-renders from `reqCtx._actionRan`. `disallowMutations()` refuses the
+ * first, so a lock never runs a mutation; the second is already committed,
+ * and refusing it reports an error for a write that happened, so the caller
+ * retries it.
  */
 export function applyRewrite(
   rewrite: Rewrite,
@@ -113,12 +142,30 @@ export function applyRewrite(
     throw rewriteNotSupported(rewrite, "loader-fetch");
   }
   if (passRequest.method !== "GET" && passRequest.method !== "HEAD") {
-    throw rewriteNotSupported(rewrite, "mutation");
+    if (!reqCtx._actionRan) {
+      if (rewrite.mutationsDisallowed) {
+        throw rewriteNotSupported(rewrite, "mutation");
+      }
+      // The target's pass hands the body to the action: one middleware read
+      // would run it with no arguments.
+      if (passRequest.bodyUsed) throw rewriteNotSupported(rewrite, "body-read");
+    } else if (rewrite.mutationsDisallowed) {
+      reportLateLock(rewrite);
+    }
   }
   const target = resolveRewriteTarget(rewrite, routeMap, reqCtx.url, basename);
   const hops = recordRewriteHop(reqCtx, reqCtx.url, target);
+  recordRewriteShell(reqCtx, rewrite.shellAudience);
   const url = rewriteTransportUrl(target, reqCtx.originalUrl);
-  const request = new Request(url, passRequest);
+  // A mutation keeps its body: one whose action has not run yet, and a no-JS
+  // form post, since the PE handler reads a clone, so a form-field check
+  // reads it on every pass. A JS action that ran consumed it
+  // (`new Request(url, used)` throws): the same request without it or its
+  // content-type, so a body check gated on the content-type passes over this
+  // pass, which never runs the action.
+  const request = passRequest.bodyUsed
+    ? bodylessRequest(url, passRequest, passRequest.method)
+    : new Request(url, passRequest);
   rebaseRequestContext(reqCtx, request, url);
   return { request, url, target, hops };
 }