@rangojs/router 0.0.0-experimental.259 → 0.0.0-experimental.26

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.
@@ -47,19 +48,19 @@ type MergeRoutesWithResponses<
 };
 
 /**
- * RSC Router interface
- * TRoutes accumulates all registered route types through the builder chain
+ * Public RSC Router interface — the user-facing API surface.
+ *
+ * Users interact with this type when building and using routers.
+ * Internal framework code uses RSCRouterInternal (via toInternal()) to access
+ * matching, build-time, and configuration members that are not part of the
+ * public contract.
+ *
+ * TRoutes accumulates all registered route types through the builder chain.
  */
 export interface RSCRouter<
   TEnv = any,
   TRoutes extends Record<string, unknown> = Record<string, string>,
 > {
-  /**
-   * Brand marker for build-time discovery.
-   * The Vite plugin uses this to identify router instances in module exports.
-   */
-  readonly __brand: typeof RSC_ROUTER_BRAND;
-
   /**
    * Unique identifier for this router instance.
    * Used to namespace static output and isolate route maps between routers.
@@ -134,6 +135,90 @@ export interface RSCRouter<
    */
   readonly routeMap: TRoutes;
 
+  /**
+   * Handle an RSC request.
+   *
+   * Uses the router's configuration (nonce, version, cache) automatically.
+   * The handler is lazily created on first call.
+   *
+   * @example Cloudflare Workers
+   * ```tsx
+   * import { router } from "./router";
+   *
+   * export default { fetch: router.fetch };
+   * ```
+   *
+   * @example Direct export
+   * ```tsx
+   * const router = createRouter({
+   *   document: Document,
+   *   urls: urlpatterns,
+   *   nonce: () => true,
+   * });
+   *
+   * export const fetch = router.fetch;
+   * ```
+   */
+  fetch(request: Request, input?: RouterRequestInput<TEnv>): Promise<Response>;
+}
+
+/**
+ * Internal RSC Router interface — the full framework-facing API.
+ *
+ * This type includes all members used by the Vite plugin, RSC handler,
+ * pre-rendering pipeline, and other framework internals. It is NOT exported
+ * from the public package API.
+ *
+ * Use toInternal(router) to assert a public RSCRouter into this type
+ * at the boundary where framework code receives a user-provided router.
+ */
+export interface RSCRouterInternal<
+  TEnv = any,
+  TRoutes extends Record<string, unknown> = Record<string, string>,
+> {
+  /**
+   * Brand marker for build-time discovery.
+   * The Vite plugin uses this to identify router instances in module exports.
+   */
+  readonly __brand: typeof RSC_ROUTER_BRAND;
+
+  /**
+   * Unique identifier for this router instance.
+   * Used to namespace static output and isolate route maps between routers.
+   */
+  readonly id: string;
+
+  /**
+   * Register routes using URL patterns from urls()
+   */
+  routes<T extends UrlPatterns<TEnv, any>>(
+    patterns: T,
+  ): RSCRouter<
+    TEnv,
+    TRoutes &
+      (NonNullable<T["_routes"]> extends Record<string, unknown>
+        ? MergeRoutesWithResponses<NonNullable<T["_routes"]>, T["_responses"]>
+        : Record<string, string>)
+  >;
+
+  /**
+   * Add global middleware that runs on all routes
+   */
+  use(
+    patternOrMiddleware: string | MiddlewareFn<TEnv>,
+    middleware?: MiddlewareFn<TEnv>,
+  ): RSCRouter<TEnv, TRoutes>;
+
+  /**
+   * Type-safe URL builder for registered routes
+   */
+  reverse: ReverseFunction<TRoutes>;
+
+  /**
+   * Accumulated route map for typeof extraction
+   */
+  readonly routeMap: TRoutes;
+
   /**
    * Root layout component that wraps the entire application
    * Access this to pass to renderSegments
@@ -147,12 +232,12 @@ export interface RSCRouter<
   readonly onError?: RSCRouterOptions<TEnv>["onError"];
 
   /**
-   * Cache configuration (for internal use by RSC handler)
+   * Cache configuration
    */
   readonly cache?: RSCRouterOptions<TEnv>["cache"];
 
   /**
-   * Not found component to render when no route matches (for internal use by RSC handler)
+   * Not found component to render when no route matches
    */
   readonly notFound?: RSCRouterOptions<TEnv>["notFound"];
 
@@ -162,6 +247,21 @@ export interface RSCRouter<
    */
   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.
+   */
+  readonly prefetchCacheControl: string | false;
+
   /**
    * Whether connection warmup is enabled.
    * When true, the client sends HEAD /?_rsc_warmup after idle periods
@@ -169,40 +269,65 @@ export interface RSCRouter<
    */
   readonly warmupEnabled: boolean;
 
+  /**
+   * Whether router-wide performance debugging is enabled.
+   * Used by the request handler to create metrics before middleware runs.
+   */
+  readonly debugPerformance?: boolean;
+
   /**
    * Whether ?__debug_manifest is allowed in production.
    * Always enabled in development.
-   * @internal
    */
   readonly allowDebugManifest: boolean;
 
   /**
-   * App-level middleware entries (for internal use by RSC handler)
+   * 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
    */
   readonly middleware: MiddlewareEntry<TEnv>[];
 
   /**
-   * Nonce provider for CSP (for internal use by createHandler)
+   * Nonce provider for CSP
    */
   readonly nonce?: NonceProvider<TEnv>;
 
   /**
-   * RSC version string (for internal use by createHandler)
+   * RSC version string
    */
   readonly version?: string;
 
   /**
    * URL patterns reference for build-time manifest generation
-   * @internal
    */
   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.
    * Used by the Vite plugin to write per-router named-routes.gen.ts files.
-   * @internal
    */
   readonly __sourceFile?: string;
 
@@ -215,12 +340,12 @@ export interface RSCRouter<
    * Build-time pre-render match. Resolves segments with a BuildContext
    * (no request/env/headers/cookies), skipping middleware and loaders.
    * Used by the Vite plugin to collect pre-render data at build time.
-   * @internal
    */
   matchForPrerender(
     pathname: string,
     params: Record<string, string>,
     buildVars?: Record<string, any>,
+    isPassthroughRoute?: boolean,
   ): Promise<{
     segments: SerializedSegmentData[];
     handles: Record<string, SegmentHandleData>;
@@ -228,12 +353,12 @@ export interface RSCRouter<
     params: Record<string, string>;
     interceptSegments?: SerializedSegmentData[];
     interceptHandles?: Record<string, SegmentHandleData>;
+    passthrough?: true;
   } | null>;
 
   /**
    * Render a single Static handler at build time.
    * Returns the RSC-serialized component string and handle data, or null on failure.
-   * @internal
    */
   renderStaticSegment(
     handler: Function,
@@ -293,7 +418,6 @@ export interface RSCRouter<
   ): Promise<MatchResult | null>;
 
   /**
-   * @internal
    * Debug utility to serialize the manifest for inspection
    * Returns a JSON-friendly representation of all routes and layouts
    */
@@ -301,27 +425,21 @@ export interface RSCRouter<
 
   /**
    * Handle an RSC request.
-   *
-   * Uses the router's configuration (nonce, version, cache) automatically.
-   * The handler is lazily created on first call.
-   *
-   * @example Cloudflare Workers
-   * ```tsx
-   * import { router } from "./router";
-   *
-   * export default { fetch: router.fetch };
-   * ```
-   *
-   * @example Direct export
-   * ```tsx
-   * const router = createRouter({
-   *   document: Document,
-   *   urls: urlpatterns,
-   *   nonce: () => true,
-   * });
-   *
-   * export const fetch = router.fetch;
-   * ```
    */
   fetch(request: Request, input?: RouterRequestInput<TEnv>): Promise<Response>;
 }
