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

package/src/rsc/helpers.ts

@@ -8,9 +8,49 @@ import {
   _getRequestContext,
   getLocationState,
 } from "../server/request-context.js";
+import type { RequestContext } from "../server/request-context.js";
 import { resolveLocationStateEntries } from "../browser/react/location-state-shared.js";
 import type { MiddlewareEntry, MiddlewareFn } from "../router/middleware.js";
 
+/**
+ * Copy stub headers from the request context onto a target Headers instance:
+ * append Set-Cookie entries, set everything else only if absent. Header
+ * mutation failures are swallowed so the same logic works against Response
+ * headers that may be immutable (e.g. Cloudflare protocol-switch responses).
+ */
+function applyStubHeaders(target: Headers, stub: Headers): void {
+  stub.forEach((value, name) => {
+    try {
+      if (name.toLowerCase() === "set-cookie") {
+        target.append(name, value);
+      } else if (!target.has(name)) {
+        target.set(name, value);
+      }
+    } catch {
+      // Headers immutable — skip.
+    }
+  });
+}
+
+/**
+ * Drain ctx._onResponseCallbacks onto a response. Swapping the array before
+ * iteration prevents re-entrant registrations from double-firing and matches
+ * the contract that each callback runs at most once per request.
+ */
+function drainOnResponseCallbacks(
+  ctx: RequestContext,
+  response: Response,
+): Response {
+  const callbacks = ctx._onResponseCallbacks;
+  if (callbacks.length === 0) return response;
+  ctx._onResponseCallbacks = [];
+  let result = response;
+  for (const callback of callbacks) {
+    result = callback(result) ?? result;
+  }
+  return result;
+}
+
 /**
  * Check if a request body has content to decode
  */
@@ -39,40 +79,23 @@ export function createResponseWithMergedHeaders(
     return new Response(body, init);
   }
 
-  // Merge headers from stub response into the new response.
-  // Delete Set-Cookie from the stub after consuming so that downstream
-  // merge points (e.g. executeMiddleware) do not duplicate them.
+  // Delete Set-Cookie from the stub after consuming so downstream merge
+  // points (e.g. executeMiddleware) don't duplicate them.
   const mergedHeaders = new Headers(init.headers);
-  ctx.res.headers.forEach((value, name) => {
-    if (name.toLowerCase() === "set-cookie") {
-      mergedHeaders.append(name, value);
-    } else if (!mergedHeaders.has(name)) {
-      // Only set if not already present in init.headers
-      mergedHeaders.set(name, value);
-    }
-  });
+  applyStubHeaders(mergedHeaders, ctx.res.headers);
   ctx.res.headers.delete("set-cookie");
 
-  // Use ctx.res.status if it was set (e.g., 404 for notFound, 500 for error)
-  // Otherwise use the status from init
+  // ctx.res.status overrides init.status when explicitly set (e.g. 404 for
+  // notFound, 500 for error). Default ctx.res.status is 200.
   const status = ctx.res.status !== 200 ? ctx.res.status : init.status;
 
