@rangojs/router 0.0.0-experimental.15 → 0.0.0-experimental.151

package/src/rsc/index.ts

@@ -1,5 +1,5 @@
 /**
- * RSC Router - RSC Entry Point
+ * Rango - RSC Entry Point
  *
  * This module provides RSC utilities for server-side rendering,
  * server actions, loader fetching, and progressive enhancement.
@@ -29,28 +29,5 @@ export type {
   NonceProvider,
 } from "./types.js";
 
-// Re-export HandleStore types for consumers who need custom handling
-export {
-  createHandleStore,
-  type HandleStore,
-  type HandleData,
-} from "../server/handle-store.js";
-
 // Re-export request context utilities for server-side access to env/request/params
-export {
-  getRequestContext,
-  requireRequestContext,
-  setRequestContextParams,
-} from "../server/request-context.js";
-
-// Re-export cache store types and implementations
-export type {
-  SegmentCacheStore,
-  CachedEntryData,
-  CachedEntryResult,
-  SegmentCacheProvider,
-  SegmentHandleData,
-} from "../cache/types.js";
-
-export { MemorySegmentCacheStore } from "../cache/memory-segment-store.js";
-export { CFCacheStore, type CFCacheStoreOptions } from "../cache/cf/index.js";
+export { getRequestContext } from "../server/request-context.js";

package/src/rsc/json-route-result.ts

@@ -0,0 +1,38 @@
+/**
+ * Shared serialization for `json()` response-route results.
+ *
+ * Kept in its own lightweight module (depends only on `errors.js`) so the
+ * `dispatch()` testing primitive can import it WITHOUT dragging in
+ * `response-route-handler.ts`'s heavy runtime graph, which transitively reaches
+ * a Vite virtual module and breaks a plain (non-Vite) vitest import.
+ */
+
+import { RouterError } from "../errors.js";
+
+/**
+ * Serialize a `json()` response-route result, rejecting a nested unresolved
+ * Promise (the forgotten-await footgun: `() => ({ data: fetchSomething() })`).
+ * `JSON.stringify` would silently emit `{}` for a Promise, shipping empty data;
+ * the RSC pipeline awaits nested promises but this path does not. Throwing
+ * `RESPONSE_NOT_SERIALIZABLE` makes the failure loud.
+ *
+ * Shared by the production response-route handler and the `dispatch()` testing
+ * primitive so a `dispatch` json test of a forgotten await fails exactly where
+ * production 500s, instead of going green.
+ */
+export function stringifyJsonRouteResult(result: unknown): string {
+  return JSON.stringify(result, (_key, value) => {
+    if (
+      value != null &&
+      typeof (value as { then?: unknown }).then === "function"
+    ) {
+      throw new RouterError(
+        "RESPONSE_NOT_SERIALIZABLE",
+        "A json() response route returned a Promise (likely a forgotten " +
+          "await). Await async values before returning so they serialize, " +
+          "instead of emitting an empty {}.",
+      );
+    }
+    return value;
+  });
+}

package/src/rsc/loader-fetch.ts