+
+/**
+ * Assert a public RSCRouter into the internal type.
+ *
+ * Use this at the boundary where framework code receives a user-provided
+ * router and needs access to internal members (match, config, build-time).
+ * The cast is safe because createRouter() always produces an object that
+ * satisfies RSCRouterInternal; the public type is just a narrower view.
+ */
+export function toInternal<
+  TEnv = any,
+  TRoutes extends Record<string, unknown> = Record<string, string>,
+>(router: RSCRouter<TEnv, TRoutes>): RSCRouterInternal<TEnv, TRoutes> {
+  return router as RSCRouterInternal<TEnv, TRoutes>;
+}

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
@@ -187,7 +239,7 @@ export interface RSCRouterOptions<TEnv = any> {
    *
    * @example Static config
    * ```typescript
-   * import { MemorySegmentCacheStore } from "rsc-router/rsc";
+   * import { MemorySegmentCacheStore } from "@rangojs/router/cache";
    *
    * const router = createRouter({
    *   cache: {
@@ -338,6 +390,16 @@ export interface RSCRouterOptions<TEnv = any> {
    *   nonce: (request, env) => env.nonce,
    * });
    * ```
+   *
+   * @example Access nonce in middleware
+   * ```tsx
+   * import { nonce } from "@rangojs/router";
+   *
+   * const cspMiddleware: Middleware = async (ctx, next) => {
+   *   const value = ctx.get(nonce); // string | undefined
+   *   await next();
+   * };
+   * ```
    */
   nonce?: NonceProvider<TEnv>;
 
@@ -352,6 +414,18 @@ export interface RSCRouterOptions<TEnv = any> {
    */
   version?: string;
 
+  /**
+   * Cache-Control header value for prefetch responses.
+   * Only applied to non-intercept partial responses that include the
+   * `X-Rango-Prefetch` header (sent by the Link component's prefetch fetch).
+   * Navigation responses are never cached by the browser.
+   *
+   * Set to `false` to disable browser caching of prefetch responses entirely.
+   *
+   * @default "private, max-age=300"
+   */
+  prefetchCacheControl?: string | false;
+
   /**
    * Enable connection warmup to keep TCP+TLS alive after idle periods.
    *
@@ -362,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/router-registry.ts

@@ -1,4 +1,4 @@
-import type { RSCRouter } from "./router-interfaces.js";
+import type { RSCRouterInternal } from "./router-interfaces.js";
 
 /**
  * Brand marker for identifying router instances at build time.
@@ -12,7 +12,10 @@ export const RSC_ROUTER_BRAND = "__rsc_router__" as const;
  * Used by the Vite plugin at build time to discover routers and extract
  * manifests, prefix trees, and pre-render candidates.
  */
-export const RouterRegistry: Map<string, RSCRouter<any, any>> = new Map();
+export const RouterRegistry: Map<
+  string,
+  RSCRouterInternal<any, any>
+> = new Map();
 
 export let routerAutoId = 0;