@rangojs/router 0.0.0-experimental.10

package/src/host/router.ts

@@ -0,0 +1,330 @@
+/**
+ * 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 {
+  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,
+    context: 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();
+      }
+
+      return mw(request, context, next);
+    }
+
+    return next();
+  }
+
+  /**
+   * Execute handler (lazy or direct)
+   */
+  async function executeHandler(
+    handler: Handler | LazyHandler,
+    request: Request,
+    context: any
+  ): Promise<Response> {
+    // Check if it's a lazy handler (function that returns promise)
+    if (typeof handler === 'function') {
+      const result = handler(request, context);
+
+      // 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, context);
+          }
+
+          // Otherwise treat as handler
+          return (defaultExport as Handler)(request, context);
+        }
+        // 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, context: any = {}): Promise<Response> {
+      log(`Request: ${request.url}`);
+
+      let effectiveHostname: string;
+
+      try {
+        // Handle cookie override (may throw HostRouterError)
+        effectiveHostname = handleCookieOverride(
+          request,
+          hostOverride,
+          context
+        );
+      } 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) {
+            context.error = error;
+            const allMiddleware = [
+              ...globalMiddleware,
+              ...fallbackRoute.middleware,
+            ];
+
+            return executeMiddleware(allMiddleware, request, context, () =>
+              executeHandler(fallbackRoute!.handler, request, context)
+            );
+          }
+
+          // 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, context, () =>
+        executeHandler(matchedRoute.handler, request, context)
+      );
+    },
+  };
+
+  // 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,138 @@
+/**
+ * Host Router Types
+ *
+ * Type definitions for the host-based routing system.
+ */
+
+/**
+ * Handler function that processes a request and returns a response
+ */
+export type Handler = (
+  request: Request,
+  context: 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
+ */
+export type Middleware = (
+  request: Request,
+  context: 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, context?: 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, context: 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);
+}