@rangojs/router 0.0.0-experimental.18 → 0.0.0-experimental.19

package/src/router/router-context.ts

@@ -18,6 +18,7 @@ import type {
   ShouldRevalidateFn,
 } from "../types.js";
 import type { RouteMatchResult } from "./pattern-matching.js";
+import type { TelemetrySink } from "./telemetry.js";
 
 /**
  * Revalidation context passed to segment resolution
@@ -79,6 +80,7 @@ export interface RouterContext<TEnv = any> {
     routeMap?: Record<string, string>,
     routeName?: string,
     responseType?: string,
+    isPassthroughRoute?: boolean,
   ) => HandlerContext<any, TEnv>;
 
   // Loader setup
@@ -181,6 +183,12 @@ export interface RouterContext<TEnv = any> {
     context: HandlerContext<any, TEnv>;
     actionContext?: any;
     stale?: boolean;
+    traceSource?:
+      | "segment-resolution"
+      | "cache-hit"
+      | "loader"
+      | "parallel"
+      | "orphan-layout";
   }) => Promise<boolean>;
 
   // Request context
@@ -234,6 +242,7 @@ export interface RouterContext<TEnv = any> {
     nextUrl: URL,
     routeKey: string,
     actionContext?: any,
+    stale?: boolean,
   ) => Promise<{ segments: ResolvedSegment[]; matchedIds: string[] }>;
 
   // Entry revalidation map
@@ -241,6 +250,12 @@ export interface RouterContext<TEnv = any> {
     entries: EntryData[],
   ) => Map<string, { revalidate: ShouldRevalidateFn[] }>;
 
+  // Telemetry sink (optional, no-op when undefined)
+  telemetry?: TelemetrySink;
+
+  // Request ID for telemetry span correlation (set per-request in match handlers)
+  requestId?: string;
+
   // Intercept loaders only (for cache hit + intercept scenarios)
   resolveInterceptLoadersOnly?: (
     intercept: InterceptEntry,

package/src/router/router-interfaces.ts

@@ -14,6 +14,7 @@ import type { MiddlewareEntry, MiddlewareFn } from "./middleware.js";
 import { RSC_ROUTER_BRAND } from "./router-registry.js";
 import type { RSCRouterOptions, RootLayoutProps } from "./router-options.js";
 import type { DefaultVars } from "../types/global-namespace.js";
+import type { ResolvedTimeouts, OnTimeoutCallback } from "./timeout.js";
 
 /**
  * Options passed to router.fetch(), router.match(), and other request entrypoints.
@@ -246,6 +247,15 @@ export interface RSCRouterInternal<
    */
   readonly themeConfig: import("../theme/types.js").ResolvedThemeConfig | null;
 
+  /**
+   * Cache profiles for "use cache" per-request resolution.
+   * Always includes at least the "default" profile.
+   */
+  readonly cacheProfiles: Record<
+    string,
+    import("../cache/profile-registry.js").CacheProfile
+  >;
+
   /**
    * Cache-Control header value for prefetch responses.
    * False means no browser caching of prefetch responses.
@@ -265,6 +275,16 @@ export interface RSCRouterInternal<
    */
   readonly allowDebugManifest: boolean;
 
+  /**
+   * Resolved timeout configuration (merged from shorthand + structured).
+   */
+  readonly timeouts: ResolvedTimeouts;
+
+  /**
+   * Custom timeout response handler.
+   */
+  readonly onTimeout?: OnTimeoutCallback<TEnv>;
+
   /**
    * App-level middleware entries
    * These wrap the entire request/response cycle
@@ -286,6 +306,18 @@ export interface RSCRouterInternal<
    */
   readonly urlpatterns?: UrlPatterns<TEnv, any>;
 
