@dotdo/postgres 0.1.0

package/dist/routing/tenant-router.js

@@ -0,0 +1,1056 @@
+/**
+ * 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',
+};
+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) {
+    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) {
+    // 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;
+}
+// =============================================================================
+// 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) => (request) => {
+        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 = '/') => (request) => {
+        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;
+        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;
+        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 = DEFAULT_HEADER_NAME) => (request) => {
+        // 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) => async (request) => {
+        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) {
+    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;
+    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() {
+        return crypto.randomUUID();
+    }
+    // Helper to check if tenant matches a blocked pattern
+    function matchesBlockedPattern(tenantId, pattern) {
+        if (pattern.endsWith('*')) {
+            const prefix = pattern.slice(0, -1);
+            return tenantId.startsWith(prefix);
+        }
+        return tenantId === pattern;
+    }
+    // Default error formatter
+    function defaultFormatError(status, message, correlationId, _tenantId) {
+        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 = {
+        async extractTenant(request) {
+            const url = new URL(request.url);
+            const originalHostname = url.hostname;
+            // Determine extraction source based on config
+            let source = 'custom';
+            if (typeof extractTenant === 'string') {
+                source = extractTenant;
+            }
+            // 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;
+            }
+            // It's a SimpleTenantExtractor result (string | null)
+            let tenantId = extractionResult;
+            // Apply transformation if configured
+            if (tenantId !== null && transformTenant) {
+                tenantId = transformTenant(tenantId);
+            }
+            // Build modified path for path-based extraction
+            let modifiedPath;
+            if (source === 'path' && tenantId !== null && stripTenantFromPath) {
+                let pathname = url.pathname;
+                const normalizedPrefix = normalizePathPrefix(pathPrefix);
+                // Remove prefix and tenant segment from path
+                let pathAfterPrefix;
+                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) {
+            const result = await router.extractTenant(request);
+            return result.tenantId;
+        },
+        async isBlocked(tenantId, request) {
+            // 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) {
+            const doId = doNamespace.idFromName(tenantId);
+            return doNamespace.get(doId);
+        },
+        async route(request) {
+            const correlationId = generateCorrelationId();
+            const startTime = Date.now();
+            const requestUrl = new URL(request.url);
+            // Extract trace context from incoming request
+            let traceContext = 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 = 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) {
+            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;
+}
+// =============================================================================
+// Error Types
+// =============================================================================
+/**
+ * Error thrown when tenant cannot be identified
+ */
+export class TenantNotFoundError extends Error {
+    request;
+    constructor(message = 'Tenant identifier not found in request', request) {
+        super(message);
+        this.request = request;
+        this.name = 'TenantNotFoundError';
+    }
+}
+/**
+ * Error thrown when tenant is blocked
+ */
+export class TenantBlockedError extends Error {
+    tenantId;
+    constructor(tenantId, message = 'Tenant is blocked') {
+        super(message);
+        this.tenantId = tenantId;
+        this.name = 'TenantBlockedError';
+    }
+}
+/**
+ * Error thrown when tenant ID format is invalid
+ */
+export class InvalidTenantIdError extends Error {
+    tenantId;
+    constructor(tenantId, message = 'Invalid tenant identifier format') {
+        super(message);
+        this.tenantId = tenantId;
+        this.name = 'InvalidTenantIdError';
+    }
+}
+/**
+ * Error thrown when DO request times out
+ */
+export class TenantTimeoutError extends Error {
+    tenantId;
+    timeoutMs;
+    constructor(tenantId, timeoutMs, message = 'Tenant DO request timed out') {
+        super(message);
+        this.tenantId = tenantId;
+        this.timeoutMs = timeoutMs;
+        this.name = 'TenantTimeoutError';
+    }
+}
+/**
+ * Error thrown when DO is unreachable
+ */
+export class TenantUnavailableError extends Error {
+    tenantId;
+    cause;
+    constructor(tenantId, cause, message = 'Tenant DO is unavailable') {
+        super(message);
+        this.tenantId = tenantId;
+        this.cause = cause;
+        this.name = 'TenantUnavailableError';
+    }
+}
+/**
+ * In-memory rate limiter for per-tenant request tracking
+ */
+export class TenantRateLimiter {
+    state = new Map();
+    maxRequests;
+    windowMs;
+    bypassTenants;
+    bypassCallback;
+    constructor(config) {
+        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, request) {
+        // 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) {
+        return this.state.get(tenantId);
+    }
+    /**
+     * Reset rate limit state for a tenant
+     */
+    reset(tenantId) {
+        this.state.delete(tenantId);
+    }
+    /**
+     * Reset all rate limit state
+     */
+    resetAll() {
+        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
+     */
+    cleanupExpiredEntries() {
+        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() {
+        return this.state.size;
+    }
+}
+/**
+ * Error thrown when rate limit is exceeded
+ */
+export class TenantRateLimitError extends Error {
+    tenantId;
+    retryAfterSeconds;
+    constructor(tenantId, retryAfterSeconds, message = 'Rate limit exceeded') {
+        super(message);
+        this.tenantId = tenantId;
+        this.retryAfterSeconds = retryAfterSeconds;
+        this.name = 'TenantRateLimitError';
+    }
+}
+/**
+ * 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) {
+    const { ttlMs, maxEntries = 10000 } = config;
+    const cache = new Map();
+    let hits = 0;
+    let misses = 0;
+    let invalidations = 0;
+    // Helper to check if an entry is expired
+    function isExpired(entry) {
+        return Date.now() - entry.cachedAt > ttlMs;
+    }
+    // Helper to evict oldest entries if over capacity
+    function evictIfNeeded() {
+        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) {
+            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, tenantId, metadata) {
+            const normalizedDomain = domain.toLowerCase();
+            cache.set(normalizedDomain, {
+                tenantId,
+                cachedAt: Date.now(),
+                metadata,
+            });
+            evictIfNeeded();
+        },
+        invalidate(domain) {
+            const normalizedDomain = domain.toLowerCase();
+            if (cache.delete(normalizedDomain)) {
+                invalidations++;
+            }
+        },
+        invalidateAll() {
+            const count = cache.size;
+            cache.clear();
+            invalidations += count;
+        },
+        has(domain) {
+            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) {
+            const now = Date.now();
+            for (const [domain, tenantId] of Object.entries(mappings)) {
+                const normalizedDomain = domain.toLowerCase();
+                cache.set(normalizedDomain, {
+                    tenantId,
+                    cachedAt: now,
+                });
+            }
+            evictIfNeeded();
+        },
+        size() {
+            return cache.size;
+        },
+        stats() {
+            return {
+                hits,
+                misses,
+                size: cache.size,
+                invalidations,
+            };
+        },
+    };
+}
+//# sourceMappingURL=tenant-router.js.map