@@ -0,0 +1,305 @@
+/**
+ * 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 { DataNotFoundError } from "../errors.js";
+import { executeLoaderMiddleware } from "../router/middleware.js";
+import { getRequestContext } from "../server/request-context.js";
+import { observePhase, PHASES } from "../router/instrument.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";
+
+/**
+ * Build the 500 RSC error Response for a failed fetchable loader. Shared by the
+ * module-load-error catch (the import itself threw) and the loader-execution
+ * error catch — both call onError("loader"), serialize the same dev-gated error
+ * payload via renderToReadableStream (reporting render failures through
+ * onError("rendering")), and return a 500 text/x-component Response. The only
+ * per-site difference is the console.error label, passed in.
+ */
+function buildLoaderErrorResponse<TEnv>(
+  ctx: HandlerContext<TEnv>,
+  error: unknown,
+  meta: { request: Request; url: URL; env: TEnv; loaderId: string },
+  logLabel: string,
+): Response {
+  const { request, url, env, loaderId } = meta;
+  const isDev = process.env.NODE_ENV !== "production";
+
+  console.error(logLabel, error);
+
+  ctx.callOnError(error, "loader", {
+    request,
+    url,
+    env,
+    loaderName: loaderId,
+    handledByBoundary: false,
+  });
+
+  const err = error instanceof Error ? error : new Error(String(error));
+  const errorPayload = {
+    loaderResult: null,
+    loaderError: {
+      message: isDev ? err.message : "An error occurred",
+      // Gate err.name to dev. In production it leaks the consumer's error class
+      // name (e.g. AuthError, PrismaClientKnownRequestError) to the client; the
+      // client only ever reads `message`, so the field is dead data outside dev.
+      // Matches sanitizeError's dev-only name contract.
+      name: isDev ? err.name : "Error",
+    },
+  };
+  const rscStream = ctx.renderToReadableStream(errorPayload, {
+    onError: (renderError: unknown) => {
+      ctx.callOnError(renderError, "rendering", {
+        request,
+        url,
+        env,
+        loaderName: loaderId,
+      });
+    },
+  });
+
+  return createResponseWithMergedHeaders(rscStream, {
+    status: 500,
+    headers: { "content-type": "text/x-component;charset=utf-8" },
+  });
+}
+
+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. getLoaderLazy returns undefined only when the id was
+  // never registered (genuine 404). A thrown error means the loader module
+  // EXISTS but its import failed (broken transitive import, syntax error, throw
+  // in top-level code) — a real server breakage that must surface as a 500 and
+  // fire onError, not be collapsed into a misleading "not found".
+  let registeredLoader;
+  try {
+    registeredLoader = await getLoaderLazy(loaderId);
+  } catch (error) {
+    return buildLoaderErrorResponse(
+      ctx,
+      error,
+      { request, url, env, loaderId },
+      `[RSC] Loader module load failed for "${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 = getRequestContext();
+          // 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 } : {}),
+          };
+
+          // Meter the fetchable-loader execution via observePhase, the sole
+          // funnel for this path (fn is called directly, not via ctx.use).
+          // depth:1 — a fetchable request has no render-phase parent.
+          const result = await observePhase(PHASES.loader(loaderId, 1), () =>
+            fn(loaderCtx),
+          );
+
+          interface LoaderPayload {
+            loaderResult: unknown;
+          }
+          const loaderPayload: LoaderPayload = { loaderResult: result };
+          const rscStream = ctx.renderToReadableStream<LoaderPayload>(
+            loaderPayload,
+            {
+              onError: (error: unknown) => {
+                ctx.callOnError(error, "rendering", {
+                  request,
+                  url,
+                  env,
+                  loaderName: loaderId,
+                });
+              },
+            },
+          );
+
+          return createResponseWithMergedHeaders(rscStream, {
+            headers: { "content-type": "text/x-component;charset=utf-8" },
+          });
+        },
+        createReverseFunction(ctx.getRequiredRouteMap()),
+      ),
+    );
+  } catch (error) {
+    // A thrown Response is control flow, not an error: `throw redirect('/x')`
+    // throws a real Response (a 3xx). The with-middleware path already converts
+    // this to a returned Response (middleware.ts: `if (error instanceof Response)
+    // result = error`), but a fetchable loader with NO middleware reaches this
+    // catch directly, where the generic Error coercion below would turn it into a
+    // 500. Honor it the same way: re-wrap through createResponseWithMergedHeaders
+    // so the request context's stub cookies/headers merge, exactly like the
+    // returned-Response path. Mirrors rsc/handler.ts's `error instanceof Response`
+    // special-case.
+    if (error instanceof Response) {
+      return finalizeResponse(
+        createResponseWithMergedHeaders(error.body, {
+          status: error.status,
+          headers: error.headers,
+        }),
+      );
+    }
+
+    // notFound() throws a DataNotFoundError (an Error subclass, NOT a Response),
+    // so it does not match the branch above. Map it to a 404 before the generic
+    // 500 coercion so a no-middleware fetchable loader's notFound() is honored
+    // (the with-middleware path resolves it through the notFoundBoundary).
+    if (error instanceof DataNotFoundError) {
+      return finalizeResponse(
+        createResponseWithMergedHeaders(null, { status: 404 }),
+      );
+    }
+
+    return buildLoaderErrorResponse(
+      ctx,
+      error,
+      { request, url, env, loaderId },
+      "[RSC] Loader error:",
+    );
+  }
+}

package/src/rsc/manifest-init.ts

