@rangojs/router 0.0.0-experimental.3 → 0.0.0-experimental.30

package/src/errors.ts

@@ -22,6 +22,7 @@ export class RouteNotFoundError extends Error {
 
   constructor(message: string, options?: ErrorOptions) {
     super(message);
+    Object.setPrototypeOf(this, RouteNotFoundError.prototype);
     this.cause = options?.cause;
   }
 }
@@ -45,6 +46,7 @@ export class DataNotFoundError extends Error {
 
   constructor(message: string = "Not found", options?: ErrorOptions) {
     super(message);
+    Object.setPrototypeOf(this, DataNotFoundError.prototype);
     this.cause = options?.cause;
   }
 }
@@ -74,6 +76,7 @@ export class MiddlewareError extends Error {
 
   constructor(message: string, options?: ErrorOptions) {
     super(message);
+    Object.setPrototypeOf(this, MiddlewareError.prototype);
     this.cause = options?.cause;
   }
 }
@@ -87,6 +90,7 @@ export class HandlerError extends Error {
 
   constructor(message: string, options?: ErrorOptions) {
     super(message);
+    Object.setPrototypeOf(this, HandlerError.prototype);
     this.cause = options?.cause;
   }
 }
@@ -100,6 +104,7 @@ export class BuildError extends Error {
 
   constructor(message: string, options?: ErrorOptions) {
     super(message);
+    Object.setPrototypeOf(this, BuildError.prototype);
     this.cause = options?.cause;
   }
 }
