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

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

package/src/host/router.ts

@@ -0,0 +1,352 @@
+/**
+ * Host Router Implementation
+ *
+ * Main router that handles host-based routing with middleware and cookie override.
+ */
+
+import type {
+  HostRouter,
+  HostRouteBuilder,
+  HostRouterOptions,
+  Handler,
+  LazyHandler,
+  Middleware,
+  HostPattern,
+  RouteEntry,
+  HostMatchResult,
+} from "./types.js";
+import type { RouterRequestInput } from "../router/router-interfaces.js";
+import {
+  matchPattern,
+  parseRequest,
+  normalizePattern,
+  validatePattern,
+} from "./pattern-matcher.js";
+import {
+  handleCookieOverride,
+  createCookieErrorResponse,
+} from "./cookie-handler.js";
+import {
+  HostRouterError,
+  NoRouteMatchError,
+  InvalidHandlerError,
+} from "./errors.js";
+
+/**
+ * Registry entry for a host router instance.
+ * Stores references to the live routes array and fallback, so the discovery
+ * plugin can iterate handlers registered after createHostRouter() returns.
+ */
+export interface HostRouterRegistryEntry {
+  routes: RouteEntry[];
+  fallback: RouteEntry | null;
+}
+
+/**
+ * Global registry for host routers (parallel to RouterRegistry for RSC routers).
+ * Populated by createHostRouter() so the build-time discovery plugin can find
+ * host routers and resolve their lazy handlers to trigger sub-app createRouter() calls.
+ */
+export const HostRouterRegistry: Map<string, HostRouterRegistryEntry> =
+  new Map();
+
+let hostRouterAutoId = 0;
+
+/**
+ * Create a host router
+ */
+export function createHostRouter(options: HostRouterOptions = {}): HostRouter {
+  const routes: RouteEntry[] = [];
+  const globalMiddleware: Middleware[] = [];
+  let fallbackRoute: RouteEntry | null = null;
+
+  const { debug = false, hostOverride } = options;
+
+  function log(message: string, ...args: any[]): void {
+    if (debug) {
+      console.log(`[HostRouter] ${message}`, ...args);
+    }
+  }
+
+  /**
+   * Create a route builder for chaining
+   */
+  function createRouteBuilder(
+    patterns: string[],
+    isFallback = false,
+  ): HostRouteBuilder {
+    const middleware: Middleware[] = [];
+
+    return {
+      use(...mw: Middleware[]): HostRouteBuilder {
+        middleware.push(...mw);
+        return this;
+      },
+
+      map(handler: Handler | LazyHandler): HostRouter {
+        const entry: RouteEntry = {
+          patterns,
+          middleware,
+          handler,
+          isFallback,
+        };
+
+        if (isFallback) {
+          fallbackRoute = entry;
+        } else {
+          routes.push(entry);
+        }
+
+        log(
+          `Registered ${isFallback ? "fallback" : "route"}:`,
+          patterns.join(", "),
+        );
+
+        return router;
+      },
+    };
+  }
+
+  /**
+   * Find matching route for hostname and path
+   */
+  function findMatchingRoute(
+    hostname: string,
+    pathname: string,
+  ): RouteEntry | null {
+    const parts = hostname.split(".");
+
+    for (const route of routes) {
+      for (const pattern of route.patterns) {
+        if (matchPattern(pattern, hostname, pathname, parts)) {
+          log(`Matched pattern: "${pattern}"`);
+          return route;
+        }
+      }
+    }
+
+    return null;
+  }
+
+  /**
+   * Execute middleware chain
+   */
+  async function executeMiddleware(
+    middleware: Middleware[],
+    request: Request,
+    input: RouterRequestInput<any>,
+    finalHandler: () => Promise<Response>,
+  ): Promise<Response> {
+    let index = 0;
+
+    async function next(): Promise<Response> {
+      if (index >= middleware.length) {
+        return finalHandler();
+      }
+
+      const mw = middleware[index++];
+      if (!mw) {
+        return finalHandler();
+      }
+
+      // Guard against double next() calls — a second call would
+      // re-enter the downstream chain and run handlers/side-effects twice.
+      let nextCalled = false;
+      const guardedNext = (): Promise<Response> => {
+        if (nextCalled) {
+          throw new Error(
+            `[HostRouter] Middleware called next() more than once.`,
+          );
+        }
+        nextCalled = true;
+        return next();
+      };
+
+      return mw(request, input, guardedNext);
+    }
+
+    return next();
+  }
+
+  /**
+   * Execute handler (lazy or direct)
+   */
+  async function executeHandler(
+    handler: Handler | LazyHandler,
+    request: Request,
+    input: RouterRequestInput<any>,
+  ): Promise<Response> {
+    // Check if it's a lazy handler (function that returns promise)
+    if (typeof handler === "function") {
+      const result = handler(request, input);
+
+      // If it returns a promise with default export
+      if (result && typeof result === "object" && "then" in result) {
+        const module = await result;
+        if (
+          typeof module === "object" &&
+          module !== null &&
+          "default" in module
+        ) {
+          const defaultExport = (module as { default: Handler | HostRouter })
+            .default;
+
+          // If default export is a router with match method
+          if (
+            typeof defaultExport === "object" &&
+            defaultExport !== null &&
+            "match" in defaultExport
+          ) {
+            return (defaultExport as HostRouter).match(request, input);
+          }
+
+          // Otherwise treat as handler
+          return (defaultExport as Handler)(request, input);
+        }
+        // If promise resolves to Response
+        return result as Promise<Response>;
+      }
+
+      // Direct handler
+      return result as Response | Promise<Response>;
+    }
+
+    throw new InvalidHandlerError(handler, {
+      cause: { handlerType: typeof handler },
+    });
+  }
+
+  /**
+   * Router instance
+   */
+  const router: HostRouter = {
+    host(patterns: HostPattern): HostRouteBuilder {
+      const patternsArray = Array.isArray(patterns) ? patterns : [patterns];
+
+      // Validate and normalize patterns
+      const normalized = patternsArray.map((p) => {
+        validatePattern(p);
+        return normalizePattern(p);
+      });
+
+      return createRouteBuilder(normalized, false);
+    },
+
+    use(...middleware: Middleware[]): HostRouter {
+      globalMiddleware.push(...middleware);
+      log(`Registered global middleware (${middleware.length})`);
+      return router;
+    },
+
+    fallback(): HostRouteBuilder {
+      return createRouteBuilder([], true);
+    },
+
+    test(hostname: string): HostMatchResult | null {
+      const parts = hostname.split(".");
+      const pathname = "/";
+
+      for (const route of routes) {
+        for (const pattern of route.patterns) {
+          if (matchPattern(pattern, hostname, pathname, parts)) {
+            return {
+              pattern,
+              handler: route.handler,
+            };
+          }
+        }
+      }
+
+      return null;
+    },
+
+    async match(
+      request: Request,
+      input: RouterRequestInput<any> = {},
+    ): Promise<Response> {
+      log(`Request: ${request.url}`);
+
+      let effectiveHostname: string;
+
+      try {
+        // Handle cookie override (may throw HostRouterError)
+        effectiveHostname = handleCookieOverride(request, hostOverride, input);
+      } catch (error) {
+        // If it's a HostRouterError from cookie override
+        if (error instanceof HostRouterError) {
+          log(`Cookie override error: ${error.message}`);
+
+          // If fallback exists, use it
+          if (fallbackRoute) {
+            const fallbackInput = { ...input, error };
+            const allMiddleware = [
+              ...globalMiddleware,
+              ...fallbackRoute.middleware,
+            ];
+
+            return executeMiddleware(
+              allMiddleware,
+              request,
+              fallbackInput,
+              () =>
+                executeHandler(fallbackRoute!.handler, request, fallbackInput),
+            );
+          }
+
+          // Otherwise return error response with cookie deletion
+          if (hostOverride) {
+            return createCookieErrorResponse(
+              hostOverride.cookieName,
+              error.message,
+            );
+          }
+        }
+
+        // Re-throw non-HostRouterErrors
+        throw error;
+      }
+
+      const { pathname } = parseRequest(request);
+
+      if (effectiveHostname !== parseRequest(request).hostname) {
+        log(`Cookie override: ${effectiveHostname}`);
+      }
+
+      // Find matching route
+      const matchedRoute = findMatchingRoute(effectiveHostname, pathname);
+
+      if (!matchedRoute) {
+        log(`No route matched`);
+        throw new NoRouteMatchError(effectiveHostname, pathname, {
+          cause: {
+            hostname: effectiveHostname,
+            pathname,
+          },
+        });
+      }
+
+      // Combine global and route-specific middleware
+      const allMiddleware = [...globalMiddleware, ...matchedRoute.middleware];
+
+      // Execute middleware chain and handler
+      return executeMiddleware(allMiddleware, request, input, () =>
+        executeHandler(matchedRoute.handler, request, input),
+      );
+    },
+  };
+
+  // Register in the global HostRouterRegistry for build-time discovery.
+  // The routes array and fallbackRoute ref are live - they reflect routes
+  // added via .host().map() after this point.
+  const registryId = `host-router-${hostRouterAutoId++}`;
+  HostRouterRegistry.set(registryId, {
+    get routes() {
+      return routes;
+    },
+    get fallback() {
+      return fallbackRoute;
+    },
+  });
+
+  return router;
+}