@@ -0,0 +1,77 @@
+/**
+ * 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,
+  setRouterPrecomputedEntries,
+} 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 = await generateManifestFull(
+    router.urlpatterns,
+    undefined,
+    router.basename ? { urlPrefix: router.basename } : undefined,
+  );
+  // Build the trie through the SAME shared helper the production discovery uses
+  // (discover-routers.ts), so the dev runtime-rebuilt trie and the prod
+  // serialized trie cannot drift. buildPerRouterTrie returns null when there
+  // are no routes.
+  const { buildPerRouterTrie } = await import("../build/route-trie.js");
+  const trie = buildPerRouterTrie(generated);
+  if (trie) {
+    setRouterTrie(router.id, trie);
+    // Set global trie only if not already set by another router
+    if (!getRouteTrie()) {
+      setRouteTrie(trie);
+    }
+  }
+  setRouterManifest(router.id, generated.routeManifest);
+
+  // Match the production discovery path: precompute leaf-include entries so the
+  // match-time shortcut in evaluateLazyEntry applies in dev/Cloudflare too.
+  // Without this, dev re-runs each matched leaf include's handler at match time
+  // (evaluateLazyEntry) AND again at render time (loadManifest); with it, the
+  // match-time run is skipped and the handler runs once per first request.
+  // Identical route ownership to the handler path (the shortcut is guarded by
+  // the same prefixIsShared and #506 checks production uses).
+  const { flattenLeafEntries } = await import("../build/prefix-tree-utils.js");
+  const precomputed: Array<{
+    staticPrefix: string;
+    routes: Record<string, string>;
+  }> = [];
+  flattenLeafEntries(
+    generated.prefixTree,
+    generated.routeManifest,
+    precomputed,
+  );
+  setRouterPrecomputedEntries(router.id, precomputed);
+
+  // Merge into global manifest (needed for reverse/href across routers)
+  const existing = hasCachedManifest() ? getGlobalRouteMap() : {};
+  setCachedManifest({ ...existing, ...generated.routeManifest });
+}

package/src/rsc/nonce.ts

@@ -2,6 +2,29 @@
  * 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 READ the nonce in middleware or handlers:
+ * ```ts
+ * import { nonce } from "@rangojs/router";
+ * const value = ctx.get(nonce); // string | undefined
+ * ```
+ *
+ * Supply the nonce via the `createRouter({ nonce })` provider, not by writing
+ * this token yourself. The provider value is threaded into the router's SSR
+ * machinery (NonceContext/useNonce, Scripts/MetaTags attributes, the inlined
+ * Flight payload scripts) AND sets this token. A direct `ctx.set(nonce, value)`
+ * in middleware runs AFTER the SSR nonce is resolved: the value is readable via
+ * `ctx.get(nonce)` and gates PPR shell capture (a per-request nonce must never
+ * bake into a shared shell), but the router will not apply it to its own
+ * scripts — useNonce() stays undefined for that request.
+ */
+export const nonce: ContextVar<string> = createVar<string>();
+
 /**
  * Generate a cryptographic nonce for CSP.
  * Returns a 16-byte random value encoded as base64.

package/src/rsc/origin-guard.ts

@@ -0,0 +1,155 @@
+/**
+ * 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.
+ */
+
+import type { RequestPlan } from "../router/request-classification.js";
+
+/**
+ * Request phase that triggered the origin check.
+ */
+export type OriginCheckPhase = "action" | "loader" | "pe-form";
+
+// Exhaustive over RequestPlan modes so a new mode must be classified here (the
+// security gate) instead of silently falling through to no origin check.
+export const ORIGIN_CHECK_PHASE_BY_MODE: Record<
+  RequestPlan["mode"],
+  OriginCheckPhase | null
+> = {
+  action: "action",
+  loader: "loader",
+  "pe-render": "pe-form",
+  "full-render": null,
+  "partial-render": null,
+  response: null,
+  redirect: null,
+  "version-mismatch": null,
+  // Terminal: handled before the origin guard (emits X-RSC-Reload, no execution).
+  "app-switch": null,
+};
+
+/**
+ * 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 {
+  let requestOrigin = request.headers.get("origin");
+
+  if (!requestOrigin) {
+    const referer = request.headers.get("referer");
+    if (referer) {
+      try {
+        requestOrigin = new URL(referer).origin;
+      } catch {
+        // Malformed referer — treat as absent
+      }
+    }
+  }
+
+  if (!requestOrigin) return true;
+
+  if (requestOrigin === "null") return false;
+
+  // An Origin/Referer is present, so this is a browser request worth checking.
+  // Establish the expected origin from the Host header only -- browsers always
+  // send Host alongside Origin (runtimes synthesize it from the HTTP/2
+  // :authority), so a missing Host here is anomalous. Fail closed rather than
+  // fall back to url.host (derived from the request line) when the trusted Host
+  // cannot be established.
+  const expectedHost = request.headers.get("host");
+  if (!expectedHost) return false;
+
+  const expectedOrigin = `${url.protocol}//${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 (true/undefined) becomes a callback returning boolean, so the
+  // Response|true|reject resolution below is written once.
+  const check: (
+    ctx: OriginCheckContext<TEnv>,
+  ) => boolean | Response | Promise<boolean | Response> =
+    config === true || config === undefined
+      ? () => defaultOriginCheck(request, url)
+      : config;
+
+  const ctx: OriginCheckContext<TEnv> = {
+    request,
+    url,
+    env,
+    routerId,
+    phase,
+    defaultCheck: () => defaultOriginCheck(request, url),
+  };
+
+  const result = await check(ctx);
+
+  if (result instanceof Response) return result;
+  return result === true ? null : createForbiddenResponse(request);
+}