@rangojs/router 0.0.0-experimental.18 → 0.0.0-experimental.1878aa49

package/src/rsc/progressive-enhancement.ts

@@ -10,9 +10,33 @@ import {
   requireRequestContext,
   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 type { RscPayload, ReactFormState } from "./types.js";
-import { createResponseWithMergedHeaders } from "./helpers.js";
+import {
+  createResponseWithMergedHeaders,
+  finalizeResponse,
+  buildRouteMiddlewareEntries,
+} from "./helpers.js";
 import type { HandlerContext } from "./handler-context.js";
+import {
+  extractRedirectResponse,
+  warnNonRedirectPeResponse,
+} from "./runtime-warnings.js";
+
+export interface PeRouteMiddlewareInfo {
+  routeMiddleware?: Array<{
+    handler: MiddlewareFn;
+    params: Record<string, string>;
+  }>;
+  variables: Record<string, any>;
+  routeReverse?: (
+    name: string,
+    params?: Record<string, string>,
+    search?: Record<string, unknown>,
+  ) => string;
+}
 
 export async function handleProgressiveEnhancement<TEnv>(
   ctx: HandlerContext<TEnv>,
@@ -22,6 +46,7 @@ export async function handleProgressiveEnhancement<TEnv>(
   isAction: boolean,
   handleStore: ReturnType<typeof requireRequestContext>["_handleStore"],
   nonce: string | undefined,
+  routeMwInfo?: PeRouteMiddlewareInfo,
 ): Promise<Response | null> {
   const contentType = request.headers.get("content-type") || "";
   const isFormSubmission =
@@ -32,8 +57,42 @@ export async function handleProgressiveEnhancement<TEnv>(
     return null;
   }
 
-  // Clone the request to read FormData without consuming it
-  const formData = await request.clone().formData();
+  // 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.
+  let formData: FormData;
+  try {
+    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,
+    );
+    if (errorHtml) {
+      ctx.callOnError(error, "action", {
+        request,
+        url,
+        env,
+        handledByBoundary: true,
+      });
+      return errorHtml;
+    }
+
+    ctx.callOnError(error, "action", {
+      request,
+      url,
+      env,
+      handledByBoundary: false,
+    });
+    console.error("[RSC] Progressive enhancement form parse error:", error);
+    return createResponseWithMergedHeaders(null, { status: 400 });
+  }
 
   // Look for React's progressive enhancement hidden fields
   let isDirectAction = false;
@@ -58,14 +117,37 @@ export async function handleProgressiveEnhancement<TEnv>(
   let reactFormState: ReactFormState | null = null;
 
   if (isUseActionState) {
+    // Decode and extract action identity before execution so error
+    // handlers can report actionId even when the action throws.
+    let useActionStateId: string | undefined;
     try {
       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();
     } catch (error) {
+      // 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,
+        useActionStateId,
+      );
+      if (errorHtml) return errorHtml;
+
       ctx.callOnError(error, "action", {
         request,
         url,
         env,
+        actionId: useActionStateId,
         handledByBoundary: false,
       });
       console.error("[RSC] Progressive enhancement action error:", error);
@@ -84,6 +166,23 @@ export async function handleProgressiveEnhancement<TEnv>(
       const loadedAction = await ctx.loadServerAction(directActionId);
       actionResult = await loadedAction.apply(null, args);
     } catch (error) {
+      // 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,
+        directActionId,
+      );
+      if (errorHtml) return errorHtml;
+
       ctx.callOnError(error, "action", {
         request,
         url,
@@ -95,6 +194,20 @@ export async function handleProgressiveEnhancement<TEnv>(
     }
   }
 
+  // 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.
+  if (actionResult instanceof Response) {
+    const redirectResponse = extractRedirectResponse(actionResult);
+    if (redirectResponse) return redirectResponse;
+    // W3: Non-redirect Response — discard it so it doesn't flow into
+    // decodeFormState or the re-render payload.
+    if (process.env.NODE_ENV !== "production") {
+      warnNonRedirectPeResponse();
+    }
+    actionResult = undefined;
+  }
+
   // Decode form state for useActionState progressive enhancement
   try {
     reactFormState = await ctx.decodeFormState(actionResult, formData);
@@ -108,28 +221,136 @@ export async function handleProgressiveEnhancement<TEnv>(
     console.error("[RSC] Failed to decode form state:", error);
   }
 
-  // Re-render the page and return HTML
-  const renderRequest = new Request(url.toString(), {
-    method: "GET",
-    headers: new Headers({ accept: "text/html" }),
-  });
+  // 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
+  // the behavior of JS-enabled requests.
+  const renderPage = async (): Promise<Response> => {
+    const renderRequest = new Request(url.toString(), {
+      method: "GET",
+      headers: new Headers({ accept: "text/html" }),
+    });
 
-  const match = await ctx.router.match(renderRequest, { env });
+    const match = await ctx.router.match(renderRequest, { env });
 
-  if (match.redirect) {
-    return createResponseWithMergedHeaders(null, {
-      status: 308,
-      headers: { Location: match.redirect },
+    if (match.redirect) {
+      return createResponseWithMergedHeaders(null, {
+        status: 308,
+        headers: { Location: match.redirect },
+      });
+    }
+
+    const payload: RscPayload = {
+      metadata: {
+        pathname: url.pathname,
+        routerId: ctx.router.id,
+        basename: ctx.router.basename,
+        segments: match.segments,
+        matched: match.matched,
+        diff: match.diff,
+        isPartial: false,
+        rootLayout: ctx.router.rootLayout,
+        handles: handleStore.stream(),
+        version: ctx.version,
+        themeConfig: ctx.router.themeConfig,
+        warmupEnabled: ctx.router.warmupEnabled,
+        initialTheme: requireRequestContext().theme,
+      },
+      formState: actionResult,
+    };
+
+    const rscStream = ctx.renderToReadableStream<RscPayload>(payload);
+    // metricsStore=undefined is safe: the handler already stashed the early
+    // SSR setup promise on request variables, so getSSRSetup returns it
+    // without falling back to a fresh startSSRSetup.
+    const [ssrModule, streamMode] = await getSSRSetup(
+      ctx,
+      request,
+      env,
+      url,
+      undefined,
+    );
+    const htmlStream = await ssrModule.renderHTML(rscStream, {
+      formState: reactFormState,
+      nonce,
+      streamMode,
     });
+
+    return createResponseWithMergedHeaders(htmlStream, {
+      headers: { "content-type": "text/html;charset=utf-8" },
+    });
+  };
+
+  // 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).
+  if (routeMwInfo?.routeMiddleware && routeMwInfo.routeMiddleware.length > 0) {
+    return finalizeResponse(
+      await executeMiddleware(
+        buildRouteMiddlewareEntries(routeMwInfo.routeMiddleware),
+        request,
+        env,
+        routeMwInfo.variables,
+        renderPage,
+        routeMwInfo.routeReverse,
+      ),
+    );
   }
 
+  return renderPage();
+}
+
+/**
+ * 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).
+ */
+async function renderPeErrorBoundary<TEnv>(
+  ctx: HandlerContext<TEnv>,
+  request: Request,
+  env: TEnv,
+  url: URL,
+  error: unknown,
+  handleStore: ReturnType<typeof requireRequestContext>["_handleStore"],
+  nonce: string | undefined,
+  actionId?: string | null,
+): Promise<Response | null> {
+  let errorResult;
+  try {
+    errorResult = await ctx.router.matchError(request, { env }, error, "route");
+  } catch (matchErr) {
+    ctx.callOnError(error, "action", {
+      request,
+      url,
+      env,
+      actionId: actionId ?? undefined,
+      handledByBoundary: false,
+    });
+    throw matchErr;
+  }
+
+  if (!errorResult) return null;
+
+  ctx.callOnError(error, "action", {
+    request,
+    url,
+    env,
+    actionId: actionId ?? undefined,
+    handledByBoundary: true,
+  });
+
+  setRequestContextParams(errorResult.params, errorResult.routeName);
+
   const payload: RscPayload = {
     metadata: {
       pathname: url.pathname,
-      segments: match.segments,
-      matched: match.matched,
-      diff: match.diff,
+      routerId: ctx.router.id,
+      basename: ctx.router.basename,
+      segments: errorResult.segments,
+      matched: errorResult.matched,
+      diff: errorResult.diff,
       isPartial: false,
+      isError: true,
       rootLayout: ctx.router.rootLayout,
       handles: handleStore.stream(),
       version: ctx.version,
@@ -137,17 +358,26 @@ export async function handleProgressiveEnhancement<TEnv>(
       warmupEnabled: ctx.router.warmupEnabled,
       initialTheme: requireRequestContext().theme,
     },
-    formState: actionResult,
   };
 
   const rscStream = ctx.renderToReadableStream<RscPayload>(payload);
-  const ssrModule = await ctx.loadSSRModule();
+  // metricsStore=undefined is safe: the handler already stashed the early
+  // SSR setup promise on request variables, so getSSRSetup returns it
+  // without falling back to a fresh startSSRSetup.
+  const [ssrModule, streamMode] = await getSSRSetup(
+    ctx,
+    request,
+    env,
+    url,
+    undefined,
+  );
   const htmlStream = await ssrModule.renderHTML(rscStream, {
-    formState: reactFormState,
     nonce,
+    streamMode,
   });
 
   return createResponseWithMergedHeaders(htmlStream, {
+    status: 500,
     headers: { "content-type": "text/html;charset=utf-8" },
   });
 }

package/src/rsc/response-route-handler.ts

@@ -23,6 +23,7 @@ import type { HandlerContext } from "./handler-context.js";
 import { createResponseErrorPayload } from "./response-error.js";
 import {
   createResponseWithMergedHeaders,
+  finalizeResponse,
   isCacheableStatus,
   buildRouteMiddlewareEntries,
 } from "./helpers.js";
@@ -70,25 +71,15 @@ export async function handleResponseRoute<TEnv>(
 
   // Build lightweight context for response handler
   const reqCtx = requireRequestContext();
+  const cleanUrl = stripInternalParams(url);
   const responseHandlerCtx = {
     request,
     params: preview.params || {},
     env,
-    searchParams: url.searchParams,
-    url,
+    searchParams: cleanUrl.searchParams,
+    url: cleanUrl,
     pathname: url.pathname,
-    href: (name: string, hrefParams?: Record<string, string>) => {
-      if (name.startsWith("/")) {
-        if (!hrefParams) return name;
-        return name.replace(/:([^/]+)/g, (_, key) => {
-          const value = hrefParams[key];
-          if (value === undefined)
-            throw new Error(`Missing param "${key}" for path "${name}"`);
-          return encodeURIComponent(value);
-        });
-      }
-      return name;
-    },
+    reverse: createReverseFunction(handlerCtx.getRequiredRouteMap()),
     get: ((keyOrVar: any) => contextGet(variables, keyOrVar)) as any,
     header: (name: string, value: string) => reqCtx.header(name, value),
     _responseType: preview.responseType,
@@ -103,10 +94,15 @@ export async function handleResponseRoute<TEnv>(
 
     // Re-wrap a handler-returned Response through createResponseWithMergedHeaders
     // so that stub headers (cookies, custom headers set via ctx.header()) are included.
+    // Use Headers (not Record<string, string>) to preserve duplicate entries like Set-Cookie.
     const rewrapResponse = (result: Response) => {
-      const headers: Record<string, string> = {};
+      const headers = new Headers();
       result.headers.forEach((value, key) => {
-        headers[key] = value;
+        if (key.toLowerCase() === "set-cookie") {
+          headers.append(key, value);
+        } else {
+          headers.set(key, value);
+        }
       });
       return createResponseWithMergedHeaders(result.body, {
         status: result.status,
@@ -231,12 +227,23 @@ export async function handleResponseRoute<TEnv>(
     }
 
     if (cacheScope?.enabled) {
+      // Evaluate condition — skip 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 (store?.getResponse && store?.putResponse) {
+      if (conditionPassed && store?.getResponse && store?.putResponse) {
         // Build cache key with response:{type}: prefix to avoid collision
         // with segment keys and differentiate between response types.
-        // Include url.search so query-driven responses cache separately.
-        let cacheKey = `response:${preview.responseType}:${url.pathname}${url.search}`;
+        // Include host and url.search so query-driven and multi-host
+        // responses cache separately.
+        let cacheKey = `response:${preview.responseType}:${url.host}${url.pathname}${url.search}`;
 
         // Priority 1: Route-level key function (full override)
         if (cacheScope.config !== false && cacheScope.config.key) {
@@ -286,11 +293,14 @@ export async function handleResponseRoute<TEnv>(
             // Stale hit (SWR) - return cached, revalidate in background
             reqCtx.waitUntil(async () => {
               try {
-                const fresh = await executeHandler();
+                // finalizeResponse drains any onResponse callbacks registered
+                // during middleware execution (e.g. middleware short-circuit)
+                // that createResponseWithMergedHeaders didn't reach.
+                const fresh = finalizeResponse(await executeHandler());
                 if (isCacheableStatus(fresh.status)) {
                   await store.putResponse!(
                     cacheKey,
-                    fresh,
+                    fresh.clone(),
                     cacheScope!.ttl,
                     cacheScope!.swr,
                   );
@@ -307,10 +317,11 @@ export async function handleResponseRoute<TEnv>(
         }
 
         // Cache miss - execute handler and cache the result.
-        // createResponseWithMergedHeaders inside the handler applies
-        // any callbacks registered during execution, so the response
-        // (and its clone) already include those transforms.
-        const response = await executeHandler();
+        // createResponseWithMergedHeaders inside the handler drains callbacks
+        // registered during handler execution. finalizeResponse catches any
+        // remaining callbacks (e.g. from middleware short-circuit where the
+        // handler never ran) so the cached artifact includes all transforms.
+        const response = finalizeResponse(await executeHandler());
 
         if (isCacheableStatus(response.status)) {
           reqCtx.waitUntil(async () => {
@@ -332,5 +343,5 @@ export async function handleResponseRoute<TEnv>(
     }
   }
 
-  return executeHandler();
+  return executeHandler().then(finalizeResponse);
 }

package/src/rsc/rsc-rendering.ts

@@ -12,6 +12,8 @@ import {
   getLocationState,
 } from "../server/request-context.js";
 import { resolveLocationStateEntries } from "../browser/react/location-state-shared.js";
+import { appendMetric } from "../router/metrics.js";
+import { getSSRSetup } from "./ssr-setup.js";
 import type { RscPayload } from "./types.js";
 import {
   createResponseWithMergedHeaders,
@@ -28,13 +30,9 @@ export async function handleRscRendering<TEnv>(
   handleStore: ReturnType<typeof requireRequestContext>["_handleStore"],
   nonce: string | undefined,
 ): Promise<Response> {
-  // Retrieve handler-level timing from variables
   const reqCtx = requireRequestContext();
-  const handlerTimingArr: string[] = reqCtx.var.__handlerTiming || [];
-  const handlerStart: number = reqCtx.var.__handlerStart || 0;
 
   let payload: RscPayload;
-  let serverTiming: string | undefined;
   let hasInterceptSlots = false;
 
   if (isPartial) {
@@ -53,11 +51,11 @@ export async function handleRscRendering<TEnv>(
         return createSimpleRedirectResponse(match.redirect);
       }
 
-      serverTiming = match.serverTiming;
-
       payload = {
         metadata: {
           pathname: url.pathname,
+          routerId: ctx.router.id,
+          basename: ctx.router.basename,
           segments: match.segments,
           matched: match.matched,
           diff: match.diff,
@@ -66,18 +64,20 @@ export async function handleRscRendering<TEnv>(
           rootLayout: ctx.router.rootLayout,
           handles: handleStore.stream(),
           version: ctx.version,
+          prefetchCacheTTL: ctx.router.prefetchCacheTTL,
           themeConfig: ctx.router.themeConfig,
           initialTheme: reqCtx.theme,
         },
       };
     } else {
       setRequestContextParams(result.params, result.routeName);
-      serverTiming = result.serverTiming;
+
       hasInterceptSlots = !!result.slots;
 
       payload = {
         metadata: {
           pathname: url.pathname,
+          routerId: ctx.router.id,
           segments: result.segments,
           matched: result.matched,
           diff: result.diff,
@@ -86,6 +86,7 @@ export async function handleRscRendering<TEnv>(
           slots: result.slots,
           handles: handleStore.stream(),
           version: ctx.version,
+          prefetchCacheTTL: ctx.router.prefetchCacheTTL,
         },
       };
     }
@@ -111,6 +112,7 @@ export async function handleRscRendering<TEnv>(
       const nonLoaderSegments = match.segments.filter(
         (s) => s.type !== "loader",
       );
+      handleStore.seal();
       await handleStore.settled;
       const { serializeSegments } = await import("../cache/segment-codec.js");
       const serializedSegments = await serializeSegments(nonLoaderSegments);
@@ -131,14 +133,14 @@ export async function handleRscRendering<TEnv>(
         { headers: { "Content-Type": "application/json" } },
       );
     } else {
-      serverTiming = match.serverTiming;
-
       payload = {
         // Initial SSR can reconstruct the tree from segments + rootLayout,
         // so we omit root to avoid sending the same structure twice.
 
         metadata: {
           pathname: url.pathname,
+          routerId: ctx.router.id,
+          basename: ctx.router.basename,
           segments: match.segments,
           matched: match.matched,
           diff: match.diff,
@@ -147,6 +149,7 @@ export async function handleRscRendering<TEnv>(
           rootLayout: ctx.router.rootLayout,
           handles: handleStore.stream(),
           version: ctx.version,
+          prefetchCacheTTL: ctx.router.prefetchCacheTTL,
           themeConfig: ctx.router.themeConfig,
           initialTheme: reqCtx.theme,
         },
@@ -165,10 +168,20 @@ export async function handleRscRendering<TEnv>(
     }
   }
 
+  const metricsStore = reqCtx._metricsStore;
+  const renderStart = performance.now();
+
   // Serialize to RSC stream
   const rscSerializeStart = performance.now();
   const rscStream = ctx.renderToReadableStream<RscPayload>(payload);
   const rscSerializeDur = performance.now() - rscSerializeStart;
+  // This measures synchronous stream creation, not end-to-end stream consumption.
+  appendMetric(
+    metricsStore,
+    "rsc-serialize",
+    rscSerializeStart,
+    rscSerializeDur,
+  );
 
   // Determine if this is an RSC request or HTML request.
   // Partial requests (_rsc_partial) are always RSC -- they come from client-side
@@ -180,15 +193,9 @@ export async function handleRscRendering<TEnv>(
       !url.searchParams.has("__html")) ||
     url.searchParams.has("__rsc");
 
-  // Build complete Server-Timing: handler phases + match/manifest + RSC serialize
-  const timingParts: string[] = [...handlerTimingArr];
-  if (serverTiming) {
-    timingParts.push(serverTiming);
-  }
-  timingParts.push(`rsc-serialize;dur=${rscSerializeDur.toFixed(2)}`);
-
   if (isRscRequest) {
-    const fullTiming = timingParts.join(", ");
+    const renderDur = performance.now() - renderStart;
+    appendMetric(metricsStore, "render:total", renderStart, renderDur);
     const rscHeaders: Record<string, string> = {
       "content-type": "text/x-component;charset=utf-8",
       vary: "accept, X-Rango-State, X-RSC-Router-Client-Path",
@@ -204,40 +211,32 @@ export async function handleRscRendering<TEnv>(
         rscHeaders["cache-control"] = cc;
       }
     }
-    if (fullTiming) {
-      rscHeaders["Server-Timing"] = fullTiming;
-    }
     return createResponseWithMergedHeaders(rscStream, {
       headers: rscHeaders,
     });
   }
 
-  // Delegate to SSR for HTML response
-  const ssrModuleStart = performance.now();
-  const ssrModule = await ctx.loadSSRModule();
-  const ssrModuleDur = performance.now() - ssrModuleStart;
-  timingParts.push(`ssr-module-load;dur=${ssrModuleDur.toFixed(2)}`);
+  // Delegate to SSR for HTML response (reuse early setup if available)
+  const [ssrModule, streamMode] = await getSSRSetup(
+    ctx,
+    request,
+    env,
+    url,
+    metricsStore,
+  );
 
   const ssrRenderStart = performance.now();
-  const htmlStream = await ssrModule.renderHTML(rscStream, { nonce });
+  const htmlStream = await ssrModule.renderHTML(rscStream, {
+    nonce,
+    streamMode,
+  });
   const ssrRenderDur = performance.now() - ssrRenderStart;
-  timingParts.push(`ssr-render-html;dur=${ssrRenderDur.toFixed(2)}`);
+  appendMetric(metricsStore, "ssr-render-html", ssrRenderStart, ssrRenderDur);
 
-  // Add total handler duration
-  if (handlerStart) {
-    const totalHandler = performance.now() - handlerStart;
-    timingParts.push(`handler-total;dur=${totalHandler.toFixed(2)}`);
-  }
-
-  const fullTiming = timingParts.join(", ");
-  const htmlHeaders: Record<string, string> = {
-    "content-type": "text/html;charset=utf-8",
-  };
-  if (fullTiming) {
-    htmlHeaders["Server-Timing"] = fullTiming;
-  }
+  const renderDur = performance.now() - renderStart;
+  appendMetric(metricsStore, "render:total", renderStart, renderDur);
 
   return createResponseWithMergedHeaders(htmlStream, {
-    headers: htmlHeaders,
+    headers: { "content-type": "text/html;charset=utf-8" },
   });
 }