@rangojs/router 0.0.0-experimental.259 → 0.0.0-experimental.26

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,132 @@ 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,
+        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,
+      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 +354,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

@@ -0,0 +1,347 @@
+/**
+ * Response Route Handler
+ *
+ * Handles response routes (JSON, text, HTML, XML, markdown, image, stream)
+ * that bypass the RSC rendering pipeline entirely. Includes content-type
+ * dispatch, route middleware execution, and response caching with SWR.
+ */
+
+import { RouterError } from "../errors.js";
+import { requireRequestContext } from "../server/request-context.js";
+import { contextGet } from "../context-var.js";
+import { NOCACHE_SYMBOL } from "../cache/taint.js";
+import { traverseBack } from "../router/pattern-matching.js";
+import { createCacheScope } from "../cache/cache-scope.js";
+import { executeMiddleware } from "../router/middleware.js";
+import {
+  createReverseFunction,
+  stripInternalParams,
+} from "../router/handler-context.js";
+import type { MiddlewareFn } from "../router/middleware.js";
+import type { EntryData } from "../server/context.js";
+import type { HandlerContext } from "./handler-context.js";
+import { createResponseErrorPayload } from "./response-error.js";
+import {
+  createResponseWithMergedHeaders,
+  finalizeResponse,
+  isCacheableStatus,
+  buildRouteMiddlewareEntries,
+} from "./helpers.js";
+
+export interface ResponseRouteMatch {
+  responseType: string;
+  handler: Function;
+  params?: Record<string, string>;
+  negotiated?: boolean;
+  manifestEntry?: EntryData;
+  routeMiddleware?: Array<{
+    handler: MiddlewareFn;
+    params: Record<string, string>;
+  }>;
+}
+
+/**
+ * Handle a response route (non-RSC). Dispatches by content type, wraps
+ * with route middleware and response caching when configured.
+ *
+ * For partial (client-side navigation) requests, returns X-RSC-Reload
+ * so the browser triggers a hard navigation to the response route URL.
+ */
+export async function handleResponseRoute<TEnv>(
+  handlerCtx: HandlerContext<TEnv>,
+  preview: ResponseRouteMatch,
+  request: Request,
+  env: TEnv,
+  url: URL,
+  variables: Record<string, any>,
+): Promise<Response> {
+  const isPartial = url.searchParams.has("_rsc_partial");
+
+  // Partial requests (client-side navigation) to response routes
+  // get X-RSC-Reload to trigger hard navigation in the browser
+  if (isPartial) {
+    return createResponseWithMergedHeaders(null, {
+      status: 200,
+      headers: {
+        "X-RSC-Reload": stripInternalParams(url).toString(),
+        "content-type": "text/x-component;charset=utf-8",
+      },
+    });
+  }
+
+  // Build lightweight context for response handler
+  const reqCtx = requireRequestContext();
+  const cleanUrl = stripInternalParams(url);
+  const responseHandlerCtx = {
+    request,
+    params: preview.params || {},
+    env,
+    searchParams: cleanUrl.searchParams,
+    url: cleanUrl,
+    pathname: url.pathname,
+    reverse: createReverseFunction(handlerCtx.getRequiredRouteMap()),
+    get: ((keyOrVar: any) => contextGet(variables, keyOrVar)) as any,
+    header: (name: string, value: string) => reqCtx.header(name, value),
+    _responseType: preview.responseType,
+  };
+  // Brand with taint symbol so "use cache" detects it as request-scoped
+  // and extracts route-identifying properties (params, pathname, _responseType)
+  (responseHandlerCtx as any)[NOCACHE_SYMBOL] = true;
+
+  // Call handler directly, wrapped by route middleware if present
+  const callHandler = async () => {
+    const errorCtx = { request, url, env };
+
+    // 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 = new Headers();
+      result.headers.forEach((value, key) => {
+        if (key.toLowerCase() === "set-cookie") {
+          headers.append(key, value);
+        } else {
+          headers.set(key, value);
+        }
+      });
+      return createResponseWithMergedHeaders(result.body, {
+        status: result.status,
+        headers,
+      });
+    };
+
+    // JSON response routes: wrap in { data } / { error } envelope
+    if (preview.responseType === "json") {
+      try {
+        const result = await (preview.handler as Function)(responseHandlerCtx);
+        if (result instanceof Response) {
+          return rewrapResponse(result);
+        }
+        return createResponseWithMergedHeaders(
+          JSON.stringify({ data: result }),
+          {
+            status: 200,
+            headers: { "content-type": "application/json;charset=utf-8" },
+          },
+        );
+      } catch (error) {
+        handlerCtx.callOnError(error, "handler", errorCtx);
+        const isDev = process.env.NODE_ENV !== "production";
+        const status = error instanceof RouterError ? error.status : 500;
+        return createResponseWithMergedHeaders(
+          JSON.stringify({
+            error: createResponseErrorPayload(error, isDev),
+          }),
+          {
+            status,
+            headers: { "content-type": "application/json;charset=utf-8" },
+          },
+        );
+      }
+    }
+
+    // Non-JSON response routes: catch errors and return plain Response
+    try {
+      const result = await (preview.handler as Function)(responseHandlerCtx);
+
+      if (result instanceof Response) {
+        return rewrapResponse(result);
+      }
+
+      // Auto-wrap based on response type tag
+      switch (preview.responseType) {
+        case "text":
+          return createResponseWithMergedHeaders(String(result), {
+            status: 200,
+            headers: { "content-type": "text/plain;charset=utf-8" },
+          });
+        case "html":
+          return createResponseWithMergedHeaders(String(result), {
+            status: 200,
+            headers: { "content-type": "text/html;charset=utf-8" },
+          });
+        case "xml":
+          return createResponseWithMergedHeaders(String(result), {
+            status: 200,
+            headers: { "content-type": "application/xml;charset=utf-8" },
+          });
+        case "md":
+          return createResponseWithMergedHeaders(String(result), {
+            status: 200,
+            headers: { "content-type": "text/markdown;charset=utf-8" },
+          });
+        default:
+          // image, stream, any -- must return Response
+          throw new Error(
+            `Response route handler for "${preview.responseType}" must return a Response object, got ${typeof result}`,
+          );
+      }
+    } catch (error) {
+      handlerCtx.callOnError(error, "handler", errorCtx);
+      const isDev = process.env.NODE_ENV !== "production";
+      const status = error instanceof RouterError ? error.status : 500;
+      const message =
+        error instanceof RouterError
+          ? error.message
+          : isDev && error instanceof Error
+            ? error.message
+            : "Internal Server Error";
+      return createResponseWithMergedHeaders(message, {
+        status,
+        headers: { "content-type": "text/plain;charset=utf-8" },
+      });
+    }
+  };
+
+  // Wrap callHandler to append Vary: Accept on content-negotiated responses
+  const callHandlerWithVary = async () => {
+    const response = await callHandler();
+    if (preview.negotiated) {
+      response.headers.append("Vary", "Accept");
+    }
+    return response;
+  };
+
+  // Wrap with route middleware if present
+  const executeHandler = async () => {
+    if (preview.routeMiddleware && preview.routeMiddleware.length > 0) {
+      return executeMiddleware(
+        buildRouteMiddlewareEntries<TEnv>(preview.routeMiddleware),
+        request,
+        env,
+        variables,
+        callHandlerWithVary,
+        createReverseFunction(handlerCtx.getRequiredRouteMap()),
+      );
+    }
+    return callHandlerWithVary();
+  };
+
+  // Resolve cache config from entry tree (same pattern as match-api.ts)
+  if (preview.manifestEntry) {
+    let cacheScope: ReturnType<typeof createCacheScope> = null;
+    for (const entry of traverseBack(preview.manifestEntry)) {
+      if (entry.cache) {
+        cacheScope = createCacheScope(entry.cache, cacheScope);
+      }
+    }
+
+    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 (conditionPassed && store?.getResponse && store?.putResponse) {
+        // Build cache key with response:{type}: prefix to avoid collision
+        // with segment keys and differentiate between response types.
+        // 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) {
+          try {
+            const customKey = await cacheScope.config.key(reqCtx);
+            cacheKey = `response:${customKey}`;
+          } catch {
+            // Fall back to default key on route-level key failure
+          }
+        } else if (store.keyGenerator) {
+          // Priority 2: Store-level keyGenerator (modifies default key)
+          try {
+            cacheKey = await store.keyGenerator(reqCtx, cacheKey);
+          } catch {
+            // Fall back to default key on keyGenerator failure
+          }
+        }
+
+        // Save pre-handler callbacks (registered by app-level middleware
+        // before we reach the cache block) and clear the live array.
+        // createResponseWithMergedHeaders (inside the handler) eagerly
+        // executes any callbacks present in _onResponseCallbacks, so
+        // handler-registered callbacks are baked into the handler's
+        // response and the cached artifact. Pre-handler callbacks are
+        // NOT in the live array during execution, so they are applied
+        // once per serve on every path (hit + miss) below.
+        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;
+        };
+
+        try {
+          const cached = await store.getResponse(cacheKey);
+
+          if (cached && isCacheableStatus(cached.response.status)) {
+            if (!cached.shouldRevalidate) {
+              // Fresh hit
+              return applyPreHandlerCallbacks(cached.response);
+            }
+
+            // Stale hit (SWR) - return cached, revalidate in background
+            reqCtx.waitUntil(async () => {
+              try {
+                // 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.clone(),
+                    cacheScope!.ttl,
+                    cacheScope!.swr,
+                  );
+                }
+              } catch (error) {
+                console.error(`[ResponseCache] Revalidation failed:`, error);
+              }
+            });
+
+            return applyPreHandlerCallbacks(cached.response);
+          }
+        } catch (error) {
+          console.error(`[ResponseCache] Cache lookup failed:`, error);
+        }
+
+        // Cache miss - execute handler and cache the result.
+        // 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 () => {
+            try {
+              await store.putResponse!(
+                cacheKey,
+                response.clone(),
+                cacheScope!.ttl,
+                cacheScope!.swr,
+              );
+            } catch (error) {
+              console.error(`[ResponseCache] Cache write failed:`, error);
+            }
+          });
+        }
+
+        return applyPreHandlerCallbacks(response);
+      }
+    }
+  }
+
+  return executeHandler().then(finalizeResponse);
+}