@rangojs/router 0.0.0-experimental.0b82333f

package/src/rsc/helpers.ts

@@ -0,0 +1,198 @@
+/**
+ * RSC Handler Helpers
+ *
+ * Utility functions for RSC request handling.
+ */
+
+import {
+  _getRequestContext,
+  getLocationState,
+} from "../server/request-context.js";
+import { resolveLocationStateEntries } from "../browser/react/location-state-shared.js";
+import type { MiddlewareEntry, MiddlewareFn } from "../router/middleware.js";
+
+/**
+ * Check if a request body has content to decode
+ */
+export function hasBodyContent(body: FormData | string): boolean {
+  if (body instanceof FormData) {
+    let hasContent = false;
+    body.forEach(() => {
+      hasContent = true;
+    });
+    return hasContent;
+  }
+  return typeof body === "string" && body.length > 0;
+}
+
+/**
+ * Create a Response with headers merged from the request context's stub response.
+ * This ensures headers/cookies set during middleware or handler execution are included.
+ * Also triggers any registered onResponse callbacks.
+ */
+export function createResponseWithMergedHeaders(
+  body: BodyInit | null,
+  init: ResponseInit,
+): Response {
+  const ctx = _getRequestContext();
+  if (!ctx) {
+    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.
+  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);
+    }
+  });
+  ctx.res.headers.delete("set-cookie");
+
+  // Use ctx.res.status if it was set (e.g., 404 for notFound, 500 for error)
+  // Otherwise use the status from init
+  const status = ctx.res.status !== 200 ? ctx.res.status : init.status;
+
+  let 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;
+}
+
+/**
+ * Create a 204 response with X-RSC-Redirect header for stateless redirects.
+ * Used during partial/action requests where fetch would auto-follow a raw
+ * 3xx to a URL that renders full HTML instead of Flight data. The 204 status
+ * prevents auto-follow; the client reads the header and re-navigates via
+ * the router.
+ */
+export function createSimpleRedirectResponse(redirectUrl: string): Response {
+  return createResponseWithMergedHeaders(null, {
+    status: 204,
+    headers: { "X-RSC-Redirect": redirectUrl },
+  });
+}
+
+/**
+ * Carry over headers from a source redirect Response to a wrapper Response.
+ * Skips Location and X-RSC-Redirect (intentionally replaced by the wrapper)
+ * and appends Set-Cookie to avoid clobbering multiple cookie headers.
+ */
+export function carryOverRedirectHeaders(
+  source: Response,
+  target: Response,
+): void {
+  source.headers.forEach((value, name) => {
+    const lower = name.toLowerCase();
+    if (lower === "location" || lower === "x-rsc-redirect") return;
+    if (lower === "set-cookie") {
+      target.headers.append(name, value);
+    } else if (!target.headers.has(name)) {
+      target.headers.set(name, value);
+    }
+  });
+}
+
+/**
+ * If a response is a 3xx redirect during a partial (client-side) request,
+ * intercept it and return a Flight-compatible redirect instead.
+ * fetch() auto-follows 3xx which would hit a URL that renders full HTML
+ * the client can't parse. Returns null if the response is not a redirect.
+ */
+export function interceptRedirectForPartial(
+  response: Response,
+  createRedirectFlightResponse: (
+    redirectUrl: string,
+    locationState?: Record<string, unknown>,
+  ) => Response,
+): Response | null {
+  const redirectUrl = response.headers.get("Location");
+  if (!(response.status >= 300 && response.status < 400 && redirectUrl)) {
+    return null;
+  }
+  const locationState = getLocationState();
+  let intercepted: Response;
+  if (locationState) {
+    intercepted = createRedirectFlightResponse(
+      redirectUrl,
+      resolveLocationStateEntries(locationState),
+    );
+  } else {
+    intercepted = createSimpleRedirectResponse(redirectUrl);
+  }
+
+  carryOverRedirectHeaders(response, intercepted);
+
+  return intercepted;
+}
+
+/**
+ * Only cache successful responses. Non-200 statuses (errors, redirects) are
+ * not cached -- notFound() produces 500 in response routes, and explicit
+ * non-200 Responses are rare enough that caching them would be surprising.
+ */
+export function isCacheableStatus(status: number): boolean {
+  return status === 200;
+}
+
+/**
+ * Convert route-level middleware entries to the format expected by
+ * executeMiddleware. Route middleware from previewMatch carries just
+ * { handler, params }; this wraps them in the full MiddlewareEntry shape.
+ */
+export function buildRouteMiddlewareEntries<TEnv>(
+  routeMiddleware: Array<{
+    handler: MiddlewareFn;
+    params: Record<string, string>;
+  }>,
+): Array<{ entry: MiddlewareEntry<TEnv>; params: Record<string, string> }> {
+  return routeMiddleware.map((mw) => ({
+    entry: {
+      pattern: null,
+      regex: null,
+      paramNames: [],
+      handler: mw.handler,
+      mountPrefix: null,
+    } as MiddlewareEntry<TEnv>,
+    params: mw.params,
+  }));
+}
+
+/**
+ * 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.
+ */
+export function finalizeResponse(response: Response): Response {
+  const ctx = _getRequestContext();
+  if (!ctx || ctx._onResponseCallbacks.length === 0) {
+    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;
+}

package/src/rsc/index.ts

@@ -0,0 +1,36 @@
+/**
+ * RSC Router - RSC Entry Point
+ *
+ * This module provides RSC utilities for server-side rendering,
+ * server actions, loader fetching, and progressive enhancement.
+ *
+ * @example Basic usage
+ * ```tsx
+ * import { router } from "./router.js";
+ *
+ * // Use router.fetch to handle requests
+ * export default { fetch: router.fetch };
+ * ```
+ */
+
+// Re-export createRSCHandler for custom handler setup
+export { createRSCHandler } from "./handler.js";
+
+// Re-export types
+export type {
+  RscPayload,
+  ReactFormState,
+  RSCDependencies,
+  SSRRenderOptions,
+  SSRModule,
+  LoadSSRModule,
+  CreateRSCHandlerOptions,
+  HandlerCacheConfig,
+  NonceProvider,
+} from "./types.js";
+
+// Re-export request context utilities for server-side access to env/request/params
+export {
+  getRequestContext,
+  requireRequestContext,
+} from "../server/request-context.js";

package/src/rsc/loader-fetch.ts

@@ -0,0 +1,209 @@
+/**
+ * Loader Fetch Handler
+ *
+ * Handles load() requests (GET, POST, PUT, PATCH, DELETE) from the client.
+ * All loader data fetching and mutations go through this endpoint.
+ *
+ * Route params (e.g. slug from /blog/:slug) come from previewMatch() in the
+ * outer coreRequestHandler, threaded through coreRequestHandlerInner as
+ * routeParams. This is necessary because handleLoaderFetch doesn't do its
+ * own route matching -- the URL is the page's pathname, and previewMatch
+ * has already extracted params from it.
+ */
+
+import { getLoaderLazy } from "../server/loader-registry.js";
+import { executeLoaderMiddleware } from "../router/middleware.js";
+import { requireRequestContext } from "../server/request-context.js";
+import {
+  createReverseFunction,
+  stripInternalParams,
+} from "../router/handler-context.js";
+import {
+  getGlobalRouteMap,
+  getSearchSchema,
+  isRouteRootScoped,
+} from "../route-map-builder.js";
+import { parseSearchParams } from "../search-params.js";
+import {
+  createResponseWithMergedHeaders,
+  finalizeResponse,
+} from "./helpers.js";
+import type { HandlerContext } from "./handler-context.js";
+
+export async function handleLoaderFetch<TEnv>(
+  ctx: HandlerContext<TEnv>,
+  request: Request,
+  env: TEnv,
+  url: URL,
+  variables: Record<string, any>,
+  routeParams?: Record<string, string>,
+): Promise<Response> {
+  const loaderId = url.searchParams.get("_rsc_loader");
+
+  if (!loaderId) {
+    return createResponseWithMergedHeaders("Missing _rsc_loader parameter", {
+      status: 400,
+    });
+  }
+
+  // Look up loader lazily
+  const registeredLoader = await getLoaderLazy(loaderId);
+  if (!registeredLoader) {
+    return createResponseWithMergedHeaders(
+      `Loader "${loaderId}" not found in registry`,
+      { status: 404 },
+    );
+  }
+
+  // Non-fetchable loaders are registered for SSR ctx.use() only.
+  // They must not be callable through the standalone _rsc_loader endpoint.
+  if (!registeredLoader.fetchable) {
+    return createResponseWithMergedHeaders(
+      `Loader "${loaderId}" is not fetchable`,
+      { status: 403 },
+    );
+  }
+
+  // Parse params, body, and formData based on request method and content type
+  let loaderParams: Record<string, string> = {};
+  let loaderBody: unknown = undefined;
+  let loaderFormData: FormData | undefined;
+  const isBodyMethod = request.method !== "GET" && request.method !== "HEAD";
+
+  if (isBodyMethod) {
+    try {
+      const contentType = request.headers.get("content-type") || "";
+      if (contentType.includes("multipart/form-data")) {
+        // FormData body — sent by load() when body is a FormData instance.
+        // Preserves File objects and binary data.
+        loaderFormData = await request.formData();
+        // Extract params if provided via the special field
+        const paramsField = loaderFormData.get("_rsc_loader_params");
+        if (typeof paramsField === "string") {
+          loaderParams = JSON.parse(paramsField);
+          loaderFormData.delete("_rsc_loader_params");
+        }
+      } else if (contentType.includes("application/json")) {
+        const jsonBody = (await request.json()) as {
+          params?: Record<string, string>;
+          body?: unknown;
+        };
+        loaderParams = jsonBody.params ?? {};
+        loaderBody = jsonBody.body;
+      }
+    } catch {
+      return createResponseWithMergedHeaders("Invalid request body", {
+        status: 400,
+      });
+    }
+  } else {
+    const loaderParamsJson = url.searchParams.get("_rsc_loader_params");
+    if (loaderParamsJson) {
+      try {
+        loaderParams = JSON.parse(loaderParamsJson);
+      } catch {
+        return createResponseWithMergedHeaders(
+          "Invalid _rsc_loader_params JSON",
+          { status: 400 },
+        );
+      }
+    }
+  }
+
+  // Execute the loader with middleware.
+  // finalizeResponse drains onResponse callbacks that middleware short-circuits
+  // may leave behind (executeLoaderMiddleware does not finalize them itself).
+  try {
+    const { fn, middleware } = registeredLoader;
+
+    return finalizeResponse(
+      await executeLoaderMiddleware(
+        middleware,
+        request,
+        env,
+        loaderParams,
+        variables,
+        async () => {
+          const reqCtx = requireRequestContext();
+          // Merge route params (from previewMatch) with explicit loader params.
+          // Explicit params take precedence over route-matched params.
+          const resolvedRouteParams = routeParams ?? {};
+          const mergedParams = {
+            ...resolvedRouteParams,
+            ...loaderParams,
+          };
+          // Strip _rsc_* transport params so loaders see the same
+          // url/searchParams as during SSR/navigation.
+          const cleanUrl = stripInternalParams(url);
+          const cleanSearchParams = cleanUrl.searchParams;
+          const searchSchema = reqCtx._routeName
+            ? getSearchSchema(reqCtx._routeName)
+            : undefined;
+          const loaderCtx: any = {
+            ...reqCtx,
+            url: cleanUrl,
+            pathname: cleanUrl.pathname,
+            searchParams: cleanSearchParams,
+            search: searchSchema
+              ? parseSearchParams(cleanSearchParams, searchSchema)
+              : {},
+            params: mergedParams,
+            routeParams: resolvedRouteParams,
+            body: loaderBody,
+            method: request.method,
+            reverse: createReverseFunction(
+              getGlobalRouteMap(),
+              reqCtx._routeName,
+              mergedParams,
+              reqCtx._routeName
+                ? isRouteRootScoped(reqCtx._routeName)
+                : undefined,
+            ),
+            ...(loaderFormData ? { formData: loaderFormData } : {}),
+          };
+
+          const result = await fn(loaderCtx);
+
+          interface LoaderPayload {
+            loaderResult: unknown;
+          }
+          const loaderPayload: LoaderPayload = { loaderResult: result };
+          const rscStream =
+            ctx.renderToReadableStream<LoaderPayload>(loaderPayload);
+
+          return createResponseWithMergedHeaders(rscStream, {
+            headers: { "content-type": "text/x-component;charset=utf-8" },
+          });
+        },
+        createReverseFunction(ctx.getRequiredRouteMap()),
+      ),
+    );
+  } catch (error) {
+    const err = error instanceof Error ? error : new Error(String(error));
+    const isDev = process.env.NODE_ENV !== "production";
+
+    console.error("[RSC] Loader error:", error);
+
+    ctx.callOnError(error, "loader", {
+      request,
+      url,
+      env,
+      loaderName: loaderId,
+      handledByBoundary: false,
+    });
+
+    const errorPayload = {
+      loaderResult: null,
+      loaderError: {
+        message: isDev ? err.message : "An error occurred",
+        name: err.name,
+      },
+    };
+    const rscStream = ctx.renderToReadableStream(errorPayload);
+
+    return createResponseWithMergedHeaders(rscStream, {
+      status: 500,
+      headers: { "content-type": "text/x-component;charset=utf-8" },
+    });
+  }
+}

package/src/rsc/manifest-init.ts

@@ -0,0 +1,86 @@
+/**
+ * Router Manifest Initialization
+ *
+ * Builds a fresh route trie from router.urlpatterns for dev/HMR scenarios
+ * where the manifest exists but the trie needs rebuilding.
+ */
+
+import {
+  getGlobalRouteMap,
+  hasCachedManifest,
+  setCachedManifest,
+  getRouteTrie,
+  setRouteTrie,
+  setRouterManifest,
+  setRouterTrie,
+} from "../route-map-builder.js";
+
+/**
+ * Build a fresh route trie from router.urlpatterns and store it in the
+ * per-router cache. Also sets the per-router manifest and merges into
+ * the global manifest for reverse()/href().
+ *
+ * Called when manifest data may exist but the per-router trie is missing,
+ * which happens in dev mode after HMR: the virtual module sets the manifest
+ * from fresh gen files but skips the trie (which would be stale from initial
+ * discovery). The trie is essential for correct wildcard priority -- without
+ * it, the regex fallback matches catch-all patterns before specific routes.
+ */
+export async function buildRouterTrieFromUrlpatterns(
+  router: any,
+): Promise<void> {
+  const { generateManifestFull } =
+    await import("../build/generate-manifest.js");
+  const generated = generateManifestFull(router.urlpatterns);
+  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,
+    );
+    setRouterTrie(router.id, trie);
+    // Set global trie only if not already set by another router
+    if (!getRouteTrie()) {
+      setRouteTrie(trie);
+    }
+  }
+  setRouterManifest(router.id, generated.routeManifest);
+  // Merge into global manifest (needed for reverse/href across routers)
+  const existing = hasCachedManifest() ? getGlobalRouteMap() : {};
+  setCachedManifest({ ...existing, ...generated.routeManifest });
+}

