@rangojs/router 0.0.0-experimental.6 → 0.0.0-experimental.64e3ae06

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;
+}

package/src/host/errors.ts

@@ -0,0 +1,97 @@
+/**
+ * Custom Error Classes for Host Router
+ *
+ * All host router errors extend HostRouterError for easy instance checking.
+ */
+
+/**
+ * Error options with cause
+ */
+interface ErrorOptions {
+  cause?: unknown;
+}
+
+/**
+ * Base error class for all host router errors
+ */
+export class HostRouterError extends Error {
+  cause?: unknown;
+
+  constructor(message: string, options?: ErrorOptions) {
+    super(message);
+    if (options?.cause) {
+      this.cause = options.cause;
+    }
+    this.name = "HostRouterError";
+    Object.setPrototypeOf(this, HostRouterError.prototype);
+  }
+}
+
+/**
+ * Error thrown when pattern validation fails
+ */
+export class InvalidPatternError extends HostRouterError {
+  constructor(pattern: string, reason: string, options?: ErrorOptions) {
+    super(`Invalid pattern "${pattern}": ${reason}`, options);
+    this.name = "InvalidPatternError";
+    Object.setPrototypeOf(this, InvalidPatternError.prototype);
+  }
+}
+
+/**
+ * Error thrown when cookie override is not allowed
+ */
+export class HostOverrideNotAllowedError extends HostRouterError {
+  constructor(currentHost: string, cookieName: string, options?: ErrorOptions) {
+    super(
+      `Host override not allowed on "${currentHost}" (cookie: ${cookieName})`,
+      options,
+    );
+    this.name = "HostOverrideNotAllowedError";
+    Object.setPrototypeOf(this, HostOverrideNotAllowedError.prototype);
+  }
+}
+
+/**
+ * Error thrown when cookie hostname is invalid
+ */
+export class InvalidHostnameError extends HostRouterError {
+  constructor(hostname: string, options?: ErrorOptions) {
+    super(`Invalid hostname format: "${hostname}"`, options);
+    this.name = "InvalidHostnameError";
+    Object.setPrototypeOf(this, InvalidHostnameError.prototype);
+  }
+}
+
+/**
+ * Error thrown when custom validation fails
+ */
+export class HostValidationError extends HostRouterError {
+  constructor(message: string, cause?: unknown) {
+    super(message, { cause });
+    this.name = "HostValidationError";
+    Object.setPrototypeOf(this, HostValidationError.prototype);
+  }
+}
+
+/**
+ * Error thrown when no route matches
+ */
+export class NoRouteMatchError extends HostRouterError {
+  constructor(hostname: string, pathname: string, options?: ErrorOptions) {
+    super(`No route matched for ${hostname}${pathname}`, options);
+    this.name = "NoRouteMatchError";
+    Object.setPrototypeOf(this, NoRouteMatchError.prototype);
+  }
+}
+
+/**
+ * Error thrown when handler type is invalid
+ */
+export class InvalidHandlerError extends HostRouterError {
+  constructor(handler: unknown, options?: ErrorOptions) {
+    super(`Invalid handler type: ${typeof handler}`, options);
+    this.name = "InvalidHandlerError";
+    Object.setPrototypeOf(this, InvalidHandlerError.prototype);
+  }
+}

package/src/host/index.ts

@@ -0,0 +1,53 @@
+/**
+ * Host Router
+ *
+ * A routing system for managing multi-application hosting based on
+ * domain/subdomain patterns with support for cookie-based host override
+ * for development environments.
+ *
+ * @example
+ * ```ts
+ * import { createHostRouter } from '@rangojs/router/host';
+ *
+ * const router = createHostRouter();
+ *
+ * router.host(['.']).map(() => import('./apps/main'));
+ * router.host(['admin.*']).map(() => import('./apps/admin'));
+ *
+ * export default {
+ *   fetch(request) {
+ *     return router.match(request);
+ *   }
+ * };
+ * ```
+ */
+
+// Core router
+export { createHostRouter } from "./router.js";
+
+// Utilities
+export { defineHosts } from "./utils.js";
+
+// Errors
+export {
+  HostRouterError,
+  InvalidPatternError,
+  HostOverrideNotAllowedError,
+  InvalidHostnameError,
+  HostValidationError,
+  NoRouteMatchError,
+  InvalidHandlerError,
+} from "./errors.js";
+
+// Types
+export type {
+  HostRouter,
+  HostRouteBuilder,
+  HostRouterOptions,
+  Handler,
+  LazyHandler,
+  Middleware,
+  HostPattern,
+  HostMatchResult,
+  HostOverrideConfig,
+} from "./types.js";

package/src/host/pattern-matcher.ts