+  /**
+   * SSR configuration. resolveStreaming determines stream vs allReady
+   * per HTML request (undefined = always stream).
+   */
+  readonly ssr?: import("./router-options.js").SSROptions<TEnv>;
+
+  /**
+   * Cross-origin request protection configuration.
+   * Default: true (enabled).
+   */
+  readonly originCheck: import("../rsc/origin-guard.js").OriginCheckConfig<TEnv>;
+
   /**
    * Source file path where createRouter() was called.
    * Set via Error.stack parsing at construction time.
@@ -307,6 +339,7 @@ export interface RSCRouterInternal<
     pathname: string,
     params: Record<string, string>,
     buildVars?: Record<string, any>,
+    isPassthroughRoute?: boolean,
   ): Promise<{
     segments: SerializedSegmentData[];
     handles: Record<string, SegmentHandleData>;
@@ -314,6 +347,7 @@ export interface RSCRouterInternal<
     params: Record<string, string>;
     interceptSegments?: SerializedSegmentData[];
     interceptHandles?: Record<string, SegmentHandleData>;
+    passthrough?: true;
   } | null>;
 
   /**

package/src/router/router-options.ts

@@ -9,6 +9,58 @@ import type { NonceProvider } from "../rsc/types.js";
 import type { ExecutionContext } from "../server/request-context.js";
 import type { UrlPatterns } from "../urls.js";
 import type { NamedRouteEntry } from "./content-negotiation.js";
+import type { TelemetrySink } from "./telemetry.js";
+import type { RouterTimeouts, OnTimeoutCallback } from "./timeout.js";
+
+/**
+ * SSR stream mode returned by resolveStreaming.
+ *
+ * - `"stream"` — start flushing HTML as soon as the shell is ready
+ *   (default React SSR behavior via `renderToReadableStream`).
+ * - `"allReady"` — wait for every Suspense boundary to resolve before
+ *   sending any bytes (equivalent to awaiting `stream.allReady`).
+ */
+export type SSRStreamMode = "stream" | "allReady";
+
+/**
+ * Context passed to the resolveStreaming callback.
+ */
+export interface ResolveStreamingContext<TEnv = unknown> {
+  request: Request;
+  env: TEnv;
+  url: URL;
+}
+
+/**
+ * SSR configuration options.
+ */
+export interface SSROptions<TEnv = unknown> {
+  /**
+   * Determine whether an HTML response should stream progressively or
+   * wait for full readiness before flushing.
+   *
+   * Called once per HTML request, before the HTML response is produced.
+   * Does NOT apply to RSC responses (`__rsc`, partial navigation, prefetch).
+   *
+   * Return `"stream"` (default) for progressive streaming or `"allReady"`
+   * to buffer the complete HTML before sending.
+   *
+   * @example Bot detection
+   * ```ts
+   * createRouter({
+   *   ssr: {
+   *     resolveStreaming: async ({ request, env }) => {
+   *       const bot = await detectBot(request, env);
+   *       return bot.isBot && !bot.supportsStreaming ? "allReady" : "stream";
+   *     },
+   *   },
+   * });
+   * ```
+   */
+  resolveStreaming?: (
+    context: ResolveStreamingContext<TEnv>,
+  ) => SSRStreamMode | Promise<SSRStreamMode>;
+}
 
 /**
  * Props passed to the root layout component
@@ -384,4 +436,152 @@ export interface RSCRouterOptions<TEnv = any> {
    * @default true
    */
   warmup?: boolean;
