@rangojs/router 0.0.0-experimental.d7eeaa75 → 0.0.0-experimental.d98a8e9d

package/src/rsc/helpers.ts

@@ -8,8 +8,67 @@ 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 { isRedirectResponse } from "../response-utils.js";
 import type { MiddlewareEntry, MiddlewareFn } from "../router/middleware.js";
+import { formatCacheSignalHeader } from "../router/telemetry.js";
+
+/**
+ * DEVELOPMENT/TEST ONLY. When the debug cache signal gate is on,
+ * match/matchPartial populate ctx._cacheSignal. Emit it as the X-Rango-Cache
+ * header. When the gate is off, ctx._cacheSignal is undefined and NOTHING is
+ * attached — output is byte-identical to the default. Header mutation failures
+ * are swallowed so immutable Response headers (e.g. protocol-switch) are safe.
+ */
+function applyCacheSignalHeader(target: Headers, ctx: RequestContext): void {
+  const signal = ctx._cacheSignal;
+  if (!signal || signal.length === 0) return;
+  try {
+    target.set("X-Rango-Cache", formatCacheSignalHeader(signal));
+  } catch {
+    // Headers immutable — skip.
+  }
+}
+
+/**
+ * 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 +98,24 @@ 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");
+  applyCacheSignalHeader(mergedHeaders, ctx);
 
-  // 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);
 }
 
 /**
@@ -122,10 +165,10 @@ export function interceptRedirectForPartial(
     locationState?: Record<string, unknown>,
   ) => Response,
 ): Response | null {
-  const redirectUrl = response.headers.get("Location");
-  if (!(response.status >= 300 && response.status < 400 && redirectUrl)) {
+  if (!isRedirectResponse(response)) {
     return null;
   }
+  const redirectUrl = response.headers.get("Location")!;
   const locationState = getLocationState();
   let intercepted: Response;
   if (locationState) {
@@ -175,24 +218,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/index.ts

@@ -1,5 +1,5 @@
 /**
- * RSC Router - RSC Entry Point
+ * Rango - RSC Entry Point
  *
  * This module provides RSC utilities for server-side rendering,
  * server actions, loader fetching, and progressive enhancement.

package/src/rsc/manifest-init.ts

@@ -13,6 +13,7 @@ import {
   setRouteTrie,
   setRouterManifest,
   setRouterTrie,
+  setRouterPrecomputedEntries,
 } from "../route-map-builder.js";
 
 /**
@@ -36,47 +37,13 @@ export async function buildRouterTrieFromUrlpatterns(
     undefined,
     router.basename ? { urlPrefix: router.basename } : undefined,
   );
-  if (
-    generated._routeAncestry &&
-    Object.keys(generated._routeAncestry).length > 0
-  ) {
-    const { buildRouteTrie } = await import("../build/route-trie.js");
-    // Map each route to its include() staticPrefix so the trie
-    // returns the correct sp for lazy entry lookup in findMatch.
-    const routeToStaticPrefix: Record<string, string> = {};
-    for (const name of Object.keys(generated.routeManifest)) {
-      routeToStaticPrefix[name] = "";
-    }
-    // Override with prefix from include() entries so the trie
-    // returns the correct sp for lazy entry lookup in findMatch.
-    // Walk recursively to include routes in nested includes.
-    if (generated.prefixTree) {
-      const visitPrefixNode = (node: any): void => {
-        const sp = node.staticPrefix || "";
-        for (const route of node.routes || []) {
-          routeToStaticPrefix[route] = sp;
-        }
-        for (const child of Object.values(node.children || {})) {
-          visitPrefixNode(child);
-        }
-      };
-      for (const node of Object.values(generated.prefixTree)) {
-        visitPrefixNode(node);
-      }
-    }
-    const trie = buildRouteTrie(
-      generated.routeManifest,
-      generated._routeAncestry,
-      routeToStaticPrefix,
-      generated.routeTrailingSlash,
-      generated.prerenderRoutes
-        ? new Set(generated.prerenderRoutes)
-        : undefined,
-      generated.passthroughRoutes
-        ? new Set(generated.passthroughRoutes)
-        : undefined,
-      generated.responseTypeRoutes,
-    );
+  // Build the trie through the SAME shared helper the production discovery uses
+  // (discover-routers.ts), so the dev runtime-rebuilt trie and the prod
+  // serialized trie cannot drift. buildPerRouterTrie returns null when there
+  // are no routes.
+  const { buildPerRouterTrie } = await import("../build/route-trie.js");
+  const trie = buildPerRouterTrie(generated);
+  if (trie) {
     setRouterTrie(router.id, trie);
     // Set global trie only if not already set by another router
     if (!getRouteTrie()) {
@@ -84,6 +51,26 @@ export async function buildRouterTrieFromUrlpatterns(
     }
   }
   setRouterManifest(router.id, generated.routeManifest);
+
+  // Match the production discovery path: precompute leaf-include entries so the
+  // match-time shortcut in evaluateLazyEntry applies in dev/Cloudflare too.
+  // Without this, dev re-runs each matched leaf include's handler at match time
+  // (evaluateLazyEntry) AND again at render time (loadManifest); with it, the
+  // match-time run is skipped and the handler runs once per first request.
+  // Identical route ownership to the handler path (the shortcut is guarded by
+  // the same prefixIsShared and #506 checks production uses).
+  const { flattenLeafEntries } = await import("../build/prefix-tree-utils.js");
+  const precomputed: Array<{
+    staticPrefix: string;
+    routes: Record<string, string>;
+  }> = [];
+  flattenLeafEntries(
+    generated.prefixTree,
+    generated.routeManifest,
+    precomputed,
+  );
+  setRouterPrecomputedEntries(router.id, precomputed);
+
   // Merge into global manifest (needed for reverse/href across routers)
   const existing = hasCachedManifest() ? getGlobalRouteMap() : {};
   setCachedManifest({ ...existing, ...generated.routeManifest });

package/src/rsc/origin-guard.ts

@@ -9,11 +9,29 @@
  * navigations, bookmarks, and non-browser clients don't send Origin.
  */
 