@@ -0,0 +1,214 @@
+/**
+ * Pattern Matching Engine
+ *
+ * Handles matching of hostnames and paths against various patterns:
+ * - `.` or `*` - any apex domain
+ * - `**` - any domain (apex + subdomains)
+ * - `*.` - any single-level subdomain
+ * - `**.` - any multi-level subdomain
+ * - `example.com` - exact domain
+ * - `*.com` - any apex .com domain
+ * - `*.example.com` - subdomain of example.com
+ * - `**.example.com` - any depth subdomain
+ * - `admin.*` - admin subdomain of any apex
+ * - `example.com/admin` - specific domain with path prefix
+ */
+
+import { InvalidPatternError } from "./errors.js";
+
+/**
+ * Normalize a pattern by removing trailing slashes from paths
+ */
+export function normalizePattern(pattern: string): string {
+  // If pattern has a path component, remove trailing slash
+  const slashIndex = pattern.indexOf("/");
+  if (slashIndex !== -1) {
+    const domain = pattern.slice(0, slashIndex);
+    const path = pattern.slice(slashIndex).replace(/\/$/, "");
+    return domain + path;
+  }
+  return pattern;
+}
+
+/**
+ * Parse hostname and path from request URL
+ */
+export function parseRequest(request: Request): {
+  hostname: string;
+  pathname: string;
+  parts: string[];
+} {
+  const url = new URL(request.url);
+  const hostname = url.hostname;
+  const pathname = url.pathname;
+  const parts = hostname.split(".");
+
+  return { hostname, pathname, parts };
+}
+
+/**
+ * Count subdomain levels (0 for apex, 1+ for subdomains)
+ */
+function getSubdomainLevel(parts: string[]): number {
+  // Apex domain has 2 parts (example.com)
+  // Single subdomain has 3 parts (www.example.com)
+  // Multi-level has 4+ parts (a.b.example.com)
+  return Math.max(0, parts.length - 2);
+}
+
+/**
+ * Check if hostname is an apex domain (no subdomains)
+ */
+function isApexDomain(parts: string[]): boolean {
+  return parts.length === 2;
+}
+
+/**
+ * Match a single pattern against hostname and path
+ */
+export function matchPattern(
+  pattern: string,
+  hostname: string,
+  pathname: string,
+  parts: string[],
+): boolean {
+  const normalized = normalizePattern(pattern);
+
+  // Check if pattern has path component
+  const slashIndex = normalized.indexOf("/");
+  const hasPath = slashIndex !== -1;
+  const domainPattern = hasPath ? normalized.slice(0, slashIndex) : normalized;
+  const pathPattern = hasPath ? normalized.slice(slashIndex) : null;
+
+  // First match domain
+  const domainMatch = matchDomainPattern(domainPattern, hostname, parts);
+  if (!domainMatch) {
+    return false;
+  }
+
+  // Then match path (prefix match)
+  if (pathPattern) {
+    return pathname === pathPattern || pathname.startsWith(pathPattern + "/");
+  }
+
+  return true;
+}
+
+/**
+ * Match domain pattern against hostname
+ */
+function matchDomainPattern(
+  pattern: string,
+  hostname: string,
+  parts: string[],
+): boolean {
+  // Exact match
+  if (pattern === hostname) {
+    return true;
+  }
+
+  // `.` or `*` - any apex domain
+  if (pattern === "." || pattern === "*") {
+    return isApexDomain(parts);
+  }
+
+  // `**` - any domain (apex + all subdomains)
+  if (pattern === "**") {
+    return true;
+  }
+
+  // `*.` - any single-level subdomain
+  if (pattern === "*.") {
+    return getSubdomainLevel(parts) === 1;
+  }
+
+  // `**.` - any multi-level subdomain (2+ levels)
+  if (pattern === "**.") {
+    return getSubdomainLevel(parts) >= 2;
+  }
+
+  // `*.tld` - any apex domain with specific TLD (e.g., *.com)
+  if (pattern.startsWith("*.") && !pattern.includes(".", 2)) {
+    const tld = pattern.slice(2);
+    return isApexDomain(parts) && hostname.endsWith("." + tld);
+  }
+
+  // `*.example.com` - single subdomain of specific domain
+  if (pattern.startsWith("*.")) {
+    const baseDomain = pattern.slice(2);
+    if (hostname.endsWith("." + baseDomain)) {
+      // Count parts: if pattern is *.example.com (3 parts),
+      // hostname should have exactly 4 parts (www.example.com)
+      const patternParts = baseDomain.split(".");
+      return parts.length === patternParts.length + 1;
+    }
+    return false;
+  }
+
+  // `**.example.com` - any depth subdomain of specific domain
+  if (pattern.startsWith("**.")) {
+    const baseDomain = pattern.slice(3);
+    if (hostname.endsWith("." + baseDomain)) {
+      const patternParts = baseDomain.split(".");
+      // Must have more parts than the base domain (i.e., has subdomains)
+      return parts.length > patternParts.length;
+    }
+    return false;
+  }
+
+  // `subdomain.*` - specific subdomain of any apex domain
+  // e.g., admin.* matches admin.example.com, admin.google.com
+  if (pattern.endsWith(".*")) {
+    const subdomain = pattern.slice(0, -2);
+    // Must be single-level subdomain (3 parts total)
+    if (parts.length === 3 && parts[0] === subdomain) {
+      return true;
+    }
+    return false;
+  }
+
+  // `subdomain.**` - specific subdomain of any domain (including multi-level)
+  // e.g., admin.** matches admin.example.com, admin.sub.example.com
+  if (pattern.endsWith(".**")) {
+    const subdomain = pattern.slice(0, -3);
+    if (parts.length >= 3 && parts[0] === subdomain) {
+      return true;
+    }
+    return false;
+  }
+
+  // `subdomain.` - specific subdomain of any apex domain (no wildcard)
+  // e.g., admin. matches admin.example.com, admin.google.com
+  if (pattern.endsWith(".") && !pattern.includes("*")) {
+    const subdomain = pattern.slice(0, -1);
+    // Must be exactly 3 parts (subdomain.domain.tld)
+    if (parts.length === 3 && parts[0] === subdomain) {
+      return true;
+    }
+    return false;
+  }
+
+  return false;
+}
+
+/**
+ * Validate pattern format
+ */
+export function validatePattern(pattern: string): void {
+  if (!pattern || typeof pattern !== "string") {
+    throw new InvalidPatternError(
+      pattern,
+      "Pattern must be a non-empty string",
+      { cause: { type: typeof pattern, value: pattern } },
+    );
+  }
+
+  // Check for invalid characters (spaces, etc.)
+  if (/\s/.test(pattern)) {
+    throw new InvalidPatternError(pattern, "contains whitespace", {
+      cause: { pattern },
+    });
+  }
+
+  // Additional validation can be added here
+}