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

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,10 @@ 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) {
     // Partial render (navigation)
@@ -52,8 +51,6 @@ export async function handleRscRendering<TEnv>(
         return createSimpleRedirectResponse(match.redirect);
       }
 
-      serverTiming = match.serverTiming;
-
       payload = {
         metadata: {
           pathname: url.pathname,
@@ -71,7 +68,8 @@ export async function handleRscRendering<TEnv>(
       };
     } else {
       setRequestContextParams(result.params, result.routeName);
-      serverTiming = result.serverTiming;
+
+      hasInterceptSlots = !!result.slots;
 
       payload = {
         metadata: {
@@ -109,6 +107,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);
@@ -129,8 +128,6 @@ 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.
@@ -163,68 +160,75 @@ 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
-  // navigation or <link rel="prefetch">. Chrome sends Accept: text/html for
-  // prefetch links despite as="fetch", so we cannot rely on Accept alone.
+  // navigation or prefetch fetch(). We cannot rely on Accept alone since some
+  // browsers may send Accept: text/html for non-HTML requests.
   const isRscRequest =
     isPartial ||
     (!request.headers.get("accept")?.includes("text/html") &&
       !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",
+      vary: "accept, X-Rango-State, X-RSC-Router-Client-Path",
     };
-    if (fullTiming) {
-      rscHeaders["Server-Timing"] = fullTiming;
+    // Enable browser HTTP caching for prefetch responses only.
+    // Requires X-Rango-Prefetch header (sent by Link prefetch fetch),
+    // non-intercept context (intercept responses depend on source page),
+    // and a configured cache-control value (false disables caching).
+    const isPrefetch = request.headers.has("X-Rango-Prefetch");
+    if (isPrefetch && isPartial && !hasInterceptSlots) {
+      const cc = ctx.router.prefetchCacheControl;
+      if (cc) {
+        rscHeaders["cache-control"] = cc;
+      }
     }
     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" },
   });
 }

package/src/rsc/runtime-warnings.ts

@@ -0,0 +1,42 @@
+/**
+ * Runtime guardrail warnings (dev-only).
+ *
+ * W3: PE action redirect / Response handling.
+ */
+
+import {
+  createResponseWithMergedHeaders,
+  carryOverRedirectHeaders,
+} from "./helpers.js";
+
+// W3 -----------------------------------------------------------------------
+
+/**
+ * Extract a redirect Response from a thrown or returned value.
+ * Returns a redirect Response to send to the client, or null if the value
+ * is not a redirect Response.
+ */
+export function extractRedirectResponse(value: unknown): Response | null {
+  if (!(value instanceof Response)) return null;
+  const location = value.headers.get("Location");
+  if (value.status >= 300 && value.status < 400 && location) {
+    const redirect = createResponseWithMergedHeaders(null, {
+      status: value.status,
+      headers: { Location: location },
+    });
+    carryOverRedirectHeaders(value, redirect);
+    return redirect;
+  }
+  return null;
+}
+
+/**
+ * Warn when a non-redirect Response is returned from an action during PE.
+ */
+export function warnNonRedirectPeResponse(): void {
+  console.warn(
+    `[rango] Server action returned a non-redirect Response during ` +
+      `progressive enhancement (no-JS) request. The Response will be ` +
+      `ignored — the page will re-render at the current URL instead.`,
+  );
+}

package/src/rsc/server-action.ts

@@ -1,9 +1,18 @@
 /**
  * Server Action Handler
  *
- * Handles server action execution and post-action revalidation.
- * Decodes action arguments, executes the action, handles redirects
- * and error boundaries, then revalidates affected segments.
+ * Handles server action execution and post-action revalidation as two
+ * separate phases:
+ *
+ * 1. executeServerAction — decodes args, runs the action, handles redirects
+ *    and error boundaries. Returns either a final Response (redirect/error)
+ *    or an ActionContinuation for the revalidation phase.
+ *
+ * 2. revalidateAfterAction — takes the continuation, matches affected
+ *    segments, builds the RSC payload, and returns the Flight response.
+ *
+ * The handler (handler.ts) runs the action BEFORE route middleware, then
+ * wraps revalidation inside route middleware — identical to a normal render.
  */
 
 import {
@@ -12,22 +21,62 @@ import {
   getLocationState,
 } from "../server/request-context.js";
 import { resolveLocationStateEntries } from "../browser/react/location-state-shared.js";
+import { appendMetric } from "../router/metrics.js";
 import type { RscPayload } from "./types.js";
 import {
   hasBodyContent,
   createResponseWithMergedHeaders,
   createSimpleRedirectResponse,
+  carryOverRedirectHeaders,
 } from "./helpers.js";
 import type { HandlerContext } from "./handler-context.js";
 
-export async function handleServerAction<TEnv>(
+/**
+ * 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);
+  }
+}
+
+/**
+ * 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.
+ */
+export interface ActionContinuation {
+  returnValue: { ok: boolean; data: unknown };
+  actionStatus: number;
+  temporaryReferences: ReturnType<
+    HandlerContext["createTemporaryReferenceSet"]
+  >;
+  actionContext: {
+    actionId: string;
+    actionUrl: URL;
+    actionResult: unknown;
+    formData?: FormData;
+  };
+}
+
+/**
+ * Phase 1: Execute the server action.
+ *
+ * Decodes arguments, runs the action, handles redirects and error
+ * boundaries. Returns a final Response (redirect, error boundary render)
+ * or an ActionContinuation for the revalidation phase.
+ */
+export async function executeServerAction<TEnv>(
   ctx: HandlerContext<TEnv>,
   request: Request,
   env: TEnv,
   url: URL,
   actionId: string,
   handleStore: ReturnType<typeof requireRequestContext>["_handleStore"],
-): Promise<Response> {
+): Promise<Response | ActionContinuation> {
   const temporaryReferences = ctx.createTemporaryReferenceSet();
 
   // Decode action arguments from request body
@@ -70,15 +119,17 @@ export async function handleServerAction<TEnv>(
       const isRedirect = data.status >= 300 && data.status < 400 && redirectUrl;
       if (isRedirect) {
         const locationState = getLocationState();
+        let redirect: Response;
         if (locationState) {
-          // Redirect with state: needs Flight payload to carry state
-          return ctx.createRedirectFlightResponse(
+          redirect = ctx.createRedirectFlightResponse(
             redirectUrl,
             resolveLocationStateEntries(locationState),
           );
+        } else {
+          redirect = createSimpleRedirectResponse(redirectUrl);
         }
-        // Simple redirect: short-circuit with a header, no RSC serialization
-        return createSimpleRedirectResponse(redirectUrl);
+        carryOverRedirectHeaders(data, redirect);
+        return redirect;
       }
     }
 
@@ -91,28 +142,58 @@ export async function handleServerAction<TEnv>(
         error.status >= 300 && error.status < 400 && redirectUrl;
       if (isRedirect) {
         const locationState = getLocationState();
+        let redirect: Response;
         if (locationState) {
-          return ctx.createRedirectFlightResponse(
+          redirect = ctx.createRedirectFlightResponse(
             redirectUrl,
             resolveLocationStateEntries(locationState),
           );
+        } else {
+          redirect = createSimpleRedirectResponse(redirectUrl);
         }
-        return createSimpleRedirectResponse(redirectUrl);
+        carryOverRedirectHeaders(error, redirect);
+        return redirect;
+      }
+
+      // Non-redirect Response thrown from action — this will be treated
+      // as a regular error and routed to the error boundary. Warn in dev
+      // since the intent is likely a redirect with a missing Location header.
+      if (process.env.NODE_ENV !== "production") {
+        console.warn(
+          `[@rangojs/router] Server action "${actionId}" threw a Response ` +
+            `(status ${error.status}) that is not a redirect. ` +
+            `Non-redirect Responses are treated as errors. ` +
+            `Use \`throw redirect('/path')\` for redirects.`,
+        );
       }
     }
 
     returnValue = { ok: false, data: error };
     actionStatus = 500;
 
-    // Try to render error boundary
-    const errorResult = await ctx.router.matchError(
-      request,
-      { env },
-      error,
-      "route",
-    );
+    // Try to render error boundary.
+    // Report the action error first so it is not lost if matchError throws.
+    let errorResult;
+    try {
+      errorResult = await ctx.router.matchError(
+        request,
+        { env },
+        error,
+        "route",
+      );
+    } catch (matchErr) {
+      // matchError failed — report the original action error as unhandled,
+      // then let the matchError failure propagate.
+      ctx.callOnError(error, "action", {
+        request,
+        url,
+        env,
+        actionId,
+        handledByBoundary: false,
+      });
+      throw matchErr;
+    }
 
-    // Report the action error (handledByBoundary indicates if error boundary will render)
     ctx.callOnError(error, "action", {
       request,
       url,
@@ -138,6 +219,10 @@ export async function handleServerAction<TEnv>(
         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, {
         temporaryReferences,
       });
@@ -149,17 +234,49 @@ export async function handleServerAction<TEnv>(
     }
   }
 
-  // Revalidate after action
+  // Build continuation for the revalidation phase
   const resolvedActionId =
     (loadedAction as { $id?: string; $$id?: string } | undefined)?.$id ??
     (loadedAction as { $$id?: string } | undefined)?.$$id ??
     actionId;
-  const actionContext = {
-    actionId: resolvedActionId,
-    actionUrl: new URL(request.url),
-    actionResult: returnValue.data,
-    formData: actionFormData,
+
+  return {
+    returnValue,
+    actionStatus,
+    temporaryReferences,
+    actionContext: {
+      actionId: resolvedActionId,
+      actionUrl: new URL(request.url),
+      actionResult: returnValue.data,
+      formData: actionFormData,
+    },
   };
+}
+
+/**
+ * Phase 2: Revalidate after action.
+ *
+ * Matches affected segments, builds the RSC payload, and returns the
+ * Flight response. Called inside route middleware (same as a normal render).
+ *
+ * Invariant: the response payload MUST have isPartial: true. The client
+ * (server-action-bridge) rejects non-partial payloads because partial
+ * reconciliation requires matched/diff semantics that full renders don't
+ * provide. Redirects are the only non-partial outcome and are handled via
+ * X-RSC-Redirect headers before Flight deserialization.
+ */
+export async function revalidateAfterAction<TEnv>(
+  ctx: HandlerContext<TEnv>,
+  request: Request,
+  env: TEnv,
+  url: URL,
+  handleStore: ReturnType<typeof requireRequestContext>["_handleStore"],
+  continuation: ActionContinuation,
+): Promise<Response> {
+  const { returnValue, actionStatus, temporaryReferences, actionContext } =
+    continuation;
+  const reqCtx = requireRequestContext();
+  const metricsStore = reqCtx._metricsStore;
 
   const matchResult = await ctx.router.matchPartial(
     request,
@@ -168,7 +285,8 @@ export async function handleServerAction<TEnv>(
   );
 
   if (!matchResult) {
-    // Fall back to full render
+    // matchPartial returns null when the route is a redirect or the request
+    // is missing required headers (previousUrl). Check for redirect first.
     const fullMatch = await ctx.router.match(request, { env });
     setRequestContextParams(fullMatch.params, fullMatch.routeName);
 
@@ -179,43 +297,20 @@ export async function handleServerAction<TEnv>(
       return createSimpleRedirectResponse(fullMatch.redirect);
     }
 
-    const serverTiming = fullMatch.serverTiming;
-
-    const payload: RscPayload = {
-      metadata: {
-        pathname: url.pathname,
-        segments: fullMatch.segments,
-        matched: fullMatch.matched,
-        diff: fullMatch.diff,
-        rootLayout: ctx.router.rootLayout,
-        handles: handleStore.stream(),
-        version: ctx.version,
-      },
-      returnValue,
-    };
-
-    const rscStream = ctx.renderToReadableStream<RscPayload>(payload, {
-      temporaryReferences,
-    });
-
-    const headers: Record<string, string> = {
-      "content-type": "text/x-component;charset=utf-8",
-    };
-    if (serverTiming) {
-      headers["Server-Timing"] = serverTiming;
-    }
-
-    return createResponseWithMergedHeaders(rscStream, {
-      status: actionStatus,
-      headers,
-    });
+    // 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.
+    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).`,
+    );
   }
 
   // Return updated segments
   setRequestContextParams(matchResult.params, matchResult.routeName);
 
-  const serverTiming = matchResult.serverTiming;
-
   const payload: RscPayload = {
     metadata: {
       pathname: url.pathname,
@@ -230,19 +325,24 @@ export async function handleServerAction<TEnv>(
     returnValue,
   };
 
+  attachLocationState(payload);
+
+  const renderStart = performance.now();
   const rscStream = ctx.renderToReadableStream<RscPayload>(payload, {
     temporaryReferences,
   });
-
-  const actionHeaders: Record<string, string> = {
-    "content-type": "text/x-component;charset=utf-8",
-  };
-  if (serverTiming) {
-    actionHeaders["Server-Timing"] = serverTiming;
-  }
+  const rscSerializeDur = performance.now() - renderStart;
+  // This measures synchronous stream creation, not end-to-end stream consumption.
+  appendMetric(metricsStore, "rsc-serialize", renderStart, rscSerializeDur);
+  appendMetric(
+    metricsStore,
+    "render:total",
+    renderStart,
+    performance.now() - renderStart,
+  );
 
   return createResponseWithMergedHeaders(rscStream, {
     status: actionStatus,
-    headers: actionHeaders,
+    headers: { "content-type": "text/x-component;charset=utf-8" },
   });
 }

package/src/rsc/ssr-setup.ts

@@ -0,0 +1,128 @@
+/**
+ * SSR Setup Utilities
+ *
+ * Manages early kickoff and retrieval of SSR module loading and stream mode
+ * resolution. Both operations are request-scoped but independent of route
+ * matching, so they can run in parallel with segment resolution.
+ */
+
+import type { HandlerContext } from "./handler-context.js";
+import type { SSRModule } from "./types.js";
+import type { SSRStreamMode } from "../router/router-options.js";
+import type { MetricsStore } from "../server/context.js";
+import { appendMetric } from "../router/metrics.js";
+import { _getRequestContext } from "../server/request-context.js";
+
+export type SSRSetup = readonly [SSRModule, SSRStreamMode];
+
+/**
+ * Key used to stash the early SSR setup promise on request variables.
+ * Read back via `getSSRSetup`.
+ */
+export const SSR_SETUP_VAR = "__ssrSetup";
+
+/**
+ * Start loading the SSR module and resolving the stream mode in parallel.
+ * When a `getMetricsStore` getter is provided, records individual
+ * `ssr:module-load` and `ssr:stream-mode` metrics (the getter is called
+ * lazily so stores created after kickoff are still captured). Without a
+ * getter the promises run bare — no `.then()` microtasks, no
+ * `performance.now()` calls — keeping the non-debug hot path lean.
+ */
+export function startSSRSetup<TEnv>(
+  ctx: HandlerContext<TEnv>,
+  request: Request,
+  env: TEnv,
+  url: URL,
+  getMetricsStore?: () => MetricsStore | undefined,
+): Promise<SSRSetup> {
+  if (!getMetricsStore) {
+    return Promise.all([
+      ctx.loadSSRModule(),
+      ctx.resolveStreamMode(request, env, url),
+    ]);
+  }
+  const start = performance.now();
+  return Promise.all([
+    ctx.loadSSRModule().then((mod) => {
+      appendMetric(
+        getMetricsStore(),
+        "ssr:module-load",
+        start,
+        performance.now() - start,
+      );
+      return mod;
+    }),
+    ctx.resolveStreamMode(request, env, url).then((mode) => {
+      appendMetric(
+        getMetricsStore(),
+        "ssr:stream-mode",
+        start,
+        performance.now() - start,
+      );
+      return mode;
+    }),
+  ]);
+}
+
+/**
+ * Retrieve the SSR setup result. Returns the early-kicked-off promise
+ * when available (stashed on request variables), otherwise starts a
+ * fresh setup.
+ */
+export function getSSRSetup<TEnv>(
+  ctx: HandlerContext<TEnv>,
+  request: Request,
+  env: TEnv,
+  url: URL,
+  metricsStore: MetricsStore | undefined,
+): Promise<SSRSetup> {
+  const early = _getRequestContext()?.var?.[SSR_SETUP_VAR] as
+    | Promise<SSRSetup>
+    | undefined;
+  if (early) return early;
+  return startSSRSetup(
+    ctx,
+    request,
+    env,
+    url,
+    metricsStore ? () => metricsStore : undefined,
+  );
+}
+
+/**
+ * Classify whether a request may require SSR (HTML rendering).
+ *
+ * Returns false for requests that are definitively RSC-only, loader fetches,
+ * prerender collection, or Accept-based RSC (no text/html). This mirrors
+ * the isRscRequest decision in rsc-rendering.ts.
+ *
+ * Note: response/mime routes are excluded by the caller — this function
+ * runs after previewMatch() classifies the route type.
+ */
+export function mayNeedSSR(request: Request, url: URL): boolean {
+  if (
+    url.searchParams.has("_rsc_partial") ||
+    url.searchParams.has("_rsc_action") ||
+    request.headers.has("rsc-action") ||
+    url.searchParams.has("_rsc_loader") ||
+    url.searchParams.has("__rsc") ||
+    url.searchParams.has("__prerender_collect")
+  ) {
+    return false;
+  }
+
+  // Mirror the Accept-based RSC decision from rsc-rendering.ts:
+  // if Accept is present and does not include text/html (and no __html override),
+  // the response will be RSC, not HTML.
+  const accept = request.headers.get("accept");
+  if (
+    accept &&
+    !accept.includes("text/html") &&
+    !url.searchParams.has("__html")
+  ) {
+    return false;
+  }
+
+  return true;
+}