+
+  /**
+   * Shorthand timeout (ms) applied to both action execution and render start.
+   * Does NOT apply to streamIdleMs.
+   * Overridden by individual values in `timeouts`.
+   *
+   * @example
+   * ```typescript
+   * createRouter({ timeout: 10_000 });
+   * ```
+   */
+  timeout?: number;
+
+  /**
+   * Structured timeout configuration per phase.
+   * Values here override the `timeout` shorthand.
+   *
+   * @example
+   * ```typescript
+   * createRouter({
+   *   timeouts: {
+   *     actionMs: 10_000,
+   *     renderStartMs: 8_000,
+   *   },
+   * });
+   * ```
+   */
+  timeouts?: RouterTimeouts;
+
+  /**
+   * Custom handler invoked when a timeout occurs.
+   * Receives context about which phase timed out and must return a Response.
+   * If not provided, returns a plain 504 with "Request timed out" body
+   * and X-Rango-Timeout-Phase header.
+   *
+   * If the callback throws, the default 504 response is used as fallback.
+   *
+   * @example
+   * ```typescript
+   * createRouter({
+   *   timeout: 10_000,
+   *   onTimeout: (ctx) => {
+   *     return new Response(
+   *       JSON.stringify({ error: "timeout", phase: ctx.phase }),
+   *       { status: 504, headers: { "Content-Type": "application/json" } },
+   *     );
+   *   },
+   * });
+   * ```
+   */
+  onTimeout?: OnTimeoutCallback<TEnv>;
+
+  /**
+   * Telemetry sink for structured lifecycle events.
+   *
+   * When provided, the router emits events for request start/end,
+   * loader start/end/error, handler errors, cache decisions, and
+   * revalidation decisions.
+   *
+   * No-op when not configured (zero overhead).
+   *
+   * @example Console logging
+   * ```typescript
+   * import { createConsoleSink } from "@rangojs/router";
+   *
+   * const router = createRouter({
+   *   telemetry: createConsoleSink(),
+   * });
+   * ```
+   *
+   * @example Custom sink
+   * ```typescript
+   * const router = createRouter({
+   *   telemetry: {
+   *     emit(event) {
+   *       myTracer.record(event);
+   *     },
+   *   },
+   * });
+   * ```
+   */
+  telemetry?: TelemetrySink;
+
+  /**
+   * SSR configuration options.
+   *
+   * @example
+   * ```typescript
+   * createRouter({
+   *   ssr: {
+   *     resolveStreaming: async ({ request, env }) => {
+   *       const bot = await detectBot(request, env);
+   *       return bot.isBot ? "allReady" : "stream";
+   *     },
+   *   },
+   * });
+   * ```
+   */
+  ssr?: SSROptions<TEnv>;
+
+  /**
+   * Cross-origin request protection for server actions, loader fetches,
+   * and progressive enhancement form submissions.
+   *
+   * When enabled, the router validates that the request's Origin header
+   * (or Referer fallback) matches the Host before executing actions,
+   * loaders, or PE submissions. Requests without Origin/Referer are
+   * allowed (same-origin navigations, non-browser clients).
+   *
+   * The built-in check compares Origin against the Host header and
+   * url.protocol. It does NOT trust X-Forwarded-Host/Proto headers
+   * (they are client-controllable without a trusted proxy). On standard
+   * deployments (Cloudflare Workers, Node behind nginx/caddy) the Host
+   * header is already set to the public-facing host by the platform or
+   * proxy. For non-standard proxy setups where Host differs from the
+   * public origin, use a custom function that reads the appropriate
+   * forwarded headers from your trusted proxy.
+   *
+   * - `true` (default) -- enable built-in origin validation
+   * - `false` -- disable
+   * - function -- full custom control with access to env, phase,
+   *   and the built-in check via `ctx.defaultCheck()`
+   *
+   * The callback receives `OriginCheckContext` with `request`, `url`,
+   * `env`, `routerId`, `phase` ("action" | "loader" | "pe-form"),
+   * and `defaultCheck()`. Return `true` to allow, `false` for default
+   * 403 rejection, or a `Response` for custom rejection.
+   *
+   * @default true
+   *
+   * @example Trusted proxy with X-Forwarded-Host
+   * ```ts
+   * createRouter({
+   *   originCheck({ request, url, env, defaultCheck }) {
+   *     if (env.TRUST_PROXY) {
+   *       const origin = request.headers.get("origin");
+   *       if (!origin) return true;
+   *       if (origin === "null") return false;
+   *       const host = request.headers.get("x-forwarded-host")
+   *         ?? request.headers.get("host") ?? url.host;
+   *       return origin.toLowerCase() === `${url.protocol}//${host}`.toLowerCase();
+   *     }
+   *     return defaultCheck();
+   *   },
+   * });
+   * ```
+   */
+  originCheck?: import("../rsc/origin-guard.js").OriginCheckConfig<TEnv>;
 }

package/src/router/segment-resolution/fresh.ts

@@ -22,6 +22,51 @@ import {
   resolveLayoutComponent,
   resolveWithErrorBoundary,
 } from "./helpers.js";
