@rangojs/router 0.0.0-experimental.259 → 0.0.0-experimental.25dbaac3

package/src/router/router-options.ts

@@ -8,7 +8,60 @@ import type {
 import type { NonceProvider } from "../rsc/types.js";
 import type { ExecutionContext } from "../server/request-context.js";
 import type { UrlPatterns } from "../urls.js";
+import type { UrlBuilder } from "../urls/pattern-types.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
@@ -43,6 +96,28 @@ export interface RSCRouterOptions<TEnv = any> {
    */
   $$sourceFile?: string;
 
+  /**
+   * URL prefix applied to all routes registered with this router.
+   *
+   * Useful when the app is served under a sub-path (e.g. `/admin` or `/v2`).
+   * All `path()` patterns are automatically prefixed and `reverse()` returns
+   * full paths including the basename. Route names are NOT prefixed.
+   *
+   * @example
+   * ```typescript
+   * const router = createRouter({
+   *   basename: "/admin",
+   * }).routes(({ path }) => [
+   *   path("/", Dashboard, { name: "home" }),       // matches /admin
+   *   path("/users", Users, { name: "users" }),     // matches /admin/users
+   * ]);
+   *
+   * router.reverse("home");   // "/admin"
+   * router.reverse("users");  // "/admin/users"
+   * ```
+   */
+  basename?: string;
+
   /**
    * Enable performance metrics collection
    * When enabled, metrics are output to console and available via Server-Timing header
@@ -187,7 +262,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: {
@@ -285,25 +360,28 @@ export interface RSCRouterOptions<TEnv = any> {
   /**
    * URL patterns to register with the router.
    *
-   * Alternative to calling `.routes()` method - allows passing patterns
-   * directly in the config for a more concise setup.
+   * Accepts either a `UrlPatterns` object from `urls()` or a builder function
+   * directly (urls() is called implicitly).
    *
    * @example
    * ```typescript
-   * import { urls } from "@rangojs/router/server";
-   *
-   * const urlpatterns = urls(({ path, layout }) => [
-   *   path("/", HomePage, { name: "home" }),
-   *   path("/about", AboutPage, { name: "about" }),
-   * ]);
-   *
-   * const router = createRouter<AppEnv>({
+   * // With urls()
+   * createRouter<AppEnv>({
    *   document: Document,
    *   urls: urlpatterns,
    * });
+   *
+   * // With builder function
+   * createRouter<AppEnv>({
+   *   document: Document,
+   *   urls: ({ path }) => [
+   *     path("/", HomePage, { name: "home" }),
+   *     path("/about", AboutPage, { name: "about" }),
+   *   ],
+   * });
    * ```
    */
-  urls?: UrlPatterns<TEnv, any>;
+  urls?: UrlPatterns<TEnv, any> | UrlBuilder<TEnv>;
 
   /**
    * Injected by the Vite transform at compile time.
@@ -338,6 +416,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 +440,23 @@ export interface RSCRouterOptions<TEnv = any> {
    */
   version?: string;
 
+  /**
+   * TTL (in seconds) for the in-memory prefetch cache and the
+   * Cache-Control header on prefetch responses.
+   *
+   * Controls how long prefetch responses are kept in the client-side
+   * in-memory cache and sets `Cache-Control: private, max-age=<ttl>`
+   * on server responses for CDN/edge caching.
+   *
+   * The cache is automatically invalidated on server actions regardless
+   * of TTL, so this is primarily a staleness safety net.
+   *
+   * Set to `false` to disable prefetch caching entirely.
+   *
+   * @default 300 (5 minutes)
+   */
+  prefetchCacheTTL?: number | false;
+
   /**
    * Enable connection warmup to keep TCP+TLS alive after idle periods.
    *
@@ -362,4 +467,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;