@rangojs/router 0.0.0-experimental.0f44aca1

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

package/src/host/testing.ts

@@ -0,0 +1,79 @@
+/**
+ * Testing Utilities for Host Router
+ *
+ * Helper functions for testing host routing.
+ */
+
+import { matchPattern } from "./pattern-matcher.js";
+
+export interface CreateTestRequestOptions {
+  host: string;
+  path?: string;
+  method?: string;
+  cookies?: Record<string, string>;
+  headers?: Record<string, string>;
+}
+
+/**
+ * Create a test request with specific host and cookies
+ *
+ * @example
+ * ```ts
+ * const request = createTestRequest({
+ *   host: 'admin.example.com',
+ *   path: '/dashboard',
+ *   cookies: { 'x-requested-host': 'api.example.com' }
+ * });
+ * ```
+ */
+export function createTestRequest(options: CreateTestRequestOptions): Request {
+  const {
+    host,
+    path = "/",
+    method = "GET",
+    cookies = {},
+    headers = {},
+  } = options;
+
+  const url = `http://${host}${path}`;
+  const requestHeaders = new Headers(headers);
+
+  // Add cookies if provided
+  if (Object.keys(cookies).length > 0) {
+    const cookieString = Object.entries(cookies)
+      .map(([key, value]) => `${key}=${encodeURIComponent(value)}`)
+      .join("; ");
+    requestHeaders.set("cookie", cookieString);
+  }
+
+  return new Request(url, {
+    method,
+    headers: requestHeaders,
+  });
+}
+
+/**
+ * Test if a pattern matches a hostname
+ *
+ * @example
+ * ```ts
+ * expect(testPattern('admin.*', 'admin.example.com')).toBe(true);
+ * expect(testPattern(['*', 'www.*'], 'example.com')).toBe(true);
+ * ```
+ */
+export function testPattern(
+  pattern: string | string[],
+  hostname: string,
+): boolean {
+  const patterns = Array.isArray(pattern) ? pattern : [pattern];
+  const parts = hostname.split(".");
+  const pathname = "/";
+
+  for (const p of patterns) {
+    if (matchPattern(p, hostname, pathname, parts)) {
+      return true;
+    }
+  }
+
+  return false;
+}

package/src/host/types.ts

@@ -0,0 +1,146 @@
+/**
+ * Host Router Types
+ *
+ * Type definitions for the host-based routing system.
+ */
+
+import type { RouterRequestInput } from "../router/router-interfaces.js";
+
+/**
+ * Handler function that processes a request and returns a response.
+ * The input parameter receives the same RouterRequestInput passed to match().
+ */
+export type Handler = (
+  request: Request,
+  input: RouterRequestInput<any>,
+) => Response | Promise<Response>;
+
+/**
+ * Lazy handler that dynamically imports a module with a default handler or router
+ */
+export type LazyHandler = () => Promise<{ default: Handler | HostRouter }>;
+
+/**
+ * Middleware function that can intercept and modify requests/responses.
+ * The input parameter receives the same RouterRequestInput passed to match().
+ */
+export type Middleware = (
+  request: Request,
+  input: RouterRequestInput<any>,
+  next: () => Promise<Response>,
+) => Promise<Response>;
+
+/**
+ * Host pattern - can be a string or array of strings
+ */
+export type HostPattern = string | string[];
+
+/**
+ * Result from testing a hostname against patterns
+ */
+export interface HostMatchResult {
+  pattern: string;
+  handler: Handler | LazyHandler;
+}
+
+/**
+ * Host route builder for chaining middleware and handler
+ */
+export interface HostRouteBuilder {
+  /**
+   * Add middleware to this host pattern
+   */
+  use(...middleware: Middleware[]): HostRouteBuilder;
+
+  /**
+   * Map to a handler or lazy import
+   */
+  map(handler: Handler | LazyHandler): HostRouter;
+}
+
+/**
+ * Main host router interface
+ */
+export interface HostRouter {
+  /**
+   * Register a host pattern
+   */
+  host(patterns: HostPattern): HostRouteBuilder;
+
+  /**
+   * Register global middleware
+   */
+  use(...middleware: Middleware[]): HostRouter;
+
+  /**
+   * Match an incoming request
+   */
+  match(request: Request, input?: RouterRequestInput<any>): Promise<Response>;
+
+  /**
+   * Register fallback handler for allowed hosts without valid cookie
+   */
+  fallback(): HostRouteBuilder;
+
+  /**
+   * Test which handler would match a hostname
+   */
+  test(hostname: string): HostMatchResult | null;
+}
+
+/**
+ * Host override configuration
+ */
+export interface HostOverrideConfig {
+  /**
+   * Cookie name to read for host override
+   */
+  cookieName: string;
+
+  /**
+   * Hosts that are allowed to use override
+   */
+  allowedHosts: string[];
+
+  /**
+   * Optional validation function
+   */
+  validate?: (
+    request: Request,
+    cookieValue: string,
+    input: RouterRequestInput<any>,
+  ) => string;
+}
+
+/**
+ * Host router options
+ */
+export interface HostRouterOptions {
+  /**
+   * Enable debug logging
+   */
+  debug?: boolean;
+
+  /**
+   * Cookie-based host override configuration
+   */
+  hostOverride?: HostOverrideConfig;
+}
+
+/**
+ * Internal route entry
+ */
+export interface RouteEntry {
+  patterns: string[];
+  middleware: Middleware[];
+  handler: Handler | LazyHandler;
+  isFallback?: boolean;
+}
+
+/**
+ * Pattern match result (internal)
+ */
+export interface PatternMatchResult {
+  matched: boolean;
+  routeEntry?: RouteEntry;
+}

package/src/host/utils.ts

@@ -0,0 +1,25 @@
+/**
+ * Host Router Utilities
+ *
+ * Helper functions for type-safe pattern definitions.
+ */
+
+/**
+ * Define hosts with type safety
+ *
+ * @example
+ * ```ts
+ * const hosts = defineHosts({
+ *   admin: 'admin.*',
+ *   api: 'api.*',
+ *   app: ['*', 'www.*']
+ * });
+ *
+ * router.host(hosts.admin).map(...); // Type-safe!
+ * ```
+ */
+export function defineHosts<T extends Record<string, string | string[]>>(
+  hosts: T,
+): Readonly<T> {
+  return Object.freeze(hosts);
+}