+import type { RequestPlan } from "../router/request-classification.js";
+
 /**
  * Request phase that triggered the origin check.
  */
 export type OriginCheckPhase = "action" | "loader" | "pe-form";
 
+// Exhaustive over RequestPlan modes so a new mode must be classified here (the
+// security gate) instead of silently falling through to no origin check.
+export const ORIGIN_CHECK_PHASE_BY_MODE: Record<
+  RequestPlan["mode"],
+  OriginCheckPhase | null
+> = {
+  action: "action",
+  loader: "loader",
+  "pe-render": "pe-form",
+  "full-render": null,
+  "partial-render": null,
+  response: null,
+  redirect: null,
+  "version-mismatch": null,
+};
+
 /**
  * Context passed to the originCheck callback.
  */
@@ -116,14 +134,15 @@ export async function checkRequestOrigin<TEnv = any>(
   // Disabled by explicit opt-out
   if (config === false) return null;
 
-  // Default: built-in validation (config === true or undefined)
-  if (config === true || config === undefined) {
-    const allowed = defaultOriginCheck(request, url);
-    if (allowed) return null;
-    return createForbiddenResponse(request);
-  }
+  // Default (true/undefined) becomes a callback returning boolean, so the
+  // Response|true|reject resolution below is written once.
+  const check: (
+    ctx: OriginCheckContext<TEnv>,
+  ) => boolean | Response | Promise<boolean | Response> =
+    config === true || config === undefined
+      ? () => defaultOriginCheck(request, url)
+      : config;
 
-  // Custom function — build context and call
   const ctx: OriginCheckContext<TEnv> = {
     request,
     url,
@@ -133,9 +152,8 @@ export async function checkRequestOrigin<TEnv = any>(
     defaultCheck: () => defaultOriginCheck(request, url),
   };
 
-  const result = await config(ctx);
+  const result = await check(ctx);
 
   if (result instanceof Response) return result;
-  if (result === true) return null;
-  return createForbiddenResponse(request);
+  return result === true ? null : createForbiddenResponse(request);
 }

package/src/rsc/progressive-enhancement.ts

@@ -248,6 +248,8 @@ export async function handleProgressiveEnhancement<TEnv>(
         segments: match.segments,
         matched: match.matched,
         diff: match.diff,
+        resolvedIds: match.resolvedIds,
+        params: match.params,
         isPartial: false,
         rootLayout: ctx.router.rootLayout,
         handles: handleStore.stream(),
@@ -353,6 +355,8 @@ async function renderPeErrorBoundary<TEnv>(
       segments: errorResult.segments,
       matched: errorResult.matched,
       diff: errorResult.diff,
+      resolvedIds: errorResult.resolvedIds,
+      params: errorResult.params,
       isPartial: false,
       isError: true,
       rootLayout: ctx.router.rootLayout,

package/src/rsc/response-error.ts

@@ -1,37 +1,104 @@
 /**
- * Response Error Payload Builder
+ * Problem Details (RFC 9457) Builder
  *
- * Builds a ResponseError object from a caught error, controlling
- * what information is exposed based on error type and environment.
+ * Builds a problem+json error body from a caught error, controlling what
+ * information is exposed based on error type and environment.
  */
 
 import { RouterError } from "../errors.js";
-import type { ResponseError } from "../urls.js";
+import type { ProblemDetails } from "../urls.js";
 
 /**
- * Build a ResponseError payload from a caught error.
- * RouterError messages are always exposed (developer-crafted).
+ * HTTP reason phrases for the problem `title` member. Inlined because the
+ * router targets edge/worker runtimes without node's `http.STATUS_CODES`;
+ * covers the full standard 4xx/5xx range, with a generic fallback for any
+ * non-standard status a handler might set.
+ */
+const STATUS_PHRASES: Record<number, string> = {
+  400: "Bad Request",
+  401: "Unauthorized",
+  402: "Payment Required",
+  403: "Forbidden",
+  404: "Not Found",
+  405: "Method Not Allowed",
+  406: "Not Acceptable",
+  407: "Proxy Authentication Required",
+  408: "Request Timeout",
+  409: "Conflict",
+  410: "Gone",
+  411: "Length Required",
+  412: "Precondition Failed",
+  413: "Payload Too Large",
+  414: "URI Too Long",
+  415: "Unsupported Media Type",
+  416: "Range Not Satisfiable",
+  417: "Expectation Failed",
+  418: "I'm a Teapot",
+  421: "Misdirected Request",
+  422: "Unprocessable Entity",
+  423: "Locked",
+  424: "Failed Dependency",
+  425: "Too Early",
+  426: "Upgrade Required",
+  428: "Precondition Required",
+  429: "Too Many Requests",
+  431: "Request Header Fields Too Large",
+  451: "Unavailable For Legal Reasons",
+  500: "Internal Server Error",
+  501: "Not Implemented",
+  502: "Bad Gateway",
+  503: "Service Unavailable",
+  504: "Gateway Timeout",
+  505: "HTTP Version Not Supported",
+  506: "Variant Also Negotiates",
+  507: "Insufficient Storage",
+  508: "Loop Detected",
+  510: "Not Extended",
+  511: "Network Authentication Required",
+};
+
+function statusPhrase(status: number): string {
+  return STATUS_PHRASES[status] ?? "Error";
+}
+
+/**
+ * Build an RFC 9457 problem+json body from a caught error.
+ * RouterError messages/codes are always exposed (developer-crafted).
  * Standard Error messages are hidden in production.
+ *
+ * The `type` member is omitted in this phase: per RFC 9457 an absent `type` is
+ * treated as `"about:blank"` (no semantics beyond the HTTP status), so emitting
+ * it adds nothing. Per-route problem-type URIs arrive with the declared-errors
+ * map later. `code` is always present so consumers can branch on it
+ * (`"INTERNAL"` for non-RouterError failures).
  */
-export function createResponseErrorPayload(
+export function createProblemDetails(
   error: unknown,
+  status: number,
   isDev: boolean,
-): ResponseError {
+): ProblemDetails {
   if (error instanceof RouterError) {
     return {
-      message: error.message,
+      title: statusPhrase(status),
+      status,
+      detail: error.message,
       code: error.code,
-      ...(error.type ? { type: error.type } : {}),
       ...(isDev && error.stack ? { stack: error.stack } : {}),
     };
   }
   if (error instanceof Error) {
     return {
-      message: isDev ? error.message : "Internal Server Error",
+      title: statusPhrase(status),
+      status,
+      detail: isDev ? error.message : "Internal Server Error",
+      code: "INTERNAL",
       ...(isDev && error.stack ? { stack: error.stack } : {}),
     };
   }
   return {
-    message: isDev ? String(error) : "Internal Server Error",
+    title: statusPhrase(status),
+    status,
+    detail: isDev ? String(error) : "Internal Server Error",
+    code: "INTERNAL",
   };
 }

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

@@ -11,6 +11,7 @@ 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 { RESPONSE_TYPE_MIME } from "../router/content-negotiation.js";
 import { createCacheScope } from "../cache/cache-scope.js";
 import { executeMiddleware } from "../router/middleware.js";
 import {
@@ -20,13 +21,15 @@ 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,
   isCacheableStatus,
   buildRouteMiddlewareEntries,
+  mergeStubHeadersAndFinalize,
 } from "./helpers.js";
+import { isWebSocketUpgradeResponse } from "../response-utils.js";
 
 export interface ResponseRouteMatch {
   responseType: string;
@@ -78,10 +81,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 +102,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") {
@@ -110,37 +122,6 @@ export async function handleResponseRoute<TEnv>(
       });
     };
 
-    // 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);
 
@@ -148,38 +129,51 @@ 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") {
+        return createResponseWithMergedHeaders(JSON.stringify(result), {
+          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
@@ -196,7 +190,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;