@dotdo/postgres 0.1.0

package/dist/routing/tenant-router.d.ts

@@ -0,0 +1,848 @@
+/**
+ * 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
+ */
+/**
+ * Standard HTTP header names used by the tenant router
+ */
+export declare const HEADERS: {
+    /** Header containing the tenant identifier */
+    readonly TENANT_ID: "X-Tenant-ID";
+    /** Header containing the correlation/request ID */
+    readonly CORRELATION_ID: "X-Correlation-ID";
+    /** Header containing the trace ID for distributed tracing */
+    readonly TRACE_ID: "X-Trace-ID";
+    /** Header containing the span ID for distributed tracing */
+    readonly SPAN_ID: "X-Span-ID";
+    /** Header containing the parent span ID for distributed tracing */
+    readonly PARENT_SPAN_ID: "X-Parent-Span-ID";
+    /** Header indicating whether the trace is sampled */
+    readonly TRACE_SAMPLED: "X-Trace-Sampled";
+};
+export type HeaderName = (typeof HEADERS)[keyof typeof HEADERS];
+export declare const DEFAULT_HEADER_NAME: "X-Tenant-ID";
+export declare const DEFAULT_PATH_PREFIX = "/";
+export declare const DEFAULT_REQUEST_TIMEOUT_MS = 30000;
+/**
+ * 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 declare function isValidTenantId(tenantId: string): boolean;
+/**
+ * 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;
+/**
+ * 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;
+/**
+ * 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;
+    /**
+     * @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;
+}
+/**
+ * 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 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 declare 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;
+    /**
+     * 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;
+    /**
+     * 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) => SimpleTenantExtractor;
+    /**
+     * 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;
+};
+/**
+ * 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 declare function createTenantRouter(config: TenantRouterConfig): TenantRouter;
+/**
+ * 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 thrown when tenant cannot be identified
+ */
+export declare class TenantNotFoundError extends Error {
+    readonly request?: Request | undefined;
+    constructor(message?: string, request?: Request | undefined);
+}
+/**
+ * Error thrown when tenant is blocked
+ */
+export declare class TenantBlockedError extends Error {
+    readonly tenantId: string;
+    constructor(tenantId: string, message?: string);
+}
+/**
+ * Error thrown when tenant ID format is invalid
+ */
+export declare class InvalidTenantIdError extends Error {
+    readonly tenantId: string;
+    constructor(tenantId: string, message?: string);
+}
+/**
+ * Error thrown when DO request times out
+ */
+export declare class TenantTimeoutError extends Error {
+    readonly tenantId: string;
+    readonly timeoutMs: number;
+    constructor(tenantId: string, timeoutMs: number, message?: string);
+}
+/**
+ * Error thrown when DO is unreachable
+ */
+export declare class TenantUnavailableError extends Error {
+    readonly tenantId: string;
+    readonly cause?: Error | undefined;
+    constructor(tenantId: string, cause?: Error, message?: string);
+}
+/**
+ * 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 declare class TenantRateLimiter {
+    private state;
+    private readonly maxRequests;
+    private readonly windowMs;
+    private readonly bypassTenants;
+    private readonly bypassCallback?;
+    constructor(config: RateLimitConfig);
+    /**
+     * Check if a request should be allowed for the given tenant
+     */
+    check(tenantId: string, request: Request): Promise<RateLimitResult>;
+    /**
+     * Get the current state for a tenant (for testing/debugging)
+     */
+    getState(tenantId: string): RateLimitState | undefined;
+    /**
+     * Reset rate limit state for a tenant
+     */
+    reset(tenantId: string): void;
+    /**
+     * Reset all rate limit state
+     */
+    resetAll(): void;
+    /**
+     * 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;
+    /**
+     * Get the current number of tracked tenants (for monitoring/debugging)
+     */
+    getTrackedTenantCount(): number;
+}
+/**
+ * Error thrown when rate limit is exceeded
+ */
+export declare class TenantRateLimitError extends Error {
+    readonly tenantId: string;
+    readonly retryAfterSeconds: number;
+    constructor(tenantId: string, retryAfterSeconds: number, message?: string);
+}
+/**
+ * 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 declare function createDomainMappingCache(config: DomainCacheConfig): DomainMappingCache;
+//# sourceMappingURL=tenant-router.d.ts.map