+import { getRouterContext } from "../router-context.js";
+import { resolveSink, safeEmit } from "../telemetry.js";
+
+// ---------------------------------------------------------------------------
+// Streamed handler telemetry
+// ---------------------------------------------------------------------------
+
+/**
+ * Attach a fire-and-forget rejection observer to a streamed handler promise.
+ * React catches the actual error via its error boundary; this only emits
+ * the handler.error telemetry event.
+ */
+function observeStreamedHandler(
+  promise: Promise<ReactNode>,
+  segmentId: string,
+  segmentType: string,
+  pathname?: string,
+  routeKey?: string,
+  params?: Record<string, string>,
+): void {
+  let routerCtx;
+  try {
+    routerCtx = getRouterContext();
+  } catch {
+    return;
+  }
+  if (!routerCtx?.telemetry) return;
+  const sink = resolveSink(routerCtx.telemetry);
+  const reqId = routerCtx.requestId;
+  promise.catch((err: unknown) => {
+    const errorObj = err instanceof Error ? err : new Error(String(err));
+    safeEmit(sink, {
+      type: "handler.error",
+      timestamp: performance.now(),
+      requestId: reqId,
+      segmentId,
+      segmentType,
+      error: errorObj,
+      handledByBoundary: true,
+      pathname,
+      routeKey,
+      params,
+    });
+  });
+}
 
 // ---------------------------------------------------------------------------
 // Fresh path (full match, no revalidation)
@@ -128,19 +173,8 @@ export async function resolveSegment<TEnv>(
       segments.push(...loaderSegments);
     }
 
-    for (const parallelEntry of entry.parallel) {
-      const parallelSegments = await resolveParallelEntry(
-        parallelEntry,
-        params,
-        context,
-        false,
-        entry.shortCode,
-        deps,
-        options,
-      );
-      segments.push(...parallelSegments);
-    }
-
+    // Handler-first: layout handler executes before its parallels and orphan
+    // layouts so that ctx.set() values are visible to all children.
     (context as InternalHandlerContext<any, TEnv>)._currentSegmentId =
       entry.shortCode;
 
@@ -160,6 +194,20 @@ export async function resolveSegment<TEnv>(
       ...(entry.mountPath ? { mountPath: entry.mountPath } : {}),
     });
 
