@rangojs/router 0.0.0-experimental.13 → 0.0.0-experimental.131

package/src/host/pattern-matcher.ts

@@ -12,27 +12,27 @@
  * - `**.example.com` - any depth subdomain
  * - `admin.*` - admin subdomain of any apex
  * - `example.com/admin` - specific domain with path prefix
+ *
+ * Apex vs subdomain is classified purely by dot-part COUNT (apex == exactly 2
+ * parts) — there is no Public Suffix List. A registrable domain under a
+ * multi-label public suffix (example.co.uk, shop.com.au) has 3+ parts and is
+ * therefore treated as a SUBDOMAIN, not an apex: `.`/`*` will NOT match it and
+ * `*.` WILL. If registrable-domain accuracy matters for a host-router consumer,
+ * supply an explicit apex/host hint rather than relying on the part count.
  */
 
-import { InvalidPatternError } from './errors.js';
+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('/');
+  const slashIndex = pattern.indexOf("/");
   if (slashIndex !== -1) {
     const domain = pattern.slice(0, slashIndex);
-    const path = pattern.slice(slashIndex).replace(/\/$/, '');
+    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;
@@ -41,135 +41,101 @@ export function parseRequest(request: Request): {
   const url = new URL(request.url);
   const hostname = url.hostname;
   const pathname = url.pathname;
-  const parts = hostname.split('.');
+  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[]
+  parts: string[],
 ): boolean {
   const normalized = normalizePattern(pattern);
 
-  // Check if pattern has path component
-  const slashIndex = normalized.indexOf('/');
+  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 pathname === pathPattern || pathname.startsWith(pathPattern + "/");
   }
 
   return true;
 }
 