@@ -133,9 +138,10 @@ export class NetworkError extends Error {
     options?: ErrorOptions & {
       url?: string;
       operation?: "action" | "navigation" | "revalidation";
-    }
+    },
   ) {
     super(message);
+    Object.setPrototypeOf(this, NetworkError.prototype);
     this.cause = options?.cause;
     this.url = options?.url;
     this.operation = options?.operation;
@@ -171,6 +177,100 @@ export function isNetworkError(error: unknown): boolean {
   return false;
 }
 
+/**
+ * Structured error for JSON response routes.
+ * Thrown by handlers to return a typed error envelope with a specific HTTP status.
+ *
+ * Unlike standard Error, RouterError messages are always exposed to the client
+ * (the developer intentionally crafted them for consumers).
+ *
+ * @example
+ * ```typescript
+ * path("/products/:id", (ctx) => {
+ *   const product = products.find(p => p.id === ctx.params.id);
+ *   if (!product) throw new RouterError("NOT_FOUND", "Product not found", { status: 404 });
+ *   return product;
+ * }, { name: "productDetail" })
+ * ```
+ */
+export class RouterError extends Error {
+  name = "RouterError" as const;
+  code: string;
+  type?: string;
+  status: number;
+  cause?: unknown;
+
+  constructor(
+    code: string,
+    message: string,
+    options?: {
+      status?: number;
+      type?: string;
+      cause?: unknown;
+    },
+  ) {
+    super(message);
+    Object.setPrototypeOf(this, RouterError.prototype);
+    this.code = code;
+    this.status = options?.status ?? 500;
+    this.type = options?.type;
+    this.cause = options?.cause;
+  }
+}
+
+/**
+ * Thrown inside a Prerender or Static handler at build time to signal
+ * "skip this entry, log it, and continue with the rest."
+ *
+ * When thrown, the entry is excluded from the pre-render manifest
+ * but the build continues normally. Regular throws (non-Skip)
+ * stop all further pre-rendering and fail the build.
+ *
+ * @example
+ * ```typescript
+ * export const BlogPost = Prerender(
+ *   async () => allPosts.map(p => ({ slug: p.slug })),
+ *   async (ctx) => {
+ *     const post = await getPost(ctx.params.slug);
+ *     if (post.draft) throw new Skip(`"${ctx.params.slug}" is a draft`);
+ *     return <PostPage post={post} />;
+ *   },
+ * );
+ * ```
+ */
+export class Skip extends Error {
+  name = "Skip" as const;
+  cause?: unknown;
+
+  constructor(message: string = "Entry skipped", options?: ErrorOptions) {
+    super(message);
+    Object.setPrototypeOf(this, Skip.prototype);
+    this.cause = options?.cause;
+  }
+}
+
+/**
+ * Type guard to check if a thrown value is a Skip signal.
+ */
+export function isSkip(value: unknown): value is Skip {
+  return value instanceof Skip;
+}
+
+/**
+ * Thrown by the partial updater when the server responds with a redirect payload
+ * that carries location state. Caught by navigate() to re-navigate to the
+ * redirect target with the server-set state merged into history.pushState.
+ *
+ * Not an Error subclass -- this is a control flow signal, not a failure.
+ */
+export class ServerRedirect {
+  readonly name = "ServerRedirect";
+  constructor(
+    public readonly url: string,
+    public readonly state: Record<string, unknown> | undefined,
+  ) {}
+}
+
 /**
  * Thrown when route handler returns invalid type
  */
@@ -180,6 +280,7 @@ export class InvalidHandlerError extends Error {
 
   constructor(message: string, options?: ErrorOptions) {
     super(message);
+    Object.setPrototypeOf(this, InvalidHandlerError.prototype);
     this.cause = options?.cause;
   }
 }
@@ -226,7 +327,12 @@ export function sanitizeError(error: unknown): Response {
     return error;
   }
 
-  const isDev = (import.meta as any).env?.DEV ?? true;
+  // Vite replaces import.meta.env.DEV at compile time. The fallback covers
+  // non-Vite environments (plain Node, test runners without Vite transforms).
+  // SECURITY: fail closed — default to production when the environment is ambiguous.
+  const isDev =
+    (import.meta as any).env?.DEV ??
+    globalThis.process?.env?.NODE_ENV === "development";
 
   if (isDev) {
     // Development: Send full error details for debugging

package/src/handle.ts

@@ -29,16 +29,6 @@ export interface Handle<TData, TAccumulated = TData[]> {
    * Format: "filePath#ExportName" in dev, "hash#ExportName" in production
    */
   readonly $$id: string;
-
-  /**
-   * Collect function to transform segment data into final value.
-   * Receives array of arrays - each inner array contains values pushed
-   * by one segment, ordered parent-to-child.
-   *
-   * @param segments - Array of segment data arrays, e.g. [[a, b], [c], [d, e]]
-   * @returns The accumulated value
-   */
-  readonly collect: (segments: TData[][]) => TAccumulated;
 }
 
 /**
@@ -48,10 +38,25 @@ function defaultCollect<T>(segments: T[][]): T[] {
   return segments.flat();
 }
 
+// Module-level registry mapping $$id to collect functions.
+// Populated when createHandle() runs (both server and client).
+// Used by useHandle() to recover collect when handle is deserialized from RSC prop.
+const collectRegistry = new Map<string, (segments: unknown[][]) => unknown>();
+
+/**
+ * Look up a collect function from the registry by handle $$id.
+ * Returns undefined if not registered (falls back to defaultCollect in useHandle).
+ */
+export function getCollectFn(
+  id: string,
+): ((segments: unknown[][]) => unknown) | undefined {
+  return collectRegistry.get(id);
+}
+
 /**
  * Create a handle definition for accumulating data across route segments.
  *
- * The $$id is auto-generated by the Vite exposeHandleId plugin based on
+ * The $$id is auto-generated by the Vite exposeInternalIds plugin based on
  * file path and export name. No manual naming required.
  *
  * @param collect - Optional collect function (default: flatten into array)
@@ -86,24 +91,34 @@ function defaultCollect<T>(segments: T[][]): T[] {
  */
 export function createHandle<TData, TAccumulated = TData[]>(
   collect?: (segments: TData[][]) => TAccumulated,
-  __injectedId?: string
+  __injectedId?: string,
 ): Handle<TData, TAccumulated> {
   const handleId = __injectedId ?? "";
 
-  if (!handleId && process.env.NODE_ENV !== "production") {
-    console.warn(
+  if (!handleId && process.env.NODE_ENV === "development") {
+    throw new Error(
       "[rsc-router] Handle is missing $$id. " +
-        "Make sure the exposeHandleId Vite plugin is enabled and " +
-        "the handle is exported with: export const MyHandle = createHandle(...)"
+        "Make sure the exposeInternalIds Vite plugin is enabled and " +
+        "the handle is exported with: export const MyHandle = createHandle(...)",
+    );
+  }
+
+  const collectFn =
+    collect ??
+    (defaultCollect as unknown as (segments: TData[][]) => TAccumulated);
+
+  // Register collect in module-level registry so useHandle() can recover it
+  // when the handle is deserialized from RSC props (toJSON strips collect).
+  if (handleId) {
+    collectRegistry.set(
+      handleId,
+      collectFn as (segments: unknown[][]) => unknown,
     );
   }
 
   return {
     __brand: "handle" as const,
     $$id: handleId,
-    collect:
-      collect ??
-      (defaultCollect as unknown as (segments: TData[][]) => TAccumulated),
   };
 }
 

package/src/handles/MetaTags.tsx

@@ -28,8 +28,9 @@ import { use } from "react";
 import { useHandle } from "../browser/react/use-handle.js";
 import { Meta } from "./meta.js";
 import type { MetaDescriptor, MetaDescriptorBase } from "../router/types.js";
-import { getSSRThemeConfig } from "../theme/theme-context.js";
+import { useThemeContext } from "../theme/theme-context.js";
 import { generateThemeScript } from "../theme/theme-script.js";
+import { useNonce } from "../browser/react/nonce-context.js";
 
 // Type guards for MetaDescriptorBase variants
 function hasCharSet(d: MetaDescriptorBase): d is { charSet: "utf-8" } {
@@ -40,30 +41,53 @@ function hasTitle(d: MetaDescriptorBase): d is { title: string } {
   return "title" in d && typeof (d as { title?: unknown }).title === "string";
 }
 
-function hasNameContent(d: MetaDescriptorBase): d is { name: string; content: string } {
-  return "name" in d && "content" in d &&
+function hasNameContent(
+  d: MetaDescriptorBase,
+): d is { name: string; content: string } {
+  return (
+    "name" in d &&
+    "content" in d &&
     typeof (d as { name?: unknown }).name === "string" &&
-    typeof (d as { content?: unknown }).content === "string";
+    typeof (d as { content?: unknown }).content === "string"
+  );
 }
 
-function hasPropertyContent(d: MetaDescriptorBase): d is { property: string; content: string } {
-  return "property" in d && "content" in d &&
+function hasPropertyContent(
+  d: MetaDescriptorBase,
+): d is { property: string; content: string } {
+  return (
+    "property" in d &&
+    "content" in d &&
     typeof (d as { property?: unknown }).property === "string" &&
-    typeof (d as { content?: unknown }).content === "string";
+    typeof (d as { content?: unknown }).content === "string"
+  );
 }
 
-function hasHttpEquivContent(d: MetaDescriptorBase): d is { httpEquiv: string; content: string } {
-  return "httpEquiv" in d && "content" in d &&
+function hasHttpEquivContent(
+  d: MetaDescriptorBase,
+): d is { httpEquiv: string; content: string } {
+  return (
+    "httpEquiv" in d &&
+    "content" in d &&
     typeof (d as { httpEquiv?: unknown }).httpEquiv === "string" &&
-    typeof (d as { content?: unknown }).content === "string";
+    typeof (d as { content?: unknown }).content === "string"
+  );
 }
 
-function hasScriptLdJson(d: MetaDescriptorBase): d is { "script:ld+json": object } {
+function hasScriptLdJson(
+  d: MetaDescriptorBase,
+): d is { "script:ld+json": object } {
   return "script:ld+json" in d;
 }
 
-function hasTagName(d: MetaDescriptorBase): d is { tagName: "meta" | "link"; [name: string]: string } {
-  return "tagName" in d && ((d as { tagName?: unknown }).tagName === "meta" || (d as { tagName?: unknown }).tagName === "link");
+function hasTagName(
+  d: MetaDescriptorBase,
+): d is { tagName: "meta" | "link"; [name: string]: string } {
+  return (
+    "tagName" in d &&
+    ((d as { tagName?: unknown }).tagName === "meta" ||
+      (d as { tagName?: unknown }).tagName === "link")
+  );
 }
 
 /**
@@ -78,7 +102,7 @@ function isPromise(value: unknown): value is Promise<unknown> {
  */
 function renderMetaDescriptor(
   descriptor: MetaDescriptorBase,
-  index: number
+  index: number,
 ): React.ReactNode {
   // charset
   if (hasCharSet(descriptor)) {
@@ -139,21 +163,42 @@ function renderMetaDescriptor(
   if (hasTagName(descriptor)) {
     const { tagName, ...rest } = descriptor;
     if (tagName === "link") {
-      return <link key={`link-${index}`} {...(rest as React.LinkHTMLAttributes<HTMLLinkElement>)} />;
+      return (
+        <link
+          key={`link-${index}`}
+          {...(rest as React.LinkHTMLAttributes<HTMLLinkElement>)}
+        />
+      );
     }
     if (tagName === "meta") {
-      return <meta key={`meta-${index}`} {...(rest as React.MetaHTMLAttributes<HTMLMetaElement>)} />;
+      return (
+        <meta
+          key={`meta-${index}`}
+          {...(rest as React.MetaHTMLAttributes<HTMLMetaElement>)}
+        />
+      );
     }
   }
 
   // Fallback: treat as meta attributes
-  return <meta key={`meta-fallback-${index}`} {...(descriptor as React.MetaHTMLAttributes<HTMLMetaElement>)} />;
+  return (
+    <meta
+      key={`meta-fallback-${index}`}
+      {...(descriptor as React.MetaHTMLAttributes<HTMLMetaElement>)}
+    />
+  );
 }
 
 /**
  * Wrapper component to resolve a Promise<MetaDescriptorBase> using use().
  */
-function AsyncMetaTag({ promise, index }: { promise: Promise<MetaDescriptorBase>; index: number }): React.ReactNode {
+function AsyncMetaTag({
+  promise,
+  index,
+}: {
+  promise: Promise<MetaDescriptorBase>;
+  index: number;
+}): React.ReactNode {
   const resolved = use(promise);
   return renderMetaDescriptor(resolved, index);
 }
@@ -172,19 +217,27 @@ function AsyncMetaTag({ promise, index }: { promise: Promise<MetaDescriptorBase>
  */
 export function MetaTags(): React.ReactNode {
   const descriptors = useHandle(Meta) as MetaDescriptor[];
-  const themeConfig = getSSRThemeConfig();
+  const themeConfig = useThemeContext()?.config ?? null;
+  const nonce = useNonce();
 
   return (
     <>
       {/* Theme script must be first to prevent FOUC */}
       {themeConfig && (
         <script
+          nonce={nonce}
           dangerouslySetInnerHTML={{ __html: generateThemeScript(themeConfig) }}
         />
       )}
       {descriptors.map((descriptor, index) => {
         if (isPromise(descriptor)) {
-          return <AsyncMetaTag key={`async-${index}`} promise={descriptor} index={index} />;
+          return (
+            <AsyncMetaTag
+              key={`async-${index}`}
+              promise={descriptor}
+              index={index}
+            />
+          );
         }
         return renderMetaDescriptor(descriptor, index);
       })}

package/src/handles/meta.ts

@@ -39,7 +39,7 @@ import type {
  * Type guard for unset descriptor
  */
 function isUnsetDescriptor(
-  descriptor: MetaDescriptor
+  descriptor: MetaDescriptor,
 ): descriptor is UnsetDescriptor {
   return (
     typeof descriptor === "object" &&
@@ -53,7 +53,7 @@ function isUnsetDescriptor(
  * Type guard for title descriptor (any form)
  */
 function isTitleDescriptor(
-  descriptor: MetaDescriptor
+  descriptor: MetaDescriptor,
 ): descriptor is { title: TitleDescriptor } {
   return (
     typeof descriptor === "object" &&
@@ -66,7 +66,7 @@ function isTitleDescriptor(
  * Type guard for title template descriptor
  */
 function isTitleTemplate(
-  title: TitleDescriptor
+  title: TitleDescriptor,
 ): title is { template: string; default: string } {
   return (
     typeof title === "object" &&
@@ -79,7 +79,9 @@ function isTitleTemplate(
 /**
  * Type guard for absolute title descriptor
  */
-function isAbsoluteTitle(title: TitleDescriptor): title is { absolute: string } {
+function isAbsoluteTitle(
+  title: TitleDescriptor,
+): title is { absolute: string } {
   return typeof title === "object" && title !== null && "absolute" in title;
 }
 
@@ -141,7 +143,7 @@ function addOrReplace(
   result: MetaDescriptor[],
   keyToIndex: Map<string, number>,
   descriptor: MetaDescriptor,
-  key: string | undefined
+  key: string | undefined,
 ): void {
   if (key !== undefined && keyToIndex.has(key)) {
     result[keyToIndex.get(key)!] = descriptor;
@@ -158,7 +160,7 @@ function addOrReplace(
  */
 function updateIndicesAfterRemoval(
   keyToIndex: Map<string, number>,
-  removedIndex: number
+  removedIndex: number,
 ): void {
   for (const [key, index] of keyToIndex) {
     if (index > removedIndex) {
@@ -208,13 +210,23 @@ function collectMeta(segments: MetaDescriptor[][]): MetaDescriptor[] {
           // Store template for subsequent title descriptors in child segments
           titleTemplate = titleValue.template;
           // Set the default title
-          addOrReplace(result, keyToIndex, { title: titleValue.default }, "title");
+          addOrReplace(
+            result,
+            keyToIndex,
+            { title: titleValue.default },
+            "title",
+          );
           continue;
         }
 
         if (isAbsoluteTitle(titleValue)) {
           // Absolute title bypasses any template
-          addOrReplace(result, keyToIndex, { title: titleValue.absolute }, "title");
+          addOrReplace(
+            result,
+            keyToIndex,
+            { title: titleValue.absolute },
+            "title",
+          );
           continue;
         }
 
@@ -222,7 +234,12 @@ function collectMeta(segments: MetaDescriptor[][]): MetaDescriptor[] {
         const finalTitle = titleTemplate
           ? titleTemplate.replace("%s", titleValue as string)
           : titleValue;
-        addOrReplace(result, keyToIndex, { title: finalTitle as string }, "title");
+        addOrReplace(
+          result,
+          keyToIndex,
+          { title: finalTitle as string },
+          "title",
+        );
         continue;
       }
 
@@ -241,7 +258,7 @@ function collectMeta(segments: MetaDescriptor[][]): MetaDescriptor[] {
  * Use `ctx.use(Meta)` in route handlers to push meta descriptors.
  * Use `<MetaTags />` component to render them in the document head.
  */
-export const Meta: Handle<MetaDescriptor, MetaDescriptor[]> = createHandle<MetaDescriptor, MetaDescriptor[]>(
-  collectMeta,
-  "__rsc_router_meta__"
-);
+export const Meta: Handle<MetaDescriptor, MetaDescriptor[]> = createHandle<
+  MetaDescriptor,
+  MetaDescriptor[]
+>(collectMeta, "__rsc_router_meta__");

package/src/host/cookie-handler.ts

@@ -0,0 +1,165 @@
+/**
+ * Cookie Override Handler
+ *
+ * Manages cookie-based host override for development environments.
+ */
+
+import type { HostOverrideConfig } from "./types.js";
+import type { RouterRequestInput } from "../router/router-interfaces.js";
+import { matchPattern, parseRequest } from "./pattern-matcher.js";
+import {
+  HostOverrideNotAllowedError,
+  InvalidHostnameError,
+  HostValidationError,
+} from "./errors.js";
+
+/**
+ * Parse cookies from request
+ */
+export function parseCookies(request: Request): Record<string, string> {
+  const cookieHeader = request.headers.get("cookie");
+  if (!cookieHeader) {
+    return {};
+  }
+
+  const cookies: Record<string, string> = {};
+  const pairs = cookieHeader.split(";");
+
+  for (const pair of pairs) {
+    const [name, ...rest] = pair.trim().split("=");
+    if (name && rest.length > 0) {
+      const value = rest.join("=");
+      try {
+        cookies[name] = decodeURIComponent(value);
+      } catch {
+        cookies[name] = value;
+      }
+    }
+  }
+
+  return cookies;
+}
+
+/**
+ * Get cookie value from request
+ */
+export function getCookie(request: Request, name: string): string | undefined {
+  const cookies = parseCookies(request);
+  return cookies[name];
+}
+
+/**
+ * Create Set-Cookie header to delete a cookie
+ */
+export function createDeleteCookieHeader(name: string): string {
+  return `${name}=; Max-Age=0; Path=/; Secure; HttpOnly`;
+}
+
+/**
+ * Create error response with cookie deletion
+ */
+export function createCookieErrorResponse(
+  cookieName: string,
+  message: string,
+): Response {
+  return new Response(
+    JSON.stringify({
+      error: message,
+      message: `The ${cookieName} cookie has been cleared`,
+    }),
+    {
+      status: 400,
+      headers: {
+        "Content-Type": "application/json",
+        "Set-Cookie": createDeleteCookieHeader(cookieName),
+      },
+    },
+  );
+}
+
+/**
+ * Check if current host is allowed to use override
+ */
+export function isHostAllowed(
+  request: Request,
+  allowedHosts: string[],
+): boolean {
+  const { hostname, pathname, parts } = parseRequest(request);
+
+  for (const pattern of allowedHosts) {
+    if (matchPattern(pattern, hostname, pathname, parts)) {
+      return true;
+    }
+  }
+
+  return false;
+}
+
+/**
+ * Handle cookie override logic
+ *
+ * Returns overridden hostname if valid, original hostname if no override.
+ * Throws errors for invalid overrides.
+ */
+export function handleCookieOverride(
+  request: Request,
+  config: HostOverrideConfig | undefined,
+  input: RouterRequestInput<any>,
+): string {
+  if (!config) {
+    const { hostname } = parseRequest(request);
+    return hostname;
+  }
+
+  const { cookieName, allowedHosts, validate } = config;
+  const cookieValue = getCookie(request, cookieName);
+  const { hostname: originalHostname } = parseRequest(request);
+
+  // No cookie - return original hostname
+  if (!cookieValue) {
+    return originalHostname;
+  }
+
+  // Check if current host is allowed
+  const allowed = isHostAllowed(request, allowedHosts);
+
+  // If not allowed, throw error
+  if (!allowed) {
+    throw new HostOverrideNotAllowedError(originalHostname, cookieName, {
+      cause: { cookieValue, currentHost: originalHostname },
+    });
+  }
+
+  // If allowed and has custom validation, run it
+  if (validate) {
+    try {
+      const validatedHostname = validate(request, cookieValue, input);
+      return validatedHostname;
+    } catch (error) {
+      // Wrap in HostValidationError
+      const message = error instanceof Error ? error.message : String(error);
+      throw new HostValidationError(message, error);
+    }
+  }
+
+  // Default validation - verify it's a valid hostname using URL constructor
+  try {
+    // Try to construct a URL with the hostname to validate it
+    const testUrl = new URL(`https://${cookieValue}`);
+
+    // Ensure the hostname matches what we provided (URL constructor normalizes it)
+    if (testUrl.hostname !== cookieValue) {
+      throw new InvalidHostnameError(cookieValue, {
+        cause: { original: cookieValue, normalized: testUrl.hostname },
+      });
+    }
+  } catch (error) {
+    // If URL constructor failed, throw InvalidHostnameError with cause
+    if (error instanceof InvalidHostnameError) {
+      throw error;
+    }
+    throw new InvalidHostnameError(cookieValue, { cause: error });
+  }
+
+  return cookieValue;
+}