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

package/src/router/timeout.ts

@@ -0,0 +1,148 @@
+/**
+ * Router Timeout
+ *
+ * Types, resolution logic, and helpers for request-level timeouts.
+ * Timeouts wrap action execution and render-start phases with
+ * a Promise.race mechanism, returning 504 on expiry.
+ */
+
+// ---------------------------------------------------------------------------
+// Public types
+// ---------------------------------------------------------------------------
+
+export interface RouterTimeouts {
+  /** Timeout for server action execution (ms). */
+  actionMs?: number;
+  /** Timeout for initial render/response production (ms). */
+  renderStartMs?: number;
+  /** Timeout for idle streaming after render starts (ms). Reserved for PR 2. */
+  streamIdleMs?: number;
+}
+
+export type TimeoutPhase = "action" | "render-start" | "stream-idle";
+
+export interface TimeoutContext<TEnv = any> {
+  phase: TimeoutPhase;
+  request: Request;
+  url: URL;
+  env: TEnv;
+  routeKey?: string;
+  actionId?: string;
+  durationMs: number;
+}
+
+export type OnTimeoutCallback<TEnv = any> = (
+  ctx: TimeoutContext<TEnv>,
+) => Response | Promise<Response>;
+
+// ---------------------------------------------------------------------------
+// Internal resolved form
+// ---------------------------------------------------------------------------
+
+export interface ResolvedTimeouts {
+  actionMs: number | undefined;
+  renderStartMs: number | undefined;
+  streamIdleMs: number | undefined;
+}
+
+/**
+ * Merge the `timeout` shorthand with the structured `timeouts` object.
+ *
+ * - `timeout` applies to `actionMs` and `renderStartMs` (NOT `streamIdleMs`).
+ * - Explicit `timeouts.*` values override the shorthand.
+ * - Returns `undefined` for any phase that has no configured value.
+ */
+export function resolveTimeouts(
+  timeout?: number,
+  timeouts?: RouterTimeouts,
+): ResolvedTimeouts {
+  return {
+    actionMs: timeouts?.actionMs ?? timeout ?? undefined,
+    renderStartMs: timeouts?.renderStartMs ?? timeout ?? undefined,
+    streamIdleMs: timeouts?.streamIdleMs ?? undefined,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Error class
+// ---------------------------------------------------------------------------
+
+export class RouterTimeoutError extends Error {
+  override name = "RouterTimeoutError" as const;
+  phase: TimeoutPhase;
+  durationMs: number;
+
+  constructor(phase: TimeoutPhase, durationMs: number) {
+    super(
+      `Request timed out during ${phase} after ${Math.round(durationMs)}ms`,
+    );
+    this.phase = phase;
+    this.durationMs = durationMs;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Race helper
+// ---------------------------------------------------------------------------
+
+type TimeoutResult<T> =
+  | { result: T; timedOut: false }
+  | { timedOut: true; durationMs: number };
+
+/**
+ * Race an operation against a deadline.
+ *
+ * Returns a discriminated union so callers handle the timeout case
+ * without try/catch. Non-timeout errors from the operation re-throw.
+ *
+ * When `timeoutMs` is `undefined` or `<= 0`, the operation runs
+ * without any deadline (pass-through).
+ */
+export async function withTimeout<T>(
+  operation: Promise<T>,
+  timeoutMs: number | undefined,
+  phase: TimeoutPhase,
+): Promise<TimeoutResult<T>> {
+  if (timeoutMs == null || timeoutMs <= 0) {
+    return { result: await operation, timedOut: false };
+  }
+
+  const start = performance.now();
+  let timer: ReturnType<typeof setTimeout>;
+
+  const timeoutPromise = new Promise<never>((_, reject) => {
+    timer = setTimeout(() => {
+      reject(new RouterTimeoutError(phase, performance.now() - start));
+    }, timeoutMs);
+  });
+
+  try {
+    const result = await Promise.race([operation, timeoutPromise]);
+    clearTimeout(timer!);
+    return { result, timedOut: false };
+  } catch (error) {
+    clearTimeout(timer!);
+    if (error instanceof RouterTimeoutError) {
+      return { timedOut: true, durationMs: error.durationMs };
+    }
+    throw error;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Default response
+// ---------------------------------------------------------------------------
+
+/**
+ * Create the default 504 response for a timed-out request.
+ * Includes `X-Rango-Timeout-Phase` header for observability.
+ */
+export function createDefaultTimeoutResponse(phase: TimeoutPhase): Response {
+  return new Response("Request timed out", {
+    status: 504,
+    headers: {
+      "Content-Type": "text/plain;charset=utf-8",
+      "X-Rango-Timeout-Phase": phase,
+    },
+  });
+}

package/src/router/types.ts

@@ -83,7 +83,13 @@ export interface SegmentResolutionDeps<TEnv = any> {
       requestStartTime?: number;
     },
   ) => Promise<LoaderDataResult<T>>;
-  trackHandler: <T>(promise: Promise<T>) => Promise<T>;
+  trackHandler: <T>(
+    promise: Promise<T>,
+    errorContext?: {
+      segmentId?: string;
+      segmentType?: string;
+    },
+  ) => Promise<T>;
   findNearestErrorBoundary: (
     entry: EntryData | null,
   ) => ReactNode | ErrorBoundaryHandler | null;

package/src/router.ts

@@ -1,6 +1,9 @@
 import { type ReactNode } from "react";
 import { createCacheScope } from "./cache/cache-scope.js";
-import { setCacheProfiles } from "./cache/profile-registry.js";
+import {
+  setCacheProfiles,
+  resolveCacheProfiles,
+} from "./cache/profile-registry.js";
 import { isCachedFunction } from "./cache/taint.js";
 import { assertClientComponent } from "./component-utils.js";
 import { DefaultDocument } from "./components/DefaultDocument.js";
@@ -68,12 +71,14 @@ import {
   extractStaticPrefix,
   traverseBack,
 } from "./router/pattern-matching.js";
+import { resolveSink, safeEmit, getRequestId } from "./router/telemetry.js";
 import { evaluateRevalidation } from "./router/revalidation.js";
 import {
   type RouterContext,
   runWithRouterContext,
 } from "./router/router-context.js";
 import { resolveThemeConfig } from "./theme/constants.js";
+import { resolveTimeouts } from "./router/timeout.js";
 
 // Extracted content negotiation utilities
 import { flattenNamedRoutes } from "./router/content-negotiation.js";
@@ -111,6 +116,9 @@ export { RSC_ROUTER_BRAND, RouterRegistry } from "./router/router-registry.js";
 export type {
   RSCRouterOptions,
   RootLayoutProps,
+  SSRStreamMode,
+  SSROptions,
+  ResolveStreamingContext,
 } from "./router/router-options.js";
 export type {
   RSCRouter,
@@ -142,12 +150,22 @@ export function createRouter<TEnv = any>(
     prefetchCacheControl: prefetchCacheControlOption,
     warmup: warmupOption,
     allowDebugManifest: allowDebugManifestOption = false,
+    telemetry: telemetrySink,
+    ssr: ssrOption,
+    timeout: timeoutShorthand,
+    timeouts: timeoutsOption,
+    onTimeout,
+    originCheck: originCheckOption,
   } = options;
 
-  // Set cache profiles for "use cache" directive
-  if (cacheProfilesOption) {
-    setCacheProfiles(cacheProfilesOption);
-  }
+  // Resolve telemetry sink (no-op when not configured)
+  const telemetry = resolveSink(telemetrySink);
+
+  // Resolve cache profiles: merge user config with guaranteed default profile.
+  // This resolved map is both stored on the router (for per-request context)
+  // and written to the global registry (for DSL-time cache("profileName")).
+  const resolvedCacheProfiles = resolveCacheProfiles(cacheProfilesOption);
+  setCacheProfiles(resolvedCacheProfiles);
 
   // Source file: prefer Vite-injected path (zero cost), fall back to
   // stack trace parsing for non-Vite environments (e.g. tests).
@@ -196,15 +214,29 @@ export function createRouter<TEnv = any>(
     ? resolveThemeConfig(themeOption)
     : null;
 
+  // Resolve timeout config (merge shorthand + structured)
+  const resolvedTimeouts = resolveTimeouts(timeoutShorthand, timeoutsOption);
+
   /**
    * Wrapper for invokeOnError that binds the router's onError callback.
    * Uses the shared utility from router/error-handling.ts for consistent behavior.
+   *
+   * Deduplicates via per-request WeakSet stored on the ALS request context.
+   * A closure-level WeakSet would silently swallow errors if the same object
+   * instance is thrown across separate requests (e.g. a singleton error).
    */
   function callOnError(
     error: unknown,
     phase: ErrorPhase,
     context: Parameters<typeof invokeOnError<TEnv>>[3],
   ): void {
+    if (error != null && typeof error === "object") {
+      const reportedErrors = _getRequestContext()?._reportedErrors;
+      if (reportedErrors) {
+        if (reportedErrors.has(error)) return;
+        reportedErrors.add(error);
+      }
+    }
     invokeOnError(onError, error, phase, context, "Router");
   }
 
@@ -340,14 +372,43 @@ export function createRouter<TEnv = any>(
     return _getRequestContext()?._handleStore;
   };
 
-  // Track a pending handler promise (non-blocking)
-  const trackHandler = <T>(promise: Promise<T>): Promise<T> => {
+  // Track a pending handler promise (non-blocking).
+  // Attaches a side-effect .catch() to report streaming handler errors to onError
+  // without altering the rejection chain (React's streaming error boundary still handles it).
+  const trackHandler = <T>(
+    promise: Promise<T>,
+    errorContext?: {
+      segmentId?: string;
+      segmentType?: string;
+    },
+  ): Promise<T> => {
     const store = getHandleStore();
-    return store ? store.track(promise) : promise;
+    const tracked = store ? store.track(promise) : promise;
+
+    // Report streaming handler errors to onError as a side-effect.
+    // The rejection still propagates to the RSC stream for client error boundaries.
+    // Captures request context eagerly (closure) so the catch handler has full context.
+    const reqCtx = _getRequestContext();
+    if (reqCtx && onError) {
+      tracked.catch((error) => {
+        callOnError(error, "handler", {
+          request: reqCtx.request,
+          url: reqCtx.url,
+          routeKey: reqCtx._routeName,
+          params: reqCtx.params as Record<string, string>,
+          env: reqCtx.env as TEnv,
+          segmentId: errorContext?.segmentId,
+          segmentType: errorContext?.segmentType as any,
+          handledByBoundary: true,
+        });
+      });
+    }
+
+    return tracked;
   };
 
   // Wrapper for wrapLoaderWithErrorHandling that uses router's error boundary finder
-  // Includes onError callback for loader error notification
+  // Includes onError callback for loader error notification and telemetry emission.
   function wrapLoaderPromise<T>(
     promise: Promise<T>,
     entry: EntryData,
@@ -363,7 +424,25 @@ export function createRouter<TEnv = any>(
       requestStartTime?: number;
     },
   ): Promise<LoaderDataResult<T>> {
-    return wrapLoaderWithErrorHandling(
+    const loaderStart = telemetrySink ? performance.now() : 0;
+    const loaderRequestId = telemetrySink
+      ? errorContext?.request
+        ? getRequestId(errorContext.request)
+        : undefined
+      : undefined;
+    if (telemetrySink) {
+      const loaderName = segmentId.split(".").pop() || "unknown";
+      safeEmit(telemetry, {
+        type: "loader.start",
+        timestamp: loaderStart,
+        requestId: loaderRequestId,
+        segmentId,
+        loaderName,
+        pathname,
+      });
+    }
+
+    const result = wrapLoaderWithErrorHandling(
       promise,
       entry,
       segmentId,
@@ -386,9 +465,42 @@ export function createRouter<TEnv = any>(
               handledByBoundary: ctx.handledByBoundary,
               requestStartTime: errorContext.requestStartTime,
             });
+            if (telemetrySink) {
+              const errorObj =
+                error instanceof Error ? error : new Error(String(error));
+              safeEmit(telemetry, {
+                type: "loader.error",
+                timestamp: performance.now(),
+                requestId: loaderRequestId,
+                segmentId: ctx.segmentId,
+                loaderName: ctx.loaderName,
+                pathname,
+                error: errorObj,
+                handledByBoundary: ctx.handledByBoundary,
+              });
+            }
           }
         : undefined,
     );
+
+    // Emit loader.end after the promise settles (fire-and-forget)
+    if (telemetrySink) {
+      const loaderName = segmentId.split(".").pop() || "unknown";
+      result.then((r) => {
+        safeEmit(telemetry, {
+          type: "loader.end",
+          timestamp: performance.now(),
+          requestId: loaderRequestId,
+          segmentId,
+          loaderName,
+          pathname,
+          durationMs: performance.now() - loaderStart,
+          ok: r.ok,
+        });
+      });
+    }
+
+    return result;
   }
 
   // Dependencies object for extracted segment resolution functions.
@@ -468,6 +580,7 @@ export function createRouter<TEnv = any>(
       resolveLoadersOnlyWithRevalidation,
       resolveInterceptLoadersOnly,
       resolveLoadersOnly,
+      telemetry: telemetrySink,
     };
   }
 
@@ -483,8 +596,15 @@ export function createRouter<TEnv = any>(
     pathname: string,
     params: Record<string, string>,
     buildVars?: Record<string, any>,
+    isPassthroughRoute?: boolean,
   ) {
-    return _matchForPrerender(pathname, params, prerenderDeps, buildVars);
+    return _matchForPrerender(
+      pathname,
+      params,
+      prerenderDeps,
+      buildVars,
+      isPassthroughRoute,
+    );
   }
 
   async function renderStaticSegment(
@@ -508,6 +628,7 @@ export function createRouter<TEnv = any>(
     defaultErrorBoundary,
     findMatch,
     findInterceptForRoute,
+    telemetry: telemetrySink,
   });
 
   const { match, matchPartial, matchError, previewMatch } = matchHandlers;
@@ -568,6 +689,7 @@ export function createRouter<TEnv = any>(
           parent: syntheticMapRoot,
           counters: {},
           mountIndex: currentMountIndex,
+          cacheProfiles: resolvedCacheProfiles,
         },
         () => {
           handlerResult = urlPatterns.handler() as AllUseItems[];
@@ -582,10 +704,15 @@ export function createRouter<TEnv = any>(
 
       // Collect route keys that have prerender handlers (for non-trie match path)
       let prerenderRouteKeys: Set<string> | undefined;
+      let passthroughRouteKeys: Set<string> | undefined;
       for (const [name, entry] of manifest.entries()) {
         if (entry.type === "route" && entry.isPrerender) {
           if (!prerenderRouteKeys) prerenderRouteKeys = new Set();
           prerenderRouteKeys.add(name);
+          if (entry.prerenderDef?.options?.passthrough === true) {
+            if (!passthroughRouteKeys) passthroughRouteKeys = new Set();
+            passthroughRouteKeys.add(name);
+          }
         }
       }
 
@@ -608,7 +735,9 @@ export function createRouter<TEnv = any>(
             trailingSlash: trailingSlashConfig,
             handler: urlPatterns.handler,
             mountIndex: currentMountIndex,
+            cacheProfiles: resolvedCacheProfiles,
             ...(prerenderRouteKeys ? { prerenderRouteKeys } : {}),
+            ...(passthroughRouteKeys ? { passthroughRouteKeys } : {}),
           });
         }
       } else {
@@ -625,7 +754,9 @@ export function createRouter<TEnv = any>(
           trailingSlash: trailingSlashConfig,
           handler: urlPatterns.handler,
           mountIndex: currentMountIndex,
+          cacheProfiles: resolvedCacheProfiles,
           ...(prerenderRouteKeys ? { prerenderRouteKeys } : {}),
+          ...(passthroughRouteKeys ? { passthroughRouteKeys } : {}),
         });
       }
 
@@ -735,6 +866,9 @@ export function createRouter<TEnv = any>(
     // Expose resolved theme configuration for NavigationProvider and MetaTags
     themeConfig: resolvedThemeConfig,
 
+    // Expose resolved cache profiles for per-request resolution
+    cacheProfiles: resolvedCacheProfiles,
+
     // Expose prefetch cache control for RSC handler
     prefetchCacheControl,
 
@@ -744,6 +878,16 @@ export function createRouter<TEnv = any>(
     // Expose debug manifest flag for handler
     allowDebugManifest: allowDebugManifestOption,
 
+    // Expose origin check configuration for handler (default: enabled)
+    originCheck: originCheckOption ?? true,
+
+    // Expose SSR configuration for handler
+    ssr: ssrOption,
+
+    // Expose resolved timeouts for RSC handler
+    timeouts: resolvedTimeouts,
+    onTimeout,
+
     // Expose global middleware for RSC handler
     middleware: globalMiddleware,
 

package/src/rsc/handler-context.ts

@@ -10,6 +10,7 @@ import type { RSCRouterInternal } from "../router/router-interfaces.js";
 import type { ErrorPhase } from "../types.js";
 import type { InvokeOnErrorContext } from "../router/error-handling.js";
 import type { RSCDependencies, LoadSSRModule } from "./types.js";
+import type { SSRStreamMode } from "../router/router-options.js";
 
 export interface HandlerContext<TEnv = unknown> {
   router: RSCRouterInternal<TEnv, any>;
@@ -31,4 +32,14 @@ export interface HandlerContext<TEnv = unknown> {
     redirectUrl: string,
     locationState?: Record<string, unknown>,
   ) => Response;
+
+  /**
+   * Resolve the SSR stream mode for a given request.
+   * Returns "stream" when no resolveStreaming callback is configured.
+   */
+  resolveStreamMode: (
+    request: Request,
+    env: TEnv,
+    url: URL,
+  ) => Promise<SSRStreamMode>;
 }