-/**
- * Match domain pattern against hostname
- */
 function matchDomainPattern(
   pattern: string,
   hostname: string,
-  parts: string[]
+  parts: string[],
 ): boolean {
-  // Exact match
   if (pattern === hostname) {
     return true;
   }
 
-  // `.` or `*` - any apex domain
-  if (pattern === '.' || pattern === '*') {
+  if (pattern === "." || pattern === "*") {
     return isApexDomain(parts);
   }
 
-  // `**` - any domain (apex + all subdomains)
-  if (pattern === '**') {
+  if (pattern === "**") {
     return true;
   }
 
-  // `*.` - any single-level subdomain
-  if (pattern === '*.') {
+  if (pattern === "*.") {
     return getSubdomainLevel(parts) === 1;
   }
 
-  // `**.` - any multi-level subdomain (2+ levels)
-  if (pattern === '**.') {
+  if (pattern === "**.") {
     return getSubdomainLevel(parts) >= 2;
   }
 
-  // `*.tld` - any apex domain with specific TLD (e.g., *.com)
-  if (pattern.startsWith('*.') && !pattern.includes('.', 2)) {
+  if (pattern.startsWith("*.") && !pattern.includes(".", 2)) {
     const tld = pattern.slice(2);
-    return isApexDomain(parts) && hostname.endsWith('.' + tld);
+    return isApexDomain(parts) && hostname.endsWith("." + tld);
   }
 
-  // `*.example.com` - single subdomain of specific domain
-  if (pattern.startsWith('*.')) {
+  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('.');
+    if (hostname.endsWith("." + baseDomain)) {
+      const patternParts = baseDomain.split(".");
       return parts.length === patternParts.length + 1;
     }
     return false;
   }
 
-  // `**.example.com` - any depth subdomain of specific domain
-  if (pattern.startsWith('**.')) {
+  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)
+    if (hostname.endsWith("." + baseDomain)) {
+      const patternParts = baseDomain.split(".");
       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('.*')) {
+  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('.**')) {
+  if (pattern.endsWith(".**")) {
     const subdomain = pattern.slice(0, -3);
     if (parts.length >= 3 && parts[0] === subdomain) {
       return true;
@@ -177,11 +143,8 @@ function matchDomainPattern(
     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('*')) {
+  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;
     }
@@ -191,24 +154,18 @@ function matchDomainPattern(
   return false;
 }
 
-/**
- * Validate pattern format
- */
 export function validatePattern(pattern: string): void {
-  if (!pattern || typeof pattern !== 'string') {
+  if (!pattern || typeof pattern !== "string") {
     throw new InvalidPatternError(
       pattern,
-      'Pattern must be a non-empty string',
-      { cause: { type: typeof pattern, value: 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', {
+    throw new InvalidPatternError(pattern, "contains whitespace", {
       cause: { pattern },
     });
   }
-
-  // Additional validation can be added here
 }

package/src/host/router.ts

@@ -14,45 +14,55 @@ import type {
   HostPattern,
   RouteEntry,
   HostMatchResult,
-} from './types.js';
+} from "./types.js";
+import type { RouterRequestInput } from "../router/router-interfaces.js";
 import {
   matchPattern,
   parseRequest,
   normalizePattern,
   validatePattern,
-} from './pattern-matcher.js';
+} from "./pattern-matcher.js";
 import {
   handleCookieOverride,
   createCookieErrorResponse,
-} from './cookie-handler.js';
+} from "./cookie-handler.js";
 import {
   HostRouterError,
   NoRouteMatchError,
   InvalidHandlerError,
-} from './errors.js';
+} 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();
+export const HostRouterRegistry: Map<string, HostRouterRegistryEntry> =
+  new Map();
 
 let hostRouterAutoId = 0;
 
-/**
- * Create a host router
- */
+function isThenable(value: unknown): value is PromiseLike<unknown> {
+  return (
+    value !== null &&
+    (typeof value === "object" || typeof value === "function") &&
+    typeof (value as { then?: unknown }).then === "function"
+  );
+}
+
+function looksLikeLazyModule(value: unknown): boolean {
+  if (value === null || typeof value !== "object" || !("default" in value)) {
+    return false;
+  }
+  const defaultExport = (value as { default: unknown }).default;
+  return (
+    typeof defaultExport === "function" ||
+    (typeof defaultExport === "object" &&
+      defaultExport !== null &&
+      "match" in defaultExport)
+  );
+}
+
 export function createHostRouter(options: HostRouterOptions = {}): HostRouter {
   const routes: RouteEntry[] = [];
   const globalMiddleware: Middleware[] = [];
@@ -66,53 +76,59 @@ export function createHostRouter(options: HostRouterOptions = {}): HostRouter {
     }
   }
 
-  /**
-   * Create a route builder for chaining
-   */
   function createRouteBuilder(
     patterns: string[],
-    isFallback = false
+    isFallback = false,
   ): HostRouteBuilder {
     const middleware: Middleware[] = [];
 
+    function register(
+      handler: Handler | LazyHandler,
+      kind: RouteEntry["kind"],
+    ): HostRouter {
+      const entry: RouteEntry = {
+        patterns,
+        middleware,
+        handler,
+        kind,
+        isFallback,
+      };
+
+      if (isFallback) {
+        fallbackRoute = entry;
+      } else {
+        routes.push(entry);
+      }
+
+      log(
+        `Registered ${isFallback ? "fallback" : "route"} (${kind}):`,
+        patterns.join(", "),
+      );
+
+      return router;
+    }
+
     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(', ')
-        );
+      map(handler: Handler): HostRouter {
+        return register(handler, "handler");
+      },
 
-        return router;
+      lazy(handler: LazyHandler): HostRouter {
+        return register(handler, "lazy");
       },
     };
   }
 
-  /**
-   * Find matching route for hostname and path
-   */
   function findMatchingRoute(
     hostname: string,
-    pathname: string
+    pathname: string,
   ): RouteEntry | null {
-    const parts = hostname.split('.');
+    const parts = hostname.split(".");
 
     for (const route of routes) {
       for (const pattern of route.patterns) {
@@ -126,14 +142,11 @@ export function createHostRouter(options: HostRouterOptions = {}): HostRouter {
     return null;
   }
 
-  /**
-   * Execute middleware chain
-   */
   async function executeMiddleware(
     middleware: Middleware[],
     request: Request,
-    context: any,
-    finalHandler: () => Promise<Response>
+    input: RouterRequestInput<any>,
+    finalHandler: () => Promise<Response>,
   ): Promise<Response> {
     let index = 0;
 
@@ -147,68 +160,90 @@ export function createHostRouter(options: HostRouterOptions = {}): HostRouter {
         return finalHandler();
       }
 
-      return mw(request, context, next);
+      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,
+    entry: RouteEntry,
     request: Request,
-    context: any
+    input: RouterRequestInput<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);
-          }
+    const { handler, kind } = entry;
 
-          // Otherwise treat as handler
-          return (defaultExport as Handler)(request, context);
-        }
-        // If promise resolves to Response
-        return result as Promise<Response>;
+    if (typeof handler !== "function") {
+      throw new InvalidHandlerError(handler, {
+        cause: { handlerType: typeof handler },
+      });
+    }
+
+    if (kind === "lazy") {
+      return executeLazyMount(handler as LazyHandler, request, input);
+    }
+
+    const result = (handler as Handler)(request, input);
+
+    if (isThenable(result)) {
+      const awaited = await result;
+      if (looksLikeLazyModule(awaited)) {
+        throw new HostRouterError(
+          ".map() is for inline request handlers; use .lazy(() => import(...)) for lazy host mounts.",
+        );
       }
+      return awaited as Response;
+    }
+
+    return result;
+  }
 
-      // Direct handler
-      return result as Response | Promise<Response>;
+  async function executeLazyMount(
+    loader: LazyHandler,
+    request: Request,
+    input: RouterRequestInput<any>,
+  ): Promise<Response> {
+    const module = await loader();
+
+    if (typeof module === "object" && module !== null && "default" in module) {
+      const defaultExport = (module as { default: Handler | HostRouter })
+        .default;
+
+      if (
+        typeof defaultExport === "object" &&
+        defaultExport !== null &&
+        "match" in defaultExport
+      ) {
+        return (defaultExport as HostRouter).match(request, input);
+      }
+
+      return (defaultExport as Handler)(request, input);
     }
 
-    throw new InvalidHandlerError(handler, {
-      cause: { handlerType: typeof handler },
+    throw new InvalidHandlerError(loader, {
+      cause: {
+        reason:
+          "lazy mount did not resolve to a module with a default export; " +
+          "use .lazy(() => import('./sub-app')) where the module default-exports a handler or host router",
+      },
     });
   }
 
-  /**
-   * 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);
@@ -227,9 +262,8 @@ export function createHostRouter(options: HostRouterOptions = {}): HostRouter {
       return createRouteBuilder([], true);
     },
 
-    test(hostname: string): HostMatchResult | null {
-      const parts = hostname.split('.');
-      const pathname = '/';
+    test(hostname: string, pathname = "/"): HostMatchResult | null {
+      const parts = hostname.split(".");
 
       for (const route of routes) {
         for (const pattern of route.patterns) {
@@ -237,6 +271,7 @@ export function createHostRouter(options: HostRouterOptions = {}): HostRouter {
             return {
               pattern,
               handler: route.handler,
+              kind: route.kind,
             };
           }
         }
@@ -245,46 +280,43 @@ export function createHostRouter(options: HostRouterOptions = {}): HostRouter {
       return null;
     },
 
-    async match(request: Request, context: any = {}): Promise<Response> {
+    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,
-          context
-        );
+        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) {
-            context.error = error;
+            const fallbackInput = { ...input, error };
             const allMiddleware = [
               ...globalMiddleware,
               ...fallbackRoute.middleware,
             ];
 
-            return executeMiddleware(allMiddleware, request, context, () =>
-              executeHandler(fallbackRoute!.handler, request, context)
+            return executeMiddleware(
+              allMiddleware,
+              request,
+              fallbackInput,
+              () => executeHandler(fallbackRoute!, request, fallbackInput),
             );
           }
 
-          // Otherwise return error response with cookie deletion
           if (hostOverride) {
             return createCookieErrorResponse(
               hostOverride.cookieName,
-              error.message
+              error.message,
             );
           }
         }
 
-        // Re-throw non-HostRouterErrors
         throw error;
       }
 
@@ -294,7 +326,6 @@ export function createHostRouter(options: HostRouterOptions = {}): HostRouter {
         log(`Cookie override: ${effectiveHostname}`);
       }
 
-      // Find matching route
       const matchedRoute = findMatchingRoute(effectiveHostname, pathname);
 
       if (!matchedRoute) {
@@ -307,23 +338,22 @@ export function createHostRouter(options: HostRouterOptions = {}): HostRouter {
         });
       }
 
-      // 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)
+      return executeMiddleware(allMiddleware, request, input, () =>
+        executeHandler(matchedRoute, 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; },
+    get routes() {
+      return routes;
+    },
+    get fallback() {
+      return fallbackRoute;
+    },
   });
 
   return router;