@dotdo/postgres 0.1.0

package/src/routing/tenant-router.ts

@@ -0,0 +1,1908 @@
+/**
+ * Hostname-based Multi-tenant DO Routing
+ *
+ * Purpose: Route incoming requests to the correct Durable Object based on
+ * tenant identification extracted from hostname, path, or headers.
+ *
+ * This module provides a flexible tenant routing system that supports:
+ * - Subdomain-based tenancy (tenant1.app.com)
+ * - Path-based tenancy (/tenant1/api/...)
+ * - Header-based tenancy (X-Tenant-ID)
+ * - Custom extraction functions
+ * - Blocked tenant lists
+ * - Tenant isolation guarantees
+ */
+
+// =============================================================================
+// Constants
+// =============================================================================
+
+/**
+ * Standard HTTP header names used by the tenant router
+ */
+export const HEADERS = {
+  /** Header containing the tenant identifier */
+  TENANT_ID: 'X-Tenant-ID',
+  /** Header containing the correlation/request ID */
+  CORRELATION_ID: 'X-Correlation-ID',
+  /** Header containing the trace ID for distributed tracing */
+  TRACE_ID: 'X-Trace-ID',
+  /** Header containing the span ID for distributed tracing */
+  SPAN_ID: 'X-Span-ID',
+  /** Header containing the parent span ID for distributed tracing */
+  PARENT_SPAN_ID: 'X-Parent-Span-ID',
+  /** Header indicating whether the trace is sampled */
+  TRACE_SAMPLED: 'X-Trace-Sampled',
+} as const
+
+export type HeaderName = (typeof HEADERS)[keyof typeof HEADERS]
+
+export const DEFAULT_HEADER_NAME = HEADERS.TENANT_ID
+export const DEFAULT_PATH_PREFIX = '/'
+export const DEFAULT_REQUEST_TIMEOUT_MS = 30_000
+
+// Tenant ID validation constants
+const TENANT_ID_MAX_LENGTH = 128
+// Must start with alphanumeric, followed by alphanumeric, underscore, or hyphen
+const TENANT_ID_PATTERN = /^[a-zA-Z0-9][a-zA-Z0-9_-]*$/
+
+/**
+ * Normalize a path prefix to ensure consistent format.
+ * - Ensures path starts with '/'
+ * - Removes trailing '/' (except for root '/')
+ *
+ * @param prefix The path prefix to normalize
+ * @returns Normalized path prefix
+ */
+function normalizePathPrefix(prefix: string): string {
+  let normalized = prefix
+  if (!normalized.startsWith('/')) {
+    normalized = '/' + normalized
+  }
+  if (normalized.endsWith('/') && normalized.length > 1) {
+    normalized = normalized.slice(0, -1)
+  }
+  return normalized
+}
+
+/**
+ * Validate that a tenant ID is safe and well-formed.
+ *
+ * Security requirements:
+ * - Non-empty and within length limits
+ * - Starts with alphanumeric character
+ * - Contains only alphanumeric, underscore, or hyphen
+ * - No control characters (including null bytes)
+ * - No path traversal sequences
+ *
+ * @param tenantId The tenant ID to validate
+ * @returns true if the tenant ID is valid, false otherwise
+ */
+export function isValidTenantId(tenantId: string): boolean {
+  // Check length bounds
+  if (tenantId.length === 0 || tenantId.length > TENANT_ID_MAX_LENGTH) {
+    return false
+  }
+
+  // Check pattern (alphanumeric start, alphanumeric/underscore/hyphen continuation)
+  if (!TENANT_ID_PATTERN.test(tenantId)) {
+    return false
+  }
+
+  // Check for control characters (ASCII 0-31 and 127)
+  for (let i = 0; i < tenantId.length; i++) {
+    const charCode = tenantId.charCodeAt(i)
+    if (charCode < 32 || charCode === 127) {
+      return false
+    }
+  }
+
+  return true
+}
+
+// =============================================================================
+// Core Types
+// =============================================================================
+
+/**
+ * Source of tenant identification
+ */
+export type TenantExtractionSource = 'subdomain' | 'path' | 'header' | 'custom'
+
+/**
+ * Result of tenant extraction from a request
+ */
+export interface TenantExtractionResult {
+  /** The extracted tenant identifier, or null if extraction failed */
+  tenantId: string | null
+  /** How the tenant was identified */
+  source: TenantExtractionSource
+  /** Original hostname from the request */
+  originalHostname: string
+  /** Modified path (with tenant prefix stripped for path-based extraction) */
+  modifiedPath?: string | undefined
+  /** Additional metadata from custom extractors */
+  metadata?: Record<string, unknown> | undefined
+}
+
+/**
+ * Routing metadata about how the tenant was resolved
+ */
+export interface RoutingMetadata {
+  /** Which extractor type was used */
+  extractorType: TenantExtractionSource
+  /** Whether the tenant was found in cache (if caching is enabled) */
+  cached?: boolean
+  /** The DO ID that was generated */
+  doId: string
+}
+
+/**
+ * Timing information for the routing operation
+ */
+export interface RoutingTiming {
+  /** Time taken to extract tenant from request (ms) */
+  extractionTimeMs: number
+  /** Time taken to route to DO (ms) */
+  routingTimeMs: number
+  /** Total time for the entire operation (ms) */
+  totalTimeMs: number
+  /** Timestamp when routing started */
+  startTimestamp: number
+}
+
+/**
+ * Tenant context information
+ */
+export interface TenantContext {
+  /** The tenant identifier */
+  tenantId: string
+  /** How the tenant was identified */
+  source: TenantExtractionSource
+  /** Additional metadata from extraction */
+  metadata?: Record<string, unknown> | undefined
+}
+
+/**
+ * Result of routing a request to a tenant's DO
+ */
+export interface TenantRoutingResult {
+  /** The response from the DO */
+  response: Response
+  /** Routing metadata about how tenant was resolved */
+  routingMetadata: RoutingMetadata
+  /** Timing information for the operation */
+  timing: RoutingTiming
+  /** Tenant context information */
+  tenantContext: TenantContext
+}
+
+/**
+ * Function signature for custom tenant extraction
+ */
+export type TenantExtractor = (
+  request: Request
+) => TenantExtractionResult | Promise<TenantExtractionResult>
+
+/**
+ * Simplified extractor that just returns tenant ID or null
+ */
+export type SimpleTenantExtractor = (request: Request) => string | null | Promise<string | null>
+
+/**
+ * Preset extractor types
+ */
+export type PresetExtractorType = 'subdomain' | 'path' | 'header'
+
+/**
+ * Callback for dynamic blocked tenant checks
+ */
+export type BlockedTenantCallback = (
+  tenantId: string,
+  request: Request
+) => boolean | Promise<boolean>
+
+/**
+ * Function to transform tenant IDs before routing
+ */
+export type TenantTransformer = (tenantId: string) => string
+
+/**
+ * Custom error response formatter
+ */
+export type ErrorResponseFormatter = (
+  status: number,
+  message: string,
+  correlationId: string,
+  tenantId?: string
+) => Response
+
+// =============================================================================
+// Observability Types
+// =============================================================================
+
+/**
+ * Log levels for structured logging
+ */
+export type LogLevel = 'debug' | 'info' | 'warn' | 'error'
+
+/**
+ * Structured log entry
+ */
+export interface LogEntry {
+  level: LogLevel
+  message: string
+  tenantId?: string
+  correlationId?: string
+  timestamp: number
+  data?: Record<string, unknown>
+}
+
+/**
+ * Logger interface for observability
+ */
+export interface TenantRouterLogger {
+  log(entry: LogEntry): void
+  debug(message: string, data?: Record<string, unknown>): void
+  info(message: string, data?: Record<string, unknown>): void
+  warn(message: string, data?: Record<string, unknown>): void
+  error(message: string, data?: Record<string, unknown>): void
+}
+
+/**
+ * Metrics data for a single request
+ */
+export interface RequestMetrics {
+  tenantId: string
+  method: string
+  path: string
+  status: number
+  routingLatencyMs: number
+  doResponseTimeMs: number
+  timestamp: number
+  correlationId: string
+  traceId?: string | undefined
+  spanId?: string | undefined
+}
+
+/**
+ * Metrics collector interface for observability
+ */
+export interface MetricsCollector {
+  /**
+   * Record metrics for a routed request
+   */
+  recordRequest(metrics: RequestMetrics): void
+
+  /**
+   * Increment request count for a tenant
+   */
+  incrementRequestCount(tenantId: string): void
+
+  /**
+   * Record routing latency
+   */
+  recordLatency(tenantId: string, latencyMs: number): void
+
+  /**
+   * Record DO response time
+   */
+  recordDoResponseTime(tenantId: string, responseTimeMs: number): void
+}
+
+/**
+ * Trace context for distributed tracing
+ */
+export interface TraceContext {
+  traceId: string
+  spanId: string
+  parentSpanId?: string
+  sampled?: boolean
+}
+
+/**
+ * Function to extract trace context from request
+ */
+export type TraceContextExtractor = (request: Request) => TraceContext | null
+
+/**
+ * Function to generate a new span ID
+ */
+export type SpanIdGenerator = () => string
+
+// =============================================================================
+// Configuration Sub-interfaces
+// =============================================================================
+
+/**
+ * Core routing configuration
+ */
+export interface RoutingConfig {
+  /** The Durable Object namespace to route requests to */
+  doNamespace: DurableObjectNamespace
+
+  /**
+   * How to extract tenant from requests:
+   * - 'subdomain': Extract from hostname subdomain
+   * - 'path': Extract from URL path
+   * - 'header': Extract from HTTP header
+   * - TenantExtractor: Custom extraction function
+   */
+  extractTenant: TenantExtractor | SimpleTenantExtractor | PresetExtractorType
+
+  /**
+   * Base domain for subdomain extraction (e.g., 'app.com')
+   * Required for proper subdomain extraction with multi-level TLDs
+   */
+  baseDomain?: string
+
+  /**
+   * Path prefix for path-based extraction
+   * e.g., '/orgs' would extract from /orgs/{tenant}/...
+   * @default '/'
+   */
+  pathPrefix?: string
+
+  /**
+   * Header name for header-based extraction
+   * @default 'X-Tenant-ID'
+   */
+  headerName?: string
+
+  /**
+   * Request timeout in milliseconds
+   * @default 30000
+   */
+  requestTimeoutMs?: number
+
+  /**
+   * List of blocked tenant identifiers
+   * Supports exact matches and wildcard patterns (e.g., 'admin*')
+   */
+  blockedTenants?: string[]
+
+  /**
+   * Dynamic callback for checking if a tenant is blocked
+   */
+  blockedTenantCallback?: BlockedTenantCallback
+
+  /**
+   * Custom error response formatter
+   */
+  errorResponseFormatter?: ErrorResponseFormatter
+}
+
+/**
+ * Observability configuration
+ */
+export interface ObservabilityConfig {
+  /** Metrics collector for recording request metrics */
+  metricsCollector?: MetricsCollector
+
+  /** Logger for structured logging */
+  logger?: TenantRouterLogger
+
+  /** Function to extract trace context from incoming requests */
+  traceContextExtractor?: TraceContextExtractor
+
+  /**
+   * Whether to propagate trace context to forwarded requests
+   * @default true
+   */
+  propagateTraceContext?: boolean
+}
+
+/**
+ * Rate limiting configuration
+ */
+export interface RateLimitingConfig {
+  /**
+   * Enable rate limiting
+   * @default false
+   */
+  enabled?: boolean
+
+  /**
+   * Maximum requests allowed within the window
+   */
+  maxRequests?: number
+
+  /**
+   * Time window in milliseconds
+   * @default 60000 (1 minute)
+   */
+  windowMs?: number
+
+  /**
+   * List of tenant IDs that bypass rate limiting
+   */
+  bypassTenants?: string[]
+
+  /**
+   * Dynamic callback for checking if a tenant should bypass rate limiting
+   */
+  bypassCallback?: (tenantId: string, request: Request) => boolean | Promise<boolean>
+}
+
+/**
+ * Domain caching configuration
+ */
+export interface DomainCachingConfig {
+  /**
+   * Enable domain mapping cache
+   * @default false
+   */
+  enabled?: boolean
+
+  /**
+   * Cache TTL in milliseconds
+   * @default 300000 (5 minutes)
+   */
+  ttlMs?: number
+
+  /**
+   * Maximum number of cache entries
+   * @default 10000
+   */
+  maxEntries?: number
+}
+
+/**
+ * Complete tenant router configuration
+ * Extends RoutingConfig with nested sub-configs for better organization
+ */
+export interface TenantRouterConfig extends RoutingConfig {
+  /**
+   * Whether to strip the tenant segment from the forwarded path
+   * @default true
+   */
+  stripTenantFromPath?: boolean
+
+  /**
+   * Transform tenant ID before routing (e.g., lowercase normalization)
+   */
+  transformTenant?: TenantTransformer
+
+  /**
+   * Ordered list of extraction strategies to try
+   * First successful extraction wins
+   */
+  extractionOrder?: PresetExtractorType[]
+
+  /** Observability settings */
+  observability?: ObservabilityConfig
+
+  /** Rate limiting settings */
+  rateLimit?: RateLimitingConfig
+
+  /** Domain caching settings */
+  domainCache?: DomainCachingConfig
+
+  // =============================================================================
+  // Legacy flat config options (deprecated, use nested configs instead)
+  // =============================================================================
+
+  /**
+   * @deprecated Use blockedTenantCallback instead
+   * Dynamic callback for checking if a tenant is blocked
+   */
+  isBlocked?: BlockedTenantCallback
+
+  /**
+   * @deprecated Use errorResponseFormatter instead
+   * Custom error response formatter
+   */
+  formatError?: ErrorResponseFormatter
+
+  /**
+   * @deprecated Use domainCache.ttlMs instead
+   * Cache TTL for custom domain mappings in milliseconds
+   * @default 300000 (5 minutes)
+   */
+  domainCacheTtlMs?: number
+
+  /**
+   * @deprecated Use rateLimit.maxRequests instead (with windowMs: 60000)
+   * Per-tenant rate limit (requests per minute)
+   * Set to 0 to disable rate limiting
+   * @default 0
+   */
+  rateLimitPerMinute?: number
+
+  /**
+   * @deprecated Use observability.metricsCollector instead
+   * Metrics collector for recording request metrics
+   */
+  metricsCollector?: MetricsCollector
+
+  /**
+   * @deprecated Use observability.logger instead
+   * Logger for structured logging
+   */
+  logger?: TenantRouterLogger
+
+  /**
+   * @deprecated Use observability.traceContextExtractor instead
+   * Function to extract trace context from incoming requests
+   */
+  traceContextExtractor?: TraceContextExtractor
+
+  /**
+   * @deprecated Use observability.propagateTraceContext instead
+   * Whether to propagate trace context to forwarded requests
+   * @default true
+   */
+  propagateTraceContext?: boolean
+}
+
+// =============================================================================
+// Router Interface
+// =============================================================================
+
+/**
+ * The TenantRouter interface for routing requests to tenant-specific DOs
+ */
+export interface TenantRouter {
+  /**
+   * Route a request to the appropriate tenant's Durable Object
+   * @param request The incoming request
+   * @returns Response from the tenant's DO
+   *
+   * @example
+   * ```typescript
+   * export default {
+   *   async fetch(request: Request, env: Env) {
+   *     const router = createTenantRouter({
+   *       doNamespace: env.TENANT_DO,
+   *       extractTenant: 'subdomain',
+   *       baseDomain: 'myapp.com',
+   *     })
+   *
+   *     // Route request to tenant's DO
+   *     return router.route(request)
+   *   }
+   * }
+   * ```
+   */
+  route(request: Request): Promise<Response>
+
+  /**
+   * Route a request and return detailed routing result
+   * @param request The incoming request
+   * @returns Full routing result with response, metadata, timing, and context
+   *
+   * @example
+   * ```typescript
+   * const result = await router.routeWithResult(request)
+   *
+   * console.log(`Tenant: ${result.tenantContext.tenantId}`)
+   * console.log(`Source: ${result.routingMetadata.extractorType}`)
+   * console.log(`Total time: ${result.timing.totalTimeMs}ms`)
+   *
+   * return result.response
+   * ```
+   */
+  routeWithResult(request: Request): Promise<TenantRoutingResult>
+
+  /**
+   * Extract tenant ID from a request without routing
+   * @param request The incoming request
+   * @returns The tenant ID or null if not found
+   *
+   * @example
+   * ```typescript
+   * const tenantId = await router.getTenantId(request)
+   * if (!tenantId) {
+   *   return new Response('Tenant not found', { status: 400 })
+   * }
+   * console.log(`Processing request for tenant: ${tenantId}`)
+   * ```
+   */
+  getTenantId(request: Request): Promise<string | null>
+
+  /**
+   * Get full extraction result from a request
+   * @param request The incoming request
+   * @returns The extraction result with metadata
+   */
+  extractTenant(request: Request): Promise<TenantExtractionResult>
+
+  /**
+   * Check if a tenant is blocked
+   * @param tenantId The tenant identifier
+   * @param request The original request (for context in dynamic checks)
+   * @returns True if the tenant is blocked
+   */
+  isBlocked(tenantId: string, request: Request): Promise<boolean>
+
+  /**
+   * Get the DO stub for a specific tenant
+   * @param tenantId The tenant identifier
+   * @returns The Durable Object stub
+   *
+   * @example
+   * ```typescript
+   * const stub = router.getStub('acme-corp')
+   *
+   * // Make a custom request to the tenant's DO
+   * const response = await stub.fetch('https://internal/api/health')
+   * ```
+   */
+  getStub(tenantId: string): DurableObjectStub
+}
+
+// =============================================================================
+// Preset Extractors
+// =============================================================================
+
+/**
+ * Preset tenant extraction functions
+ *
+ * @example
+ * ```typescript
+ * // Use preset extractors with createTenantRouter
+ * const router = createTenantRouter({
+ *   doNamespace: env.TENANT_DO,
+ *   extractTenant: 'subdomain', // Uses extractors.subdomain internally
+ *   baseDomain: 'myapp.com',
+ * })
+ *
+ * // Or use extractors directly
+ * const subdomainExtractor = extractors.subdomain('myapp.com')
+ * const tenantId = subdomainExtractor(request) // 'acme' from acme.myapp.com
+ * ```
+ */
+export const extractors = {
+  /**
+   * Extract tenant from subdomain
+   * e.g., tenant1.app.com -> tenant1
+   *
+   * @param baseDomain Optional base domain for proper TLD handling
+   *
+   * @example
+   * ```typescript
+   * const extractor = extractors.subdomain('myapp.com')
+   *
+   * // acme.myapp.com -> 'acme'
+   * // www.myapp.com -> null (apex domain)
+   * // myapp.com -> null (apex domain)
+   * ```
+   */
+  subdomain:
+    (baseDomain?: string): SimpleTenantExtractor =>
+    (request: Request): string | null => {
+      const url = new URL(request.url)
+      let hostname = url.hostname.toLowerCase()
+
+      // Handle IP addresses - return null
+      if (/^(\d{1,3}\.){3}\d{1,3}$/.test(hostname)) {
+        return null
+      }
+
+      // Remove port if present (for localhost:8787 cases)
+      hostname = hostname.split(':')[0] ?? hostname
+
+      // If baseDomain is provided, use it to determine subdomain
+      if (baseDomain) {
+        const normalizedBaseDomain = baseDomain.toLowerCase()
+        // Check if hostname ends with the base domain
+        if (hostname === normalizedBaseDomain) {
+          // This is the apex domain
+          return null
+        }
+        if (hostname.endsWith('.' + normalizedBaseDomain)) {
+          // Extract subdomain part
+          const subdomainPart = hostname.slice(0, -(normalizedBaseDomain.length + 1))
+          const segments = subdomainPart.split('.')
+          // Handle www prefix
+          let firstSegment = segments[0]
+          if (firstSegment === 'www' && segments.length > 1) {
+            firstSegment = segments[1]
+          }
+          return firstSegment || null
+        }
+        // Hostname doesn't match base domain
+        return null
+      }
+
+      // Without baseDomain, parse generically
+      const parts = hostname.split('.')
+
+      // Handle localhost
+      if (parts.length === 1) {
+        return null // Just "localhost" or similar
+      }
+
+      // Handle common patterns
+      // For two-part domains like "app.com", return null (apex)
+      if (parts.length === 2) {
+        return null
+      }
+
+      // For three or more parts, first segment is tenant (unless it's www)
+      let tenantSegment = parts[0]
+      if (tenantSegment === 'www' && parts.length > 3) {
+        tenantSegment = parts[1]
+      } else if (tenantSegment === 'www') {
+        return null // www.app.com is still apex
+      }
+
+      return tenantSegment || null
+    },
+
+  /**
+   * Extract tenant from URL path
+   * e.g., /tenant1/api/users -> tenant1
+   *
+   * @param prefix Path prefix before tenant segment
+   *
+   * @example
+   * ```typescript
+   * const extractor = extractors.path('/orgs')
+   *
+   * // /orgs/acme/users -> 'acme'
+   * // /orgs/bigcorp/api/data -> 'bigcorp'
+   * // /api/users -> null (no match)
+   * ```
+   */
+  path:
+    (prefix: string = '/'): SimpleTenantExtractor =>
+    (request: Request): string | null => {
+      const url = new URL(request.url)
+      let pathname = url.pathname
+
+      const normalizedPrefix = normalizePathPrefix(prefix)
+
+      // Check if pathname starts with the prefix
+      if (normalizedPrefix !== '/' && !pathname.startsWith(normalizedPrefix)) {
+        return null
+      }
+
+      // Get the path after the prefix
+      let pathAfterPrefix: string
+      if (normalizedPrefix === '/') {
+        pathAfterPrefix = pathname
+      } else {
+        pathAfterPrefix = pathname.slice(normalizedPrefix.length)
+      }
+
+      // pathAfterPrefix should now start with / or be empty
+      if (!pathAfterPrefix || pathAfterPrefix === '/') {
+        return null
+      }
+
+      // Remove leading slash
+      if (pathAfterPrefix.startsWith('/')) {
+        pathAfterPrefix = pathAfterPrefix.slice(1)
+      }
+
+      // Get the first segment (tenant)
+      const slashIndex = pathAfterPrefix.indexOf('/')
+      let tenantSegment: string
+      if (slashIndex === -1) {
+        tenantSegment = pathAfterPrefix
+      } else {
+        tenantSegment = pathAfterPrefix.slice(0, slashIndex)
+      }
+
+      // Decode URL encoding
+      try {
+        tenantSegment = decodeURIComponent(tenantSegment)
+      } catch {
+        // If decoding fails, use as-is
+      }
+
+      // Return null for empty string
+      if (!tenantSegment) {
+        return null
+      }
+
+      return tenantSegment
+    },
+
+  /**
+   * Extract tenant from HTTP header
+   * e.g., X-Tenant-ID: tenant1 -> tenant1
+   *
+   * @param headerName The header to extract from
+   *
+   * @example
+   * ```typescript
+   * const extractor = extractors.header('X-Org-ID')
+   *
+   * // Request with header 'X-Org-ID: acme' -> 'acme'
+   * // Request without header -> null
+   * ```
+   */
+  header:
+    (headerName: string = DEFAULT_HEADER_NAME): SimpleTenantExtractor =>
+    (request: Request): string | null => {
+      // Headers.get() is case-insensitive per HTTP spec
+      const value = request.headers.get(headerName)
+
+      if (value === null) {
+        return null
+      }
+
+      // Trim whitespace
+      const trimmed = value.trim()
+
+      // Return null for empty string
+      if (!trimmed) {
+        return null
+      }
+
+      return trimmed
+    },
+
+  /**
+   * Try multiple extractors in order
+   * Returns first successful extraction
+   *
+   * @param extractorFns Array of extractors to try
+   *
+   * @example
+   * ```typescript
+   * // Try subdomain first, then fall back to header
+   * const extractor = extractors.combined([
+   *   extractors.subdomain('myapp.com'),
+   *   extractors.header('X-Tenant-ID'),
+   * ])
+   *
+   * // acme.myapp.com -> 'acme' (from subdomain)
+   * // myapp.com with X-Tenant-ID: bigcorp -> 'bigcorp' (from header)
+   * ```
+   */
+  combined:
+    (extractorFns: SimpleTenantExtractor[]): SimpleTenantExtractor =>
+    async (request: Request): Promise<string | null> => {
+      for (const extractor of extractorFns) {
+        const result = await extractor(request)
+        if (result !== null) {
+          return result
+        }
+      }
+      return null
+    },
+}
+
+// =============================================================================
+// Factory Function
+// =============================================================================
+
+/**
+ * Create a new TenantRouter instance
+ *
+ * @param config Router configuration
+ * @returns A configured TenantRouter
+ *
+ * @example
+ * ```typescript
+ * // Subdomain-based routing
+ * const router = createTenantRouter({
+ *   doNamespace: env.TENANT_DO,
+ *   extractTenant: 'subdomain',
+ *   baseDomain: 'myapp.com',
+ * })
+ *
+ * // Path-based routing
+ * const router = createTenantRouter({
+ *   doNamespace: env.TENANT_DO,
+ *   extractTenant: 'path',
+ *   pathPrefix: '/api/tenants',
+ * })
+ *
+ * // Header-based routing
+ * const router = createTenantRouter({
+ *   doNamespace: env.TENANT_DO,
+ *   extractTenant: 'header',
+ *   headerName: 'X-Org-ID',
+ * })
+ *
+ * // Custom extractor
+ * const router = createTenantRouter({
+ *   doNamespace: env.TENANT_DO,
+ *   extractTenant: (req) => {
+ *     const url = new URL(req.url)
+ *     return url.searchParams.get('tenant')
+ *   },
+ * })
+ * ```
+ */
+export function createTenantRouter(config: TenantRouterConfig): TenantRouter {
+  const {
+    doNamespace,
+    extractTenant,
+    headerName = DEFAULT_HEADER_NAME,
+    pathPrefix = DEFAULT_PATH_PREFIX,
+    stripTenantFromPath = true,
+    blockedTenants = [],
+    blockedTenantCallback,
+    isBlocked: legacyIsBlockedCallback, // deprecated
+    transformTenant,
+    requestTimeoutMs = DEFAULT_REQUEST_TIMEOUT_MS,
+    errorResponseFormatter,
+    formatError: legacyFormatError, // deprecated
+    baseDomain,
+    // Nested sub-configs
+    observability,
+    rateLimit: _rateLimit, // reserved for future use
+    domainCache: _domainCache, // reserved for future use
+    // Legacy flat observability options (deprecated)
+    metricsCollector: legacyMetricsCollector,
+    logger: legacyLogger,
+    traceContextExtractor: legacyTraceContextExtractor,
+    propagateTraceContext: legacyPropagateTraceContext,
+  } = config
+
+  // Resolve observability config: prefer nested config, fall back to legacy flat options
+  const metricsCollector = observability?.metricsCollector ?? legacyMetricsCollector
+  const logger = observability?.logger ?? legacyLogger
+  const traceContextExtractor = observability?.traceContextExtractor ?? legacyTraceContextExtractor
+  const propagateTraceContext = observability?.propagateTraceContext ?? legacyPropagateTraceContext ?? true
+
+  // Resolve blocked tenant callback: prefer new name, fall back to legacy
+  const isBlockedCallback = blockedTenantCallback ?? legacyIsBlockedCallback
+
+  // Resolve error formatter: prefer new name, fall back to legacy
+  const formatError = errorResponseFormatter ?? legacyFormatError
+
+  // Build the tenant extractor function
+  let tenantExtractor: TenantExtractor | SimpleTenantExtractor
+
+  if (typeof extractTenant === 'string') {
+    // Preset extractor type
+    switch (extractTenant) {
+      case 'subdomain':
+        tenantExtractor = extractors.subdomain(baseDomain)
+        break
+      case 'path':
+        tenantExtractor = extractors.path(pathPrefix)
+        break
+      case 'header':
+        tenantExtractor = extractors.header(headerName)
+        break
+      default:
+        throw new Error(`Invalid extractTenant value: ${extractTenant}`)
+    }
+  } else if (typeof extractTenant === 'function') {
+    tenantExtractor = extractTenant
+  } else {
+    throw new Error('extractTenant must be a string or function')
+  }
+
+  // Helper to generate correlation ID
+  function generateCorrelationId(): string {
+    return crypto.randomUUID()
+  }
+
+  // Helper to check if tenant matches a blocked pattern
+  function matchesBlockedPattern(tenantId: string, pattern: string): boolean {
+    if (pattern.endsWith('*')) {
+      const prefix = pattern.slice(0, -1)
+      return tenantId.startsWith(prefix)
+    }
+    return tenantId === pattern
+  }
+
+  // Default error formatter
+  function defaultFormatError(
+    status: number,
+    message: string,
+    correlationId: string,
+    _tenantId?: string
+  ): Response {
+    return new Response(
+      JSON.stringify({
+        error: message,
+        correlationId,
+      }),
+      {
+        status,
+        headers: {
+          'Content-Type': 'application/json',
+          [HEADERS.CORRELATION_ID]: correlationId,
+        },
+      }
+    )
+  }
+
+  const errorFormatter = formatError || defaultFormatError
+
+  // Implementation of the TenantRouter interface
+  const router: TenantRouter = {
+    async extractTenant(request: Request): Promise<TenantExtractionResult> {
+      const url = new URL(request.url)
+      const originalHostname = url.hostname
+
+      // Determine extraction source based on config
+      let source: TenantExtractionResult['source'] = 'custom'
+      if (typeof extractTenant === 'string') {
+        source = extractTenant as TenantExtractionResult['source']
+      }
+
+      // Call the extractor
+      let extractionResult = await tenantExtractor(request)
+
+      // Check if it's a full TenantExtractionResult or just a string/null
+      if (
+        extractionResult !== null &&
+        typeof extractionResult === 'object' &&
+        'tenantId' in extractionResult
+      ) {
+        // It's a full TenantExtractionResult
+        return extractionResult as TenantExtractionResult
+      }
+
+      // It's a SimpleTenantExtractor result (string | null)
+      let tenantId = extractionResult as string | null
+
+      // Apply transformation if configured
+      if (tenantId !== null && transformTenant) {
+        tenantId = transformTenant(tenantId)
+      }
+
+      // Build modified path for path-based extraction
+      let modifiedPath: string | undefined
+      if (source === 'path' && tenantId !== null && stripTenantFromPath) {
+        let pathname = url.pathname
+        const normalizedPrefix = normalizePathPrefix(pathPrefix)
+
+        // Remove prefix and tenant segment from path
+        let pathAfterPrefix: string
+        if (normalizedPrefix === '/') {
+          pathAfterPrefix = pathname
+        } else {
+          pathAfterPrefix = pathname.slice(normalizedPrefix.length)
+        }
+
+        // Remove leading slash and tenant segment
+        if (pathAfterPrefix.startsWith('/')) {
+          pathAfterPrefix = pathAfterPrefix.slice(1)
+        }
+        const slashIndex = pathAfterPrefix.indexOf('/')
+        if (slashIndex === -1) {
+          modifiedPath = '/'
+        } else {
+          modifiedPath = pathAfterPrefix.slice(slashIndex)
+        }
+      }
+
+      return {
+        tenantId,
+        source,
+        originalHostname,
+        modifiedPath,
+      }
+    },
+
+    async getTenantId(request: Request): Promise<string | null> {
+      const result = await router.extractTenant(request)
+      return result.tenantId
+    },
+
+    async isBlocked(tenantId: string, request: Request): Promise<boolean> {
+      // Check static blocked list
+      for (const pattern of blockedTenants) {
+        if (matchesBlockedPattern(tenantId, pattern)) {
+          return true
+        }
+      }
+
+      // Check dynamic callback
+      if (isBlockedCallback) {
+        return await isBlockedCallback(tenantId, request)
+      }
+
+      return false
+    },
+
+    getStub(tenantId: string): DurableObjectStub {
+      const doId = doNamespace.idFromName(tenantId)
+      return doNamespace.get(doId)
+    },
+
+    async route(request: Request): Promise<Response> {
+      const correlationId = generateCorrelationId()
+      const startTime = Date.now()
+      const requestUrl = new URL(request.url)
+
+      // Extract trace context from incoming request
+      let traceContext: TraceContext | null = null
+      if (traceContextExtractor) {
+        traceContext = traceContextExtractor(request)
+      }
+
+      // Log debug: routing decision starting
+      if (logger) {
+        logger.debug('Starting tenant routing', {
+          correlationId,
+          path: requestUrl.pathname,
+          method: request.method,
+          traceId: traceContext?.traceId,
+        })
+      }
+
+      let tenantId: string | null = null
+      let status = 500
+
+      try {
+        // Extract tenant
+        const extraction = await router.extractTenant(request)
+
+        if (extraction.tenantId === null) {
+          // Log extraction failure
+          if (logger) {
+            logger.warn('Tenant extraction failed', {
+              correlationId,
+              path: requestUrl.pathname,
+              method: request.method,
+              source: extraction.source,
+              hostname: extraction.originalHostname,
+            })
+          }
+          status = 400
+          return errorFormatter(400, 'Tenant identifier not found in request', correlationId)
+        }
+
+        tenantId = extraction.tenantId
+
+        // Log debug: tenant extracted
+        if (logger) {
+          logger.debug('Tenant routing decision', {
+            correlationId,
+            tenantId,
+            source: extraction.source,
+            path: requestUrl.pathname,
+          })
+        }
+
+        // Validate tenant ID format - comprehensive security validation
+        if (!isValidTenantId(tenantId)) {
+          status = 400
+          return errorFormatter(400, 'Invalid tenant identifier format', correlationId)
+        }
+
+        // Check if blocked
+        if (await router.isBlocked(tenantId, request)) {
+          status = 404
+          return errorFormatter(404, 'Not Found', correlationId, tenantId)
+        }
+
+        // Get DO stub
+        const stub = router.getStub(tenantId)
+
+        // If path-based and stripping tenant, use modified path
+        if (extraction.source === 'path' && stripTenantFromPath && extraction.modifiedPath) {
+          requestUrl.pathname = extraction.modifiedPath
+        }
+
+        // Clone headers and add tenant ID
+        const headers = new Headers(request.headers)
+        headers.set(HEADERS.TENANT_ID, tenantId)
+        headers.set(HEADERS.CORRELATION_ID, correlationId)
+
+        // Handle trace context propagation
+        if (propagateTraceContext && traceContext) {
+          // Propagate trace context headers
+          headers.set(HEADERS.TRACE_ID, traceContext.traceId)
+          headers.set(HEADERS.SPAN_ID, traceContext.spanId)
+          if (traceContext.parentSpanId) {
+            headers.set(HEADERS.PARENT_SPAN_ID, traceContext.parentSpanId)
+          }
+        } else if (!propagateTraceContext) {
+          // Remove trace context headers when propagation is disabled
+          headers.delete(HEADERS.TRACE_ID)
+          headers.delete(HEADERS.SPAN_ID)
+          headers.delete(HEADERS.PARENT_SPAN_ID)
+          headers.delete(HEADERS.TRACE_SAMPLED)
+        }
+
+        // Create new request with modified URL and headers
+        const forwardedRequest = new Request(requestUrl.toString(), {
+          method: request.method,
+          headers,
+          body: request.body,
+          // @ts-expect-error - duplex is needed for streaming bodies
+          duplex: request.body ? 'half' : undefined,
+        })
+
+        // Forward to DO with timeout
+        const controller = new AbortController()
+        const timeoutId = setTimeout(() => controller.abort(), requestTimeoutMs)
+        const doStartTime = Date.now()
+
+        try {
+          const response = await stub.fetch(forwardedRequest, {
+            signal: controller.signal,
+          })
+          clearTimeout(timeoutId)
+
+          const doResponseTimeMs = Date.now() - doStartTime
+          const routingLatencyMs = Date.now() - startTime
+          status = response.status
+
+          // Emit metrics
+          if (metricsCollector) {
+            metricsCollector.incrementRequestCount(tenantId)
+            metricsCollector.recordLatency(tenantId, routingLatencyMs)
+            metricsCollector.recordDoResponseTime(tenantId, doResponseTimeMs)
+            metricsCollector.recordRequest({
+              tenantId,
+              method: request.method,
+              path: requestUrl.pathname,
+              status: response.status,
+              routingLatencyMs,
+              doResponseTimeMs,
+              timestamp: startTime,
+              correlationId,
+              traceId: traceContext?.traceId,
+              spanId: traceContext?.spanId,
+            })
+          }
+
+          return response
+        } catch (error) {
+          clearTimeout(timeoutId)
+
+          if (error instanceof Error) {
+            if (error.name === 'AbortError') {
+              throw new TenantTimeoutError(tenantId, requestTimeoutMs)
+            }
+            throw new TenantUnavailableError(tenantId, error)
+          }
+          throw error
+        }
+      } catch (error) {
+        const routingLatencyMs = Date.now() - startTime
+
+        // Emit error metrics
+        if (metricsCollector && tenantId) {
+          metricsCollector.incrementRequestCount(tenantId)
+          metricsCollector.recordLatency(tenantId, routingLatencyMs)
+          metricsCollector.recordRequest({
+            tenantId,
+            method: request.method,
+            path: requestUrl.pathname,
+            status,
+            routingLatencyMs,
+            doResponseTimeMs: 0,
+            timestamp: startTime,
+            correlationId,
+            traceId: traceContext?.traceId,
+            spanId: traceContext?.spanId,
+          })
+        }
+
+        if (error instanceof TenantNotFoundError) {
+          return errorFormatter(400, 'Tenant identifier not found in request', correlationId)
+        }
+
+        if (error instanceof TenantBlockedError) {
+          return errorFormatter(404, 'Not Found', correlationId, error.tenantId)
+        }
+
+        if (error instanceof InvalidTenantIdError) {
+          return errorFormatter(400, 'Invalid tenant identifier format', correlationId)
+        }
+
+        if (error instanceof TenantTimeoutError) {
+          return errorFormatter(504, 'Gateway Timeout', correlationId, error.tenantId)
+        }
+
+        if (error instanceof TenantUnavailableError) {
+          return errorFormatter(502, 'Bad Gateway', correlationId, error.tenantId)
+        }
+
+        // Generic error - don't expose details
+        return errorFormatter(500, 'Internal Server Error', correlationId)
+      }
+    },
+
+    async routeWithResult(request: Request): Promise<TenantRoutingResult> {
+      const startTimestamp = Date.now()
+      const correlationId = generateCorrelationId()
+
+      // Extract tenant with timing
+      const extractionStartTime = Date.now()
+      const extraction = await router.extractTenant(request)
+      const extractionTimeMs = Date.now() - extractionStartTime
+
+      if (extraction.tenantId === null) {
+        throw new TenantNotFoundError('Tenant identifier not found in request', request)
+      }
+
+      const tenantId = extraction.tenantId
+
+      // Validate tenant ID format - comprehensive security validation
+      if (!isValidTenantId(tenantId)) {
+        throw new InvalidTenantIdError(tenantId)
+      }
+
+      // Check if blocked
+      if (await router.isBlocked(tenantId, request)) {
+        throw new TenantBlockedError(tenantId)
+      }
+
+      // Get DO stub and ID
+      const doId = doNamespace.idFromName(tenantId)
+      const stub = doNamespace.get(doId)
+
+      // Build forwarded request
+      const url = new URL(request.url)
+
+      // If path-based and stripping tenant, use modified path
+      if (extraction.source === 'path' && stripTenantFromPath && extraction.modifiedPath) {
+        url.pathname = extraction.modifiedPath
+      }
+
+      // Clone headers and add tenant ID
+      const headers = new Headers(request.headers)
+      headers.set(HEADERS.TENANT_ID, tenantId)
+      headers.set(HEADERS.CORRELATION_ID, correlationId)
+
+      // Create new request with modified URL and headers
+      const forwardedRequest = new Request(url.toString(), {
+        method: request.method,
+        headers,
+        body: request.body,
+        // @ts-expect-error - duplex is needed for streaming bodies
+        duplex: request.body ? 'half' : undefined,
+      })
+
+      // Forward to DO with timeout
+      const controller = new AbortController()
+      const timeoutId = setTimeout(() => controller.abort(), requestTimeoutMs)
+      const routingStartTime = Date.now()
+
+      try {
+        const response = await stub.fetch(forwardedRequest, {
+          signal: controller.signal,
+        })
+        clearTimeout(timeoutId)
+
+        const routingTimeMs = Date.now() - routingStartTime
+        const totalTimeMs = Date.now() - startTimestamp
+
+        return {
+          response,
+          routingMetadata: {
+            extractorType: extraction.source,
+            doId: doId.toString(),
+          },
+          timing: {
+            extractionTimeMs,
+            routingTimeMs,
+            totalTimeMs,
+            startTimestamp,
+          },
+          tenantContext: {
+            tenantId,
+            source: extraction.source,
+            metadata: extraction.metadata,
+          },
+        }
+      } catch (error) {
+        clearTimeout(timeoutId)
+
+        if (error instanceof Error) {
+          if (error.name === 'AbortError') {
+            throw new TenantTimeoutError(tenantId, requestTimeoutMs)
+          }
+          throw new TenantUnavailableError(tenantId, error)
+        }
+        throw error
+      }
+    },
+  }
+
+  return router
+}
+
+// =============================================================================
+// Helper Types
+// =============================================================================
+
+/**
+ * Request with tenant context attached
+ */
+export interface TenantRequest extends Request {
+  tenantId: string
+  tenantMetadata?: Record<string, unknown>
+}
+
+/**
+ * Tenant routing metrics
+ */
+export interface TenantRoutingMetrics {
+  requestCount: number
+  successCount: number
+  errorCount: number
+  blockedCount: number
+  avgRoutingLatencyMs: number
+  avgDoResponseTimeMs: number
+}
+
+/**
+ * Per-tenant metrics
+ */
+export interface PerTenantMetrics {
+  tenantId: string
+  requestCount: number
+  lastRequestAt: number
+  avgResponseTimeMs: number
+}
+
+// =============================================================================
+// Error Types
+// =============================================================================
+
+/**
+ * Error thrown when tenant cannot be identified
+ */
+export class TenantNotFoundError extends Error {
+  constructor(
+    message: string = 'Tenant identifier not found in request',
+    public readonly request?: Request
+  ) {
+    super(message)
+    this.name = 'TenantNotFoundError'
+  }
+}
+
+/**
+ * Error thrown when tenant is blocked
+ */
+export class TenantBlockedError extends Error {
+  constructor(
+    public readonly tenantId: string,
+    message: string = 'Tenant is blocked'
+  ) {
+    super(message)
+    this.name = 'TenantBlockedError'
+  }
+}
+
+/**
+ * Error thrown when tenant ID format is invalid
+ */
+export class InvalidTenantIdError extends Error {
+  constructor(
+    public readonly tenantId: string,
+    message: string = 'Invalid tenant identifier format'
+  ) {
+    super(message)
+    this.name = 'InvalidTenantIdError'
+  }
+}
+
+/**
+ * Error thrown when DO request times out
+ */
+export class TenantTimeoutError extends Error {
+  constructor(
+    public readonly tenantId: string,
+    public readonly timeoutMs: number,
+    message: string = 'Tenant DO request timed out'
+  ) {
+    super(message)
+    this.name = 'TenantTimeoutError'
+  }
+}
+
+/**
+ * Error thrown when DO is unreachable
+ */
+export class TenantUnavailableError extends Error {
+  public readonly tenantId: string
+  public override readonly cause?: Error | undefined
+
+  constructor(
+    tenantId: string,
+    cause?: Error,
+    message: string = 'Tenant DO is unavailable'
+  ) {
+    super(message)
+    this.tenantId = tenantId
+    this.cause = cause
+    this.name = 'TenantUnavailableError'
+  }
+}
+
+// =============================================================================
+// Rate Limiting
+// =============================================================================
+
+/**
+ * Rate limit configuration
+ */
+export interface RateLimitConfig {
+  /**
+   * Maximum requests allowed within the window
+   */
+  maxRequests: number
+
+  /**
+   * Time window in milliseconds
+   * @default 60000 (1 minute)
+   */
+  windowMs?: number
+
+  /**
+   * List of tenant IDs that bypass rate limiting
+   */
+  bypassTenants?: string[]
+
+  /**
+   * Custom function to determine if a tenant should bypass rate limiting
+   */
+  bypassCallback?: (tenantId: string, request: Request) => boolean | Promise<boolean>
+}
+
+/**
+ * Rate limit state for a single tenant
+ */
+export interface RateLimitState {
+  /** Number of requests in the current window */
+  requestCount: number
+  /** Timestamp when the window started */
+  windowStart: number
+}
+
+/**
+ * Rate limit check result
+ */
+export interface RateLimitResult {
+  /** Whether the request is allowed */
+  allowed: boolean
+  /** Current request count in the window */
+  currentCount: number
+  /** Maximum requests allowed */
+  maxRequests: number
+  /** Seconds until the rate limit resets */
+  retryAfterSeconds: number
+  /** Whether this tenant bypasses rate limiting */
+  bypassed: boolean
+}
+
+/**
+ * In-memory rate limiter for per-tenant request tracking
+ */
+export class TenantRateLimiter {
+  private state: Map<string, RateLimitState> = new Map()
+  private readonly maxRequests: number
+  private readonly windowMs: number
+  private readonly bypassTenants: Set<string>
+  private readonly bypassCallback?: ((tenantId: string, request: Request) => boolean | Promise<boolean>) | undefined
+
+  constructor(config: RateLimitConfig) {
+    this.maxRequests = config.maxRequests
+    this.windowMs = config.windowMs ?? 60_000
+    this.bypassTenants = new Set(config.bypassTenants ?? [])
+    this.bypassCallback = config.bypassCallback
+  }
+
+  /**
+   * Check if a request should be allowed for the given tenant
+   */
+  async check(tenantId: string, request: Request): Promise<RateLimitResult> {
+    // Periodic cleanup of expired entries (1% chance per request)
+    if (Math.random() < 0.01) {
+      this.cleanupExpiredEntries()
+    }
+
+    // Check bypass list first
+    if (this.bypassTenants.has(tenantId)) {
+      return {
+        allowed: true,
+        currentCount: 0,
+        maxRequests: this.maxRequests,
+        retryAfterSeconds: 0,
+        bypassed: true,
+      }
+    }
+
+    // Check bypass callback
+    if (this.bypassCallback) {
+      const shouldBypass = await this.bypassCallback(tenantId, request)
+      if (shouldBypass) {
+        return {
+          allowed: true,
+          currentCount: 0,
+          maxRequests: this.maxRequests,
+          retryAfterSeconds: 0,
+          bypassed: true,
+        }
+      }
+    }
+
+    const now = Date.now()
+    let tenantState = this.state.get(tenantId)
+
+    // Initialize or reset window if expired
+    if (!tenantState || now - tenantState.windowStart >= this.windowMs) {
+      tenantState = {
+        requestCount: 0,
+        windowStart: now,
+      }
+      this.state.set(tenantId, tenantState)
+    }
+
+    // Calculate retry-after
+    const windowEnd = tenantState.windowStart + this.windowMs
+    const retryAfterSeconds = Math.ceil((windowEnd - now) / 1000)
+
+    // Check if limit exceeded
+    if (tenantState.requestCount >= this.maxRequests) {
+      return {
+        allowed: false,
+        currentCount: tenantState.requestCount,
+        maxRequests: this.maxRequests,
+        retryAfterSeconds,
+        bypassed: false,
+      }
+    }
+
+    // Increment and allow
+    tenantState.requestCount++
+
+    return {
+      allowed: true,
+      currentCount: tenantState.requestCount,
+      maxRequests: this.maxRequests,
+      retryAfterSeconds,
+      bypassed: false,
+    }
+  }
+
+  /**
+   * Get the current state for a tenant (for testing/debugging)
+   */
+  getState(tenantId: string): RateLimitState | undefined {
+    return this.state.get(tenantId)
+  }
+
+  /**
+   * Reset rate limit state for a tenant
+   */
+  reset(tenantId: string): void {
+    this.state.delete(tenantId)
+  }
+
+  /**
+   * Reset all rate limit state
+   */
+  resetAll(): void {
+    this.state.clear()
+  }
+
+  /**
+   * Clean up expired entries from the rate limit state map
+   * Removes entries that are 2x past their window to prevent unbounded memory growth
+   */
+  private cleanupExpiredEntries(): void {
+    const now = Date.now()
+    for (const [tenantId, state] of this.state.entries()) {
+      // Remove entries that are 2x past their window
+      if (now - state.windowStart >= this.windowMs * 2) {
+        this.state.delete(tenantId)
+      }
+    }
+  }
+
+  /**
+   * Get the current number of tracked tenants (for monitoring/debugging)
+   */
+  getTrackedTenantCount(): number {
+    return this.state.size
+  }
+}
+
+/**
+ * Error thrown when rate limit is exceeded
+ */
+export class TenantRateLimitError extends Error {
+  constructor(
+    public readonly tenantId: string,
+    public readonly retryAfterSeconds: number,
+    message: string = 'Rate limit exceeded'
+  ) {
+    super(message)
+    this.name = 'TenantRateLimitError'
+  }
+}
+
+// =============================================================================
+// Caching Types and Implementation
+// =============================================================================
+
+/**
+ * Cache entry for domain-to-tenant mappings
+ */
+export interface DomainCacheEntry {
+  /** The tenant ID mapped to this domain */
+  tenantId: string
+  /** Timestamp when this entry was cached */
+  cachedAt: number
+  /** Additional metadata */
+  metadata?: Record<string, unknown> | undefined
+}
+
+/**
+ * Configuration for the domain mapping cache
+ */
+export interface DomainCacheConfig {
+  /** TTL for cache entries in milliseconds */
+  ttlMs: number
+  /** Maximum number of entries to cache */
+  maxEntries?: number
+}
+
+/**
+ * Cache statistics
+ */
+export interface CacheStats {
+  hits: number
+  misses: number
+  size: number
+  invalidations: number
+}
+
+/**
+ * Interface for domain-to-tenant mapping cache
+ */
+export interface DomainMappingCache {
+  /** Get a cached tenant ID for a domain */
+  get(domain: string): DomainCacheEntry | null
+  /** Set a domain-to-tenant mapping in the cache */
+  set(domain: string, tenantId: string, metadata?: Record<string, unknown>): void
+  /** Invalidate a specific domain mapping */
+  invalidate(domain: string): void
+  /** Invalidate all cache entries */
+  invalidateAll(): void
+  /** Check if cache has a valid (non-expired) entry for a domain */
+  has(domain: string): boolean
+  /** Warm the cache with known domain-to-tenant mappings */
+  warm(mappings: Record<string, string>): void
+  /** Get the current cache size */
+  size(): number
+  /** Get cache statistics */
+  stats(): CacheStats
+}
+
+/**
+ * Create a new domain mapping cache
+ *
+ * @param config Cache configuration
+ * @returns A DomainMappingCache instance
+ *
+ * @example
+ * ```typescript
+ * const cache = createDomainMappingCache({ ttlMs: 300000 }) // 5 minute TTL
+ *
+ * // Set a mapping
+ * cache.set('custom.example.com', 'tenant1')
+ *
+ * // Get a mapping (returns null if expired or not found)
+ * const entry = cache.get('custom.example.com')
+ * if (entry) {
+ *   console.log(entry.tenantId) // 'tenant1'
+ * }
+ *
+ * // Warm cache on startup
+ * cache.warm({
+ *   'acme.com': 'acme-inc',
+ *   'bigcorp.io': 'bigcorp',
+ * })
+ *
+ * // Invalidate on config change
+ * cache.invalidate('acme.com')
+ * // or invalidate all
+ * cache.invalidateAll()
+ * ```
+ */
+export function createDomainMappingCache(config: DomainCacheConfig): DomainMappingCache {
+  const { ttlMs, maxEntries = 10000 } = config
+  const cache = new Map<string, DomainCacheEntry>()
+  let hits = 0
+  let misses = 0
+  let invalidations = 0
+
+  // Helper to check if an entry is expired
+  function isExpired(entry: DomainCacheEntry): boolean {
+    return Date.now() - entry.cachedAt > ttlMs
+  }
+
+  // Helper to evict oldest entries if over capacity
+  function evictIfNeeded(): void {
+    if (cache.size <= maxEntries) return
+
+    // Find and remove oldest entries
+    const entries = Array.from(cache.entries())
+    entries.sort((a, b) => a[1].cachedAt - b[1].cachedAt)
+    const toRemove = entries.slice(0, cache.size - maxEntries)
+    for (const [key] of toRemove) {
+      cache.delete(key)
+    }
+  }
+
+  return {
+    get(domain: string): DomainCacheEntry | null {
+      const normalizedDomain = domain.toLowerCase()
+      const entry = cache.get(normalizedDomain)
+
+      if (!entry) {
+        misses++
+        return null
+      }
+
+      if (isExpired(entry)) {
+        cache.delete(normalizedDomain)
+        misses++
+        return null
+      }
+
+      hits++
+      return entry
+    },
+
+    set(domain: string, tenantId: string, metadata?: Record<string, unknown>): void {
+      const normalizedDomain = domain.toLowerCase()
+      cache.set(normalizedDomain, {
+        tenantId,
+        cachedAt: Date.now(),
+        metadata,
+      })
+      evictIfNeeded()
+    },
+
+    invalidate(domain: string): void {
+      const normalizedDomain = domain.toLowerCase()
+      if (cache.delete(normalizedDomain)) {
+        invalidations++
+      }
+    },
+
+    invalidateAll(): void {
+      const count = cache.size
+      cache.clear()
+      invalidations += count
+    },
+
+    has(domain: string): boolean {
+      const normalizedDomain = domain.toLowerCase()
+      const entry = cache.get(normalizedDomain)
+      if (!entry) return false
+      if (isExpired(entry)) {
+        cache.delete(normalizedDomain)
+        return false
+      }
+      return true
+    },
+
+    warm(mappings: Record<string, string>): void {
+      const now = Date.now()
+      for (const [domain, tenantId] of Object.entries(mappings)) {
+        const normalizedDomain = domain.toLowerCase()
+        cache.set(normalizedDomain, {
+          tenantId,
+          cachedAt: now,
+        })
+      }
+      evictIfNeeded()
+    },
+
+    size(): number {
+      return cache.size
+    },
+
+    stats(): CacheStats {
+      return {
+        hits,
+        misses,
+        size: cache.size,
+        invalidations,
+      }
+    },
+  }
+}