package/src/rsc/nonce.ts

@@ -0,0 +1,32 @@
+/**
+ * Nonce generation for Content Security Policy (CSP)
+ */
+
+import type { ContextVar } from "../context-var.js";
+import { createVar } from "../context-var.js";
+
+/**
+ * Typed ContextVar token for CSP nonce.
+ *
+ * Use this to access the nonce in middleware or handlers:
+ * ```ts
+ * import { nonce } from "@rangojs/router";
+ * const value = ctx.get(nonce); // string | undefined
+ * ```
+ */
+export const nonce: ContextVar<string> = createVar<string>();
+
+/**
+ * Generate a cryptographic nonce for CSP.
+ * Returns a 16-byte random value encoded as base64.
+ */
+export function generateNonce(): string {
+  const array = new Uint8Array(16);
+  crypto.getRandomValues(array);
+  // Convert to base64
+  let binary = "";
+  for (let i = 0; i < array.length; i++) {
+    binary += String.fromCharCode(array[i]);
+  }
+  return btoa(binary);
+}

package/src/rsc/origin-guard.ts

@@ -0,0 +1,141 @@
+/**
+ * Origin Guard
+ *
+ * Cross-origin request protection for server actions, loader fetches, and
+ * progressive enhancement form submissions. Validates that the Origin header
+ * (or Referer fallback) matches the request Host before executing.
+ *
+ * Requests without an Origin or Referer header are allowed — same-origin
+ * navigations, bookmarks, and non-browser clients don't send Origin.
+ */
+
+/**
+ * Request phase that triggered the origin check.
+ */
+export type OriginCheckPhase = "action" | "loader" | "pe-form";
+
+/**
+ * Context passed to the originCheck callback.
+ */
+export interface OriginCheckContext<TEnv = any> {
+  request: Request;
+  url: URL;
+  env: TEnv;
+  routerId: string;
+  phase: OriginCheckPhase;
+  /** Run the built-in conservative check (Origin/Referer vs Host + url.protocol). */
+  defaultCheck: () => boolean;
+}
+
+/**
+ * Configuration for the origin check.
+ *
+ * - `true` (default) — built-in conservative check
+ * - `false` — disabled
+ * - function — custom control; return true to allow, false to reject with
+ *   default 403, or a Response for custom rejection
+ */
+export type OriginCheckConfig<TEnv = any> =
+  | boolean
+  | ((
+      ctx: OriginCheckContext<TEnv>,
+    ) => boolean | Response | Promise<boolean | Response>);
+
+/**
+ * Built-in conservative origin check.
+ * Compares Origin (or Referer fallback) against Host + url.protocol.
+ * Does NOT trust X-Forwarded-Host/Proto headers.
+ *
+ * Returns true to allow, false to reject.
+ */
+export function defaultOriginCheck(request: Request, url: URL): boolean {
+  // 1. Read Origin header (present on all cross-origin requests and
+  //    same-origin POST/PUT/PATCH/DELETE in modern browsers)
+  let requestOrigin = request.headers.get("origin");
+
+  // 2. Fallback to Referer if Origin is absent (some proxies strip it)
+  if (!requestOrigin) {
+    const referer = request.headers.get("referer");
+    if (referer) {
+      try {
+        requestOrigin = new URL(referer).origin;
+      } catch {
+        // Malformed referer — treat as absent
+      }
+    }
+  }
+
+  // 3. No Origin or Referer — allow (can't be browser-initiated CSRF)
+  if (!requestOrigin) return true;
+
+  // "null" origin comes from privacy-sensitive contexts (data: URLs,
+  // sandboxed iframes, cross-origin redirects). Reject it.
+  if (requestOrigin === "null") return false;
+
+  // 4. Determine expected host from Host header or URL.
+  // X-Forwarded-Host/Proto are NOT used — they are client-controllable
+  // unless a trusted proxy strips them. On standard deployments (Cloudflare
+  // Workers, Node behind nginx/caddy) the Host header is already correct.
+  // For non-standard setups, use the custom function escape hatch.
+  const expectedHost = request.headers.get("host") || url.host;
+  const expectedProtocol = url.protocol;
+
+  // 5. Build expected origin and compare (case-insensitive)
+  const expectedOrigin = `${expectedProtocol}//${expectedHost}`;
+
+  return requestOrigin.toLowerCase() === expectedOrigin.toLowerCase();
+}
+
+function createForbiddenResponse(request: Request): Response {
+  const isDev = process.env.NODE_ENV !== "production";
+  const body = isDev
+    ? "Forbidden: Origin mismatch. The request origin does not match the server host. " +
+      `Set originCheck: false in createRouter() to disable this check. ` +
+      `(Origin: ${request.headers.get("origin") ?? "none"}, ` +
+      `Host: ${request.headers.get("host") ?? "none"})`
+    : "Forbidden";
+
+  return new Response(body, {
+    status: 403,
+    headers: { "X-Rango-Origin-Check": "failed" },
+  });
+}
+
+/**
+ * Configuration-aware origin check dispatcher.
+ * Builds the OriginCheckContext and delegates to the configured check.
+ */
+export async function checkRequestOrigin<TEnv = any>(
+  request: Request,
+  url: URL,
+  config: OriginCheckConfig<TEnv> | undefined,
+  env: TEnv,
+  routerId: string,
+  phase: OriginCheckPhase,
+): Promise<Response | null> {
+  // 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);
+  }
+
+  // Custom function — build context and call
+  const ctx: OriginCheckContext<TEnv> = {
+    request,
+    url,
+    env,
+    routerId,
+    phase,
+    defaultCheck: () => defaultOriginCheck(request, url),
+  };
+
+  const result = await config(ctx);
+
+  if (result instanceof Response) return result;
+  if (result === true) return null;
+  return createForbiddenResponse(request);
+}