@rangojs/router 0.0.0-experimental.d20dd405 → 0.0.0-experimental.d5d3070a

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

@@ -7,11 +7,12 @@
  */
 
 import { RouterError } from "../errors.js";
-import { requireRequestContext } from "../server/request-context.js";
+import { getRequestContext } 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 { RESPONSE_TYPE_MIME } from "../router/content-negotiation.js";
+import { createCacheScope, resolveCacheTags } from "../cache/cache-scope.js";
+import { serveResponseRouteWithCache } from "./response-cache-serve.js";
 import { executeMiddleware } from "../router/middleware.js";
 import {
   createReverseFunction,
@@ -20,7 +21,7 @@ import {
 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 { createProblemDetails } from "./response-error.js";
 import {
   createResponseWithMergedHeaders,
   finalizeResponse,
@@ -29,6 +30,12 @@ import {
   mergeStubHeadersAndFinalize,
 } from "./helpers.js";
 import { isWebSocketUpgradeResponse } from "../response-utils.js";
+import { stringifyJsonRouteResult } from "./json-route-result.js";
+import {
+  EXTERNAL_REDIRECT_MARKER,
+  isExternalRedirect,
+  markExternalRedirect,
+} from "../redirect-origin.js";
 
 export interface ResponseRouteMatch {
   responseType: string;
@@ -72,7 +79,7 @@ export async function handleResponseRoute<TEnv>(
   }
 
   // Build lightweight context for response handler
-  const reqCtx = requireRequestContext();
+  const reqCtx = getRequestContext();
   const cleanUrl = stripInternalParams(url);
   const responseHandlerCtx = {
     request,
@@ -109,49 +116,31 @@ export async function handleResponseRoute<TEnv>(
       }
       const headers = new Headers();
       result.headers.forEach((value, key) => {
+        // Never copy the reserved external-redirect marker off a handler result.
+        // It is not a trust signal -- the opt-in is the out-of-band brand below
+        // -- and a proxy-style route returning an attacker-controlled upstream
+        // response must not let a forged value ride through to the browser.
+        if (key.toLowerCase() === EXTERNAL_REDIRECT_MARKER) return;
         if (key.toLowerCase() === "set-cookie") {
           headers.append(key, value);
         } else {
           headers.set(key, value);
         }
       });
-      return createResponseWithMergedHeaders(result.body, {
+      const rewrapped = 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" },
-          },
-        );
+      // Transfer the out-of-band external brand only when the handler result is
+      // genuinely branded (a real redirect(url, { external: true })). A proxied
+      // upstream Response is never branded, so an attacker cannot opt a response
+      // route's redirect out of the same-origin guard by injecting the header.
+      if (isExternalRedirect(result)) {
+        markExternalRedirect(rewrapped);
       }
-    }
+      return rewrapped;
+    };
 
-    // Non-JSON response routes: catch errors and return plain Response
     try {
       const result = await (preview.handler as Function)(responseHandlerCtx);
 
@@ -159,38 +148,56 @@ export async function handleResponseRoute<TEnv>(
         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}`,
-          );
+      // Handled before the MIME lookup (json is also a RESPONSE_TYPE_MIME key).
+      if (preview.responseType === "json") {
+        // Runtime guard: the json() return type rejects nested Promises at
+        // compile time, but an `as`-cast or untyped (JS) handler can still slip
+        // one through. stringifyJsonRouteResult throws a clear error instead of
+        // shipping empty data (shared with dispatch() so the two cannot drift).
+        const body = stringifyJsonRouteResult(result);
+        return createResponseWithMergedHeaders(body, {
+          status: 200,
+          headers: { "content-type": "application/json;charset=utf-8" },
+        });
+      }
+
+      // Object.hasOwn (not truthiness) so prototype names like "toString" are not
+      // matched; image/stream/any are absent and fall through to the throw.
+      if (Object.hasOwn(RESPONSE_TYPE_MIME, preview.responseType)) {
+        return createResponseWithMergedHeaders(String(result), {
+          status: 200,
+          headers: {
+            "content-type": `${RESPONSE_TYPE_MIME[preview.responseType]};charset=utf-8`,
+          },
+        });
       }
+
+      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 derivedStatus = error instanceof RouterError ? error.status : 500;
+      // Resolve the effective status the same way createResponseWithMergedHeaders
+      // will (ctx.res.status override) so the problem body's status/title match
+      // the actual HTTP status — e.g. when a handler called ctx.setStatus()
+      // before throwing.
+      const status =
+        reqCtx.res.status !== 200 ? reqCtx.res.status : derivedStatus;
+
+      if (preview.responseType === "json") {
+        return createResponseWithMergedHeaders(
+          JSON.stringify(createProblemDetails(error, status, isDev)),
+          {
+            status,
+            headers: {
+              "content-type": "application/problem+json;charset=utf-8",
+            },
+          },
+        );
+      }
+
       const message =
         error instanceof RouterError
           ? error.message
@@ -230,130 +237,20 @@ export async function handleResponseRoute<TEnv>(
     return callHandlerWithVary();
   };
 
-  // Resolve cache config from entry tree (same pattern as match-api.ts)
+  // Response-route cache: resolved through the shared serve leaf
+  // (rsc/response-cache-serve.ts) so production and the dispatch testing
+  // primitive share ONE owner of the cache contract. Returns undefined when no
+  // cache applies, so we fall through to a plain handler run.
   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);
-      }
-    }
+    const cached = await serveResponseRouteWithCache({
+      reqCtx,
+      manifestEntry: preview.manifestEntry,
+      responseType: preview.responseType,
+      url,
+      executeHandler,
+      deps: { createCacheScope, resolveCacheTags },
+    });
+    if (cached !== undefined) return cached;
   }
 
   return executeHandler().then(finalizeResponse);

package/src/rsc/rsc-rendering.ts

@@ -7,34 +7,94 @@
  */
 
 import {
-  requireRequestContext,
+  getRequestContext,
   setRequestContextParams,
-  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 { observePhase, PHASES } from "../router/instrument.js";
+import { getSSRSetup, isRscRequest } from "./ssr-setup.js";
 import type { RscPayload } from "./types.js";
+import type { MatchResult } from "../types.js";
 import {
   createResponseWithMergedHeaders,
   createSimpleRedirectResponse,
+  attachLocationStateIfPresent,
 } from "./helpers.js";
 import type { HandlerContext } from "./handler-context.js";
 
-export async function handleRscRendering<TEnv>(
+export function handleRscRendering<TEnv>(
   ctx: HandlerContext<TEnv>,
   request: Request,
   env: TEnv,
   url: URL,
   isPartial: boolean,
-  handleStore: ReturnType<typeof requireRequestContext>["_handleStore"],
+  handleStore: ReturnType<typeof getRequestContext>["_handleStore"],
   nonce: string | undefined,
 ): Promise<Response> {
-  const reqCtx = requireRequestContext();
+  // Instrument the whole render phase once through the unified API: it records
+  // the "render:total" perf metric AND opens the "rango.render" span from the
+  // same boundary (match -> serialize -> SSR), so the two surfaces agree.
+  // Loaders kicked off during matching nest under the span; the SSR HTML pass
+  // below opens "rango.ssr" the same way.
+  return observePhase(PHASES.render, () =>
+    handleRscRenderingInner(
+      ctx,
+      request,
+      env,
+      url,
+      isPartial,
+      handleStore,
+      nonce,
+    ),
+  );
+}
+
+async function handleRscRenderingInner<TEnv>(
+  ctx: HandlerContext<TEnv>,
+  request: Request,
+  env: TEnv,
+  url: URL,
+  isPartial: boolean,
+  handleStore: ReturnType<typeof getRequestContext>["_handleStore"],
+  nonce: string | undefined,
+): Promise<Response> {
+  const reqCtx = getRequestContext();
 
   let payload: RscPayload;
   let hasInterceptSlots = false;
 
+  // Shared by the partial-fallback and full-render paths. The partial-success
+  // payload below is intentionally different (omits rootLayout/theme, adds slots).
+  const buildFullPayload = (m: MatchResult): RscPayload => ({
+    metadata: {
+      pathname: url.pathname,
+      routerId: ctx.router.id,
+      basename: ctx.router.basename,
+      segments: m.segments,
+      matched: m.matched,
+      diff: m.diff,
+      resolvedIds: m.resolvedIds,
+      params: m.params,
+      isPartial: false,
+      rootLayout: ctx.router.rootLayout,
+      handles: handleStore.stream(),
+      version: ctx.version,
+      prefetchCacheTTL: ctx.router.prefetchCacheTTL,
+      stateCookieName: ctx.router.resolvedStateCookieName,
+      themeConfig: ctx.router.themeConfig,
+      // Carry warmupEnabled on the initial full-render payload so the client
+      // respects warmup:false from first load. The 404 and PE payloads already
+      // include it; without it here warmup could never be disabled on the
+      // normal full-load path (partial payloads omit it by design).
+      warmupEnabled: ctx.router.warmupEnabled,
+      // Carry strictMode on the initial full-render payload so the browser
+      // entry knows whether to wrap hydration in React.StrictMode. Partial
+      // (navigation) payloads omit it by design; StrictMode is decided once.
+      strictMode: ctx.router.strictMode,
+      initialTheme: reqCtx.theme,
+    },
+  });
+
   if (isPartial) {
     // Partial render (navigation)
     const result = await ctx.router.matchPartial(request, { env });
@@ -51,25 +111,7 @@ export async function handleRscRendering<TEnv>(
         return createSimpleRedirectResponse(match.redirect);
       }
 
-      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,
-        },
-      };
+      payload = buildFullPayload(match);
     } else {
       setRequestContextParams(result.params, result.routeName);
 
@@ -78,6 +120,11 @@ export async function handleRscRendering<TEnv>(
       payload = {
         metadata: {
           pathname: url.pathname,
+          // routerId is serialized on every payload (including within-session
+          // ones) so the frontend can read the current app/router identity. It
+          // always equals the current app's id: a cross-app navigation is
+          // intercepted server-side (X-RSC-Reload) and never delivers a
+          // different-router payload to the client.
           routerId: ctx.router.id,
           segments: result.segments,
           matched: result.matched,
@@ -89,6 +136,7 @@ export async function handleRscRendering<TEnv>(
           handles: handleStore.stream(),
           version: ctx.version,
           prefetchCacheTTL: ctx.router.prefetchCacheTTL,
+          stateCookieName: ctx.router.resolvedStateCookieName,
         },
       };
     }
@@ -135,28 +183,7 @@ export async function handleRscRendering<TEnv>(
         { headers: { "Content-Type": "application/json" } },
       );
     } else {
-      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,
-        },
-      };
+      payload = buildFullPayload(match);
     }
   }
 
@@ -164,15 +191,10 @@ export async function handleRscRendering<TEnv>(
   // SSR (full page) requests ignore location state since there's no history.state
   // to write to on a fresh page load.
   if (isPartial && payload.metadata) {
-    const locationState = getLocationState();
-    if (locationState) {
-      payload.metadata.locationState =
-        resolveLocationStateEntries(locationState);
-    }
+    attachLocationStateIfPresent(payload);
   }
 
   const metricsStore = reqCtx._metricsStore;
-  const renderStart = performance.now();
 
   // Serialize to RSC stream
   const rscSerializeStart = performance.now();
@@ -190,22 +212,16 @@ export async function handleRscRendering<TEnv>(
     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 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");
-
-  if (isRscRequest) {
-    const renderDur = performance.now() - renderStart;
-    appendMetric(metricsStore, "render:total", renderStart, renderDur);
+  if (isRscRequest(request, url, isPartial)) {
+    // render:total is recorded by the observePhase wrapper around this function.
     const rscHeaders: Record<string, string> = {
       "content-type": "text/x-component;charset=utf-8",
       vary: "accept, X-Rango-State, X-RSC-Router-Client-Path",
+      // Router identity, so the client can verify pre-decode (before importing
+      // chunks) that this content payload belongs to its app and refuse a
+      // foreign one (cache/proxy/bug). Control-only reload/redirect responses
+      // are deliberately NOT stamped. See browser/response-adapter.ts.
+      "X-RSC-Router-Id": ctx.router.id,
     };
     // Tell the client's prefetch cache to scope this response to its source
     // URL (instead of the default source-agnostic wildcard). Intercept
@@ -239,16 +255,14 @@ export async function handleRscRendering<TEnv>(
     metricsStore,
   );
 
-  const ssrRenderStart = performance.now();
-  const htmlStream = await ssrModule.renderHTML(rscStream, {
-    nonce,
-    streamMode,
-  });
-  const ssrRenderDur = performance.now() - ssrRenderStart;
-  appendMetric(metricsStore, "ssr-render-html", ssrRenderStart, ssrRenderDur);
-
-  const renderDur = performance.now() - renderStart;
-  appendMetric(metricsStore, "render:total", renderStart, renderDur);
+  // ssr-render-html metric + rango.ssr span from one boundary. render:total is
+  // recorded by the observePhase wrapper around this function.
+  const htmlStream = await observePhase(PHASES.ssr, () =>
+    ssrModule.renderHTML(rscStream, {
+      nonce,
+      streamMode,
+    }),
+  );
 
   return createResponseWithMergedHeaders(htmlStream, {
     headers: { "content-type": "text/html;charset=utf-8" },

package/src/rsc/runtime-warnings.ts

@@ -8,6 +8,7 @@ import {
   createResponseWithMergedHeaders,
   carryOverRedirectHeaders,
 } from "./helpers.js";
+import { isRedirectResponse } from "../response-utils.js";
 
 // W3 -----------------------------------------------------------------------
 
@@ -18,16 +19,14 @@ import {
  */
 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;
+  if (!isRedirectResponse(value)) return null;
+  const location = value.headers.get("Location")!;
+  const redirect = createResponseWithMergedHeaders(null, {
+    status: value.status,
+    headers: { Location: location },
+  });
+  carryOverRedirectHeaders(value, redirect);
+  return redirect;
 }
 
 /**
@@ -40,3 +39,17 @@ export function warnNonRedirectPeResponse(): void {
       `ignored — the page will re-render at the current URL instead.`,
   );
 }
+
+/**
+ * Warn when a non-redirect Response is returned (not thrown) from an action
+ * on the JS (fetch) path. A raw Response cannot be serialized into Flight, so
+ * it is discarded — mirroring the PE path. Use `throw redirect('/path')` for
+ * redirects.
+ */
+export function warnNonRedirectActionResponse(actionId: string): void {
+  console.warn(
+    `[@rangojs/router] Server action "${actionId}" returned a Response ` +
+      `that is not a redirect. Non-redirect Responses cannot be serialized ` +
+      `and are ignored. Use \`throw redirect('/path')\` for redirects.`,
+  );
+}