@rangojs/router 0.0.0-experimental.259 → 0.0.0-experimental.25dbaac3

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

@@ -0,0 +1,360 @@
+/**
+ * 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,
+  mergeStubHeadersAndFinalize,
+} from "./helpers.js";
+import { isWebSocketUpgradeResponse } from "../response-utils.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,
+    originalUrl: reqCtx.originalUrl,
+    pathname: url.pathname,
+    reverse: createReverseFunction(handlerCtx.getRequiredRouteMap()),
+    get: ((keyOrVar: any) => contextGet(variables, keyOrVar)) as any,
+    header: (name: string, value: string) => reqCtx.header(name, value),
+    waitUntil: reqCtx.waitUntil.bind(reqCtx),
+    executionContext: reqCtx.executionContext,
+    _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) => {
+      // 204/205/304 are NOT short-circuited — they're valid for the Response
+      // constructor and must honor ctx.setStatus() overrides. Only upgrade
+      // responses (status 101 / `webSocket` property) bypass reconstruction.
+      if (isWebSocketUpgradeResponse(result)) {
+        return mergeStubHeadersAndFinalize(result);
+      }
+      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 && !isWebSocketUpgradeResponse(response)) {
+      // Skip Vary on upgrade responses: headers are semantically immutable
+      // on some runtimes, and Vary is meaningless for a 101 response.
+      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);
+}

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,38 +51,44 @@ 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,
+          resolvedIds: match.resolvedIds,
           params: match.params,
           isPartial: false,
           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,
+          resolvedIds: result.resolvedIds,
           params: result.params,
           isPartial: true,
           slots: result.slots,
           handles: handleStore.stream(),
           version: ctx.version,
+          prefetchCacheTTL: ctx.router.prefetchCacheTTL,
         },
       };
     }
@@ -109,6 +114,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,22 +135,24 @@ 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,
+          resolvedIds: match.resolvedIds,
           params: match.params,
           isPartial: false,
           rootLayout: ctx.router.rootLayout,
           handles: handleStore.stream(),
           version: ctx.version,
+          prefetchCacheTTL: ctx.router.prefetchCacheTTL,
           themeConfig: ctx.router.themeConfig,
           initialTheme: reqCtx.theme,
         },
@@ -163,68 +171,86 @@ 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 rscStream = ctx.renderToReadableStream<RscPayload>(payload, {
+    onError: (error: unknown) => {
+      ctx.callOnError(error, "rendering", { request, url, env });
+    },
+  });
   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;
+    // Tell the client's prefetch cache to scope this response to its source
+    // URL (instead of the default source-agnostic wildcard). Intercept
+    // responses depend on the source page matching an intercept rule, so
+    // they must not be reused for navigations from other sources.
+    if (hasInterceptSlots) {
+      rscHeaders["x-rsc-prefetch-scope"] = "source";
+    }
+    // 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.`,
+  );
+}