-  let response = new Response(body, {
+  const response = new Response(body, {
     ...init,
     status,
     headers: mergedHeaders,
   });
 
-  // Run onResponse callbacks - each can inspect/modify the response.
-  // Drain the array so that downstream callers (e.g. finalizeResponse)
-  // do not re-execute the same callbacks on this response.
-  const callbacks = ctx._onResponseCallbacks;
-  ctx._onResponseCallbacks = [];
-  for (const callback of callbacks) {
-    response = callback(response) ?? response;
-  }
-
-  return response;
+  return drainOnResponseCallbacks(ctx, response);
 }
 
 /**
@@ -175,24 +198,29 @@ export function buildRouteMiddlewareEntries<TEnv>(
 }
 
 /**
- * Run onResponse callbacks on an existing Response.
- *
- * Used for code paths that bypass createResponseWithMergedHeaders(), such as
- * middleware short-circuits where the Response is already constructed but
- * ctx.onResponse() callbacks still need to fire.
+ * Merge stub headers from the request context onto an existing Response in
+ * place, then drain onResponse callbacks. Used when a Response cannot flow
+ * through `new Response()` — status 101 is outside the constructor's
+ * 200-599 range, and the Cloudflare-specific `webSocket` property would be
+ * lost on reconstruction.
  */
-export function finalizeResponse(response: Response): Response {
+export function mergeStubHeadersAndFinalize(response: Response): Response {
   const ctx = _getRequestContext();
-  if (!ctx || ctx._onResponseCallbacks.length === 0) {
-    return response;
-  }
+  if (!ctx) return response;
 
-  // Drain the array so callbacks run at most once per request.
-  const callbacks = ctx._onResponseCallbacks;
-  ctx._onResponseCallbacks = [];
-  let result = response;
-  for (const callback of callbacks) {
-    result = callback(result) ?? result;
-  }
-  return result;
+  applyStubHeaders(response.headers, ctx.res.headers);
+  ctx.res.headers.delete("set-cookie");
+
+  return drainOnResponseCallbacks(ctx, response);
+}
+
+/**
+ * Run onResponse callbacks on an existing Response. Used by code paths that
+ * bypass createResponseWithMergedHeaders (e.g. middleware short-circuits)
+ * but still need ctx.onResponse() callbacks to fire.
+ */
+export function finalizeResponse(response: Response): Response {
+  const ctx = _getRequestContext();
+  if (!ctx) return response;
+  return drainOnResponseCallbacks(ctx, response);
 }

package/src/rsc/loader-fetch.ts

@@ -168,8 +168,19 @@ export async function handleLoaderFetch<TEnv>(
             loaderResult: unknown;
           }
           const loaderPayload: LoaderPayload = { loaderResult: result };
-          const rscStream =
-            ctx.renderToReadableStream<LoaderPayload>(loaderPayload);
+          const rscStream = ctx.renderToReadableStream<LoaderPayload>(
+            loaderPayload,
+            {
+              onError: (error: unknown) => {
+                ctx.callOnError(error, "rendering", {
+                  request,
+                  url,
+                  env,
+                  loaderName: loaderId,
+                });
+              },
+            },
+          );
 
           return createResponseWithMergedHeaders(rscStream, {
             headers: { "content-type": "text/x-component;charset=utf-8" },
@@ -199,7 +210,16 @@ export async function handleLoaderFetch<TEnv>(
         name: err.name,
       },
     };
-    const rscStream = ctx.renderToReadableStream(errorPayload);
+    const rscStream = ctx.renderToReadableStream(errorPayload, {
+      onError: (error: unknown) => {
+        ctx.callOnError(error, "rendering", {
+          request,
+          url,
+          env,
+          loaderName: loaderId,
+        });
+      },
+    });
 
     return createResponseWithMergedHeaders(rscStream, {
       status: 500,

package/src/rsc/manifest-init.ts

@@ -31,7 +31,11 @@ export async function buildRouterTrieFromUrlpatterns(
 ): Promise<void> {
   const { generateManifestFull } =
     await import("../build/generate-manifest.js");
-  const generated = generateManifestFull(router.urlpatterns);
+  const generated = generateManifestFull(
+    router.urlpatterns,
+    undefined,
+    router.basename ? { urlPrefix: router.basename } : undefined,
+  );
   if (
     generated._routeAncestry &&
     Object.keys(generated._routeAncestry).length > 0

package/src/rsc/progressive-enhancement.ts

@@ -10,6 +10,7 @@ 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";
@@ -242,9 +243,13 @@ export async function handleProgressiveEnhancement<TEnv>(
     const payload: RscPayload = {
       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(),
@@ -256,11 +261,21 @@ export async function handleProgressiveEnhancement<TEnv>(
       formState: actionResult,
     };
 
-    const rscStream = ctx.renderToReadableStream<RscPayload>(payload);
-    const [ssrModule, streamMode] = await Promise.all([
-      ctx.loadSSRModule(),
-      ctx.resolveStreamMode(request, env, url),
-    ]);
+    const rscStream = ctx.renderToReadableStream<RscPayload>(payload, {
+      onError: (error: unknown) => {
+        ctx.callOnError(error, "rendering", { request, url, env });
+      },
+    });
+    // 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,
@@ -335,9 +350,13 @@ async function renderPeErrorBoundary<TEnv>(
   const payload: RscPayload = {
     metadata: {
       pathname: url.pathname,
+      routerId: ctx.router.id,
+      basename: ctx.router.basename,
       segments: errorResult.segments,
       matched: errorResult.matched,
       diff: errorResult.diff,
+      resolvedIds: errorResult.resolvedIds,
+      params: errorResult.params,
       isPartial: false,
       isError: true,
       rootLayout: ctx.router.rootLayout,
@@ -349,11 +368,21 @@ async function renderPeErrorBoundary<TEnv>(
     },
   };
 
-  const rscStream = ctx.renderToReadableStream<RscPayload>(payload);
-  const [ssrModule, streamMode] = await Promise.all([
-    ctx.loadSSRModule(),
-    ctx.resolveStreamMode(request, env, url),
-  ]);
+  const rscStream = ctx.renderToReadableStream<RscPayload>(payload, {
+    onError: (error: unknown) => {
+      ctx.callOnError(error, "rendering", { request, url, env });
+    },
+  });
+  // 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, {
     nonce,
     streamMode,

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

@@ -26,7 +26,9 @@ import {
   finalizeResponse,
   isCacheableStatus,
   buildRouteMiddlewareEntries,
+  mergeStubHeadersAndFinalize,
 } from "./helpers.js";
+import { isWebSocketUpgradeResponse } from "../response-utils.js";
 
 export interface ResponseRouteMatch {
   responseType: string;
@@ -78,10 +80,13 @@ export async function handleResponseRoute<TEnv>(
     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
@@ -96,6 +101,12 @@ export async function handleResponseRoute<TEnv>(
     // 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") {
@@ -196,7 +207,9 @@ export async function handleResponseRoute<TEnv>(
   // Wrap callHandler to append Vary: Accept on content-negotiated responses
   const callHandlerWithVary = async () => {
     const response = await callHandler();
-    if (preview.negotiated) {
+    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;

package/src/rsc/rsc-rendering.ts

@@ -12,7 +12,8 @@ import {
   getLocationState,
 } from "../server/request-context.js";
 import { resolveLocationStateEntries } from "../browser/react/location-state-shared.js";
-import { appendMetric, buildMetricsTiming } from "../router/metrics.js";
+import { appendMetric } from "../router/metrics.js";
+import { getSSRSetup } from "./ssr-setup.js";
 import type { RscPayload } from "./types.js";
 import {
   createResponseWithMergedHeaders,
@@ -29,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) {
@@ -54,39 +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,
         },
       };
     }
@@ -133,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,
         },
@@ -172,7 +176,11 @@ export async function handleRscRendering<TEnv>(
 
   // 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(
@@ -192,26 +200,20 @@ 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 (isRscRequest) {
     const renderDur = performance.now() - renderStart;
     appendMetric(metricsStore, "render:total", renderStart, renderDur);
-    const metricsTiming = buildMetricsTiming(
-      request.method,
-      url.pathname,
-      metricsStore,
-      serverTiming,
-    );
-    if (metricsTiming) {
-      timingParts.push(metricsTiming);
-    }
-    const fullTiming = timingParts.join(", ");
     const rscHeaders: Record<string, string> = {
       "content-type": "text/x-component;charset=utf-8",
       vary: "accept, X-Rango-State, X-RSC-Router-Client-Path",
     };
+    // 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),
@@ -223,22 +225,19 @@ 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 ssrSetupStart = performance.now();
-  const [ssrModule, streamMode] = await Promise.all([
-    ctx.loadSSRModule(),
-    ctx.resolveStreamMode(request, env, url),
-  ]);
-  const ssrSetupDur = performance.now() - ssrSetupStart;
-  appendMetric(metricsStore, "ssr-setup", ssrSetupStart, ssrSetupDur);
+  // 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, {
@@ -248,33 +247,10 @@ export async function handleRscRendering<TEnv>(
   const ssrRenderDur = performance.now() - ssrRenderStart;
   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 renderDur = performance.now() - renderStart;
   appendMetric(metricsStore, "render:total", renderStart, renderDur);
-  const metricsTiming = buildMetricsTiming(
-    request.method,
-    url.pathname,
-    metricsStore,
-    serverTiming,
-  );
-  if (metricsTiming) {
-    timingParts.push(metricsTiming);
-  }
-
-  const fullTiming = timingParts.join(", ");
-  const htmlHeaders: Record<string, string> = {
-    "content-type": "text/html;charset=utf-8",
-  };
-  if (fullTiming) {
-    htmlHeaders["Server-Timing"] = fullTiming;
-  }
 
   return createResponseWithMergedHeaders(htmlStream, {
-    headers: htmlHeaders,
+    headers: { "content-type": "text/html;charset=utf-8" },
   });
 }

package/src/rsc/server-action.ts

@@ -21,7 +21,7 @@ import {
   getLocationState,
 } from "../server/request-context.js";
 import { resolveLocationStateEntries } from "../browser/react/location-state-shared.js";
-import { appendMetric, buildMetricsTiming } from "../router/metrics.js";
+import { appendMetric } from "../router/metrics.js";
 import type { RscPayload } from "./types.js";
 import {
   hasBodyContent,
@@ -208,10 +208,13 @@ export async function executeServerAction<TEnv>(
       const payload: RscPayload = {
         metadata: {
           pathname: url.pathname,
+          routerId: ctx.router.id,
           segments: errorResult.segments,
           isPartial: true,
           matched: errorResult.matched,
           diff: errorResult.diff,
+          resolvedIds: errorResult.resolvedIds,
+          params: errorResult.params,
           isError: true,
           handles: handleStore.stream(),
           version: ctx.version,
@@ -225,6 +228,9 @@ export async function executeServerAction<TEnv>(
 
       const rscStream = ctx.renderToReadableStream<RscPayload>(payload, {
         temporaryReferences,
+        onError: (error: unknown) => {
+          ctx.callOnError(error, "rendering", { request, url, env });
+        },
       });
 
       return createResponseWithMergedHeaders(rscStream, {
@@ -311,15 +317,16 @@ export async function revalidateAfterAction<TEnv>(
   // Return updated segments
   setRequestContextParams(matchResult.params, matchResult.routeName);
 
-  const serverTiming = matchResult.serverTiming;
-
   const payload: RscPayload = {
     metadata: {
       pathname: url.pathname,
+      routerId: ctx.router.id,
       segments: matchResult.segments,
       isPartial: true,
       matched: matchResult.matched,
       diff: matchResult.diff,
+      resolvedIds: matchResult.resolvedIds,
+      params: matchResult.params,
       slots: matchResult.slots,
       handles: handleStore.stream(),
       version: ctx.version,
@@ -332,6 +339,9 @@ export async function revalidateAfterAction<TEnv>(
   const renderStart = performance.now();
   const rscStream = ctx.renderToReadableStream<RscPayload>(payload, {
     temporaryReferences,
+    onError: (error: unknown) => {
+      ctx.callOnError(error, "rendering", { request, url, env });
+    },
   });
   const rscSerializeDur = performance.now() - renderStart;
   // This measures synchronous stream creation, not end-to-end stream consumption.
@@ -343,21 +353,8 @@ export async function revalidateAfterAction<TEnv>(
     performance.now() - renderStart,
   );
 
-  const actionHeaders: Record<string, string> = {
-    "content-type": "text/x-component;charset=utf-8",
-  };
-  const metricsTiming = buildMetricsTiming(
-    request.method,
-    url.pathname,
-    metricsStore,
-    serverTiming,
-  );
-  if (metricsTiming) {
-    actionHeaders["Server-Timing"] = metricsTiming;
-  }
-
   return createResponseWithMergedHeaders(rscStream, {
     status: actionStatus,
-    headers: actionHeaders,
+    headers: { "content-type": "text/x-component;charset=utf-8" },
   });
 }