+    for (const parallelEntry of entry.parallel) {
+      const parallelSegments = await resolveParallelEntry(
+        parallelEntry,
+        params,
+        context,
+        false,
+        entry.shortCode,
+        deps,
+        options,
+        routeKey,
+      );
+      segments.push(...parallelSegments);
+    }
+
     for (const orphan of entry.layout) {
       const orphanSegments = await resolveOrphanLayout(
         orphan,
@@ -169,6 +217,7 @@ export async function resolveSegment<TEnv>(
         false,
         deps,
         options,
+        routeKey,
       );
       segments.push(...orphanSegments);
     }
@@ -194,8 +243,23 @@ export async function resolveSegment<TEnv>(
     if (component === undefined) {
       if (entry.loading) {
         const result = handleHandlerResult(entry.handler(context));
-        component =
-          result instanceof Promise ? deps.trackHandler(result) : result;
+        if (result instanceof Promise) {
+          const tracked = deps.trackHandler(result, {
+            segmentId: entry.shortCode,
+            segmentType: entry.type,
+          });
+          observeStreamedHandler(
+            tracked,
+            entry.shortCode,
+            entry.type,
+            context.pathname,
+            routeKey,
+            params,
+          );
+          component = tracked;
+        } else {
+          component = result;
+        }
       } else {
         component = handleHandlerResult(await entry.handler(context));
       }
@@ -210,6 +274,7 @@ export async function resolveSegment<TEnv>(
         true,
         deps,
         options,
+        routeKey,
       );
       segments.push(...orphanSegments);
     }
@@ -223,6 +288,7 @@ export async function resolveSegment<TEnv>(
         entry.shortCode,
         deps,
         options,
+        routeKey,
       );
       segments.push(...parallelSegments);
     }
@@ -257,6 +323,7 @@ export async function resolveOrphanLayout<TEnv>(
   belongsToRoute: boolean,
   deps: SegmentResolutionDeps<TEnv>,
   options?: ResolveSegmentOptions,
+  routeKey?: string,
 ): Promise<ResolvedSegment[]> {
   invariant(
     orphan.type === "layout" || orphan.type === "cache",
@@ -274,19 +341,8 @@ export async function resolveOrphanLayout<TEnv>(
     segments.push(...loaderSegments);
   }
 
-  for (const parallelEntry of orphan.parallel) {
-    const parallelSegments = await resolveParallelEntry(
-      parallelEntry,
-      params,
-      context,
-      belongsToRoute,
-      orphan.shortCode,
-      deps,
-      options,
-    );
-    segments.push(...parallelSegments);
-  }
-
+  // Handler-first: orphan layout handler executes before its parallels
+  // so that ctx.set() values are visible to parallel children.
   const component = await resolveLayoutComponent(orphan, context);
 
   segments.push({
@@ -303,6 +359,20 @@ export async function resolveOrphanLayout<TEnv>(
     ...(orphan.mountPath ? { mountPath: orphan.mountPath } : {}),
   });
 
+  for (const parallelEntry of orphan.parallel) {
+    const parallelSegments = await resolveParallelEntry(
+      parallelEntry,
+      params,
+      context,
+      belongsToRoute,
+      orphan.shortCode,
+      deps,
+      options,
+      routeKey,
+    );
+    segments.push(...parallelSegments);
+  }
+
   return segments;
 }
 
@@ -317,6 +387,7 @@ export async function resolveParallelEntry<TEnv>(
   parentShortCode: string,
   deps: SegmentResolutionDeps<TEnv>,
   options?: ResolveSegmentOptions,
+  routeKey?: string,
 ): Promise<ResolvedSegment[]> {
   invariant(
     parallelEntry.type === "parallel",
@@ -344,7 +415,23 @@ export async function resolveParallelEntry<TEnv>(
       if (hasLoadingFallback) {
         const result =
           typeof handler === "function" ? handler(context) : handler;
-        component = result as ReactNode;
+        if (result instanceof Promise) {
+          const tracked = deps.trackHandler(result, {
+            segmentId: `${parentShortCode}.${slot}`,
+            segmentType: "parallel",
+          });
+          observeStreamedHandler(
+            tracked,
+            `${parentShortCode}.${slot}`,
+            "parallel",
+            context.pathname,
+            routeKey,
+            params,
+          );
+          component = tracked as ReactNode;
+        } else {
+          component = result as ReactNode;
+        }
       } else {
         component =
           typeof handler === "function" ? await handler(context) : handler;
@@ -405,6 +492,12 @@ export async function resolveAllSegments<TEnv>(
     safeRequest = context.request;
   } catch {}
 
+  // Get telemetry sink from RouterContext (may not exist during prerendering)
+  let telemetry;
+  try {
+    telemetry = getRouterContext()?.telemetry;
+  } catch {}
+
   for (const entry of entries) {
     const resolvedSegments = await resolveWithErrorBoundary(
       entry,
@@ -422,7 +515,7 @@ export async function resolveAllSegments<TEnv>(
         ),
       (seg) => [seg],
       deps,
-      { request: safeRequest, url: context.url, routeKey },
+      { request: safeRequest, url: context.url, routeKey, telemetry },
       context.pathname,
     );
     // Deduplicate by segment ID. include() scopes can produce entries that

package/src/router/segment-resolution/helpers.ts

@@ -23,6 +23,8 @@ import type { ResolvedSegment, ErrorInfo, HandlerContext } from "../../types";
 import type { SegmentResolutionDeps } from "../types.js";
 import { debugLog } from "../logging.js";
 import { tryStaticLookup } from "./static-store.js";
+import type { TelemetrySink } from "../telemetry.js";
+import { resolveSink, safeEmit, getRequestId } from "../telemetry.js";
 
 // ---------------------------------------------------------------------------
 // Handler result processing
@@ -116,6 +118,7 @@ export interface ErrorReportContext {
   env?: any;
   isPartial?: boolean;
   requestStartTime?: number;
+  telemetry?: TelemetrySink;
 }
 
 /**
@@ -150,6 +153,22 @@ export function catchSegmentError<TEnv>(
       metadata,
       requestStartTime: report.requestStartTime,
     });
+    if (report.telemetry) {
+      const errorObj =
+        error instanceof Error ? error : new Error(String(error));
+      safeEmit(resolveSink(report.telemetry), {
+        type: "handler.error",
+        timestamp: performance.now(),
+        requestId: report.request ? getRequestId(report.request) : undefined,
+        segmentId: entry.shortCode,
+        segmentType: entry.type,
+        error: errorObj,
+        handledByBoundary,
+        pathname,
+        routeKey: report.routeKey,
+        params,
+      });
+    }
   };
 
   const setResponseStatus = (status: number) => {