@dotdo/postgres 0.1.0

package/src/routing/tenant-router.test.ts

@@ -0,0 +1,2493 @@
+/**
+ * RED PHASE TESTS: 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.
+ *
+ * Key features:
+ * - Extract tenant from subdomain (tenant1.app.com)
+ * - Extract tenant from full hostname (custom domains)
+ * - Extract tenant from path (/tenant1/...)
+ * - Extract tenant from header (X-Tenant-ID)
+ * - Route to correct DO with tenant isolation
+ * - Support blocked tenant lists
+ * - Custom tenant resolver functions
+ */
+
+import { describe, it, expect, vi, beforeEach } from 'vitest'
+import {
+  TenantRouter,
+  TenantRouterConfig,
+  TenantExtractor,
+  TenantExtractionResult,
+  TenantRoutingResult,
+  RoutingMetadata,
+  RoutingTiming,
+  TenantContext,
+  createTenantRouter,
+  extractors,
+  DEFAULT_HEADER_NAME,
+  DEFAULT_PATH_PREFIX,
+  SimpleTenantExtractor,
+  TenantRateLimiter,
+  RateLimitConfig,
+  RateLimitResult,
+  createDomainMappingCache,
+  MetricsCollector,
+  RequestMetrics,
+  TenantRouterLogger,
+  LogEntry,
+  TraceContext,
+  TraceContextExtractor,
+  DomainMappingCache,
+  DomainCacheConfig,
+  DomainCacheEntry,
+  CacheStats,
+} from './tenant-router'
+import {
+  createMockRequest,
+  createMockDONamespace,
+} from '../__tests__/test-utils'
+
+describe('TenantRouter', () => {
+  describe('hostname extraction', () => {
+    it('should extract tenant from subdomain: tenant1.app.com -> tenant1', () => {
+      const extractor = extractors.subdomain('app.com')
+      const request = createMockRequest('https://tenant1.app.com/api/users')
+      expect(extractor(request)).toBe('tenant1')
+    })
+
+    it('should extract tenant from subdomain with multiple levels: tenant1.api.app.com -> tenant1', () => {
+      const extractor = extractors.subdomain('app.com')
+      const request = createMockRequest('https://tenant1.api.app.com/api/users')
+      expect(extractor(request)).toBe('tenant1')
+    })
+
+    it('should extract tenant from full hostname: tenant1.example.com -> tenant1.example.com', () => {
+      // Without baseDomain, return the first subdomain segment
+      const extractor = extractors.subdomain()
+      const request = createMockRequest('https://tenant1.example.com/api/users')
+      expect(extractor(request)).toBe('tenant1')
+    })
+
+    it('should handle www prefix: www.tenant1.app.com -> tenant1', () => {
+      const extractor = extractors.subdomain('app.com')
+      const request = createMockRequest('https://www.tenant1.app.com/api/users')
+      expect(extractor(request)).toBe('tenant1')
+    })
+
+    it('should handle custom domain mapping lookup', async () => {
+      // Custom extractor that does domain mapping lookup
+      const domainMap: Record<string, string> = {
+        'custom.example.org': 'tenant1',
+        'another.example.org': 'tenant2',
+      }
+      const customExtractor: SimpleTenantExtractor = (request: Request) => {
+        const url = new URL(request.url)
+        return domainMap[url.hostname] || null
+      }
+
+      const request1 = createMockRequest('https://custom.example.org/api')
+      const request2 = createMockRequest('https://another.example.org/api')
+
+      expect(customExtractor(request1)).toBe('tenant1')
+      expect(customExtractor(request2)).toBe('tenant2')
+    })
+
+    it('should return null for apex domain: app.com -> null', () => {
+      const extractor = extractors.subdomain('app.com')
+      const request = createMockRequest('https://app.com/api/users')
+      expect(extractor(request)).toBe(null)
+    })
+
+    it('should handle localhost with port: tenant1.localhost:8787 -> tenant1', () => {
+      const extractor = extractors.subdomain('localhost')
+      const request = createMockRequest('http://tenant1.localhost:8787/api/users')
+      expect(extractor(request)).toBe('tenant1')
+    })
+
+    it('should normalize tenant identifiers to lowercase', () => {
+      const extractor = extractors.subdomain('app.com')
+      const request = createMockRequest('https://TenAnt1.app.com/api/users')
+      // The URL parser already lowercases hostnames
+      expect(extractor(request)).toBe('tenant1')
+    })
+
+    it('should strip invalid characters from tenant identifiers', async () => {
+      const mockNamespace = createMockDONamespace()
+      const router = createTenantRouter({
+        doNamespace: mockNamespace,
+        extractTenant: 'path',
+        transformTenant: (id) => id.replace(/[^a-z0-9-]/gi, ''),
+      })
+
+      const request = createMockRequest('https://app.com/tenant@1!/api')
+      const tenantId = await router.getTenantId(request)
+      expect(tenantId).toBe('tenant1')
+    })
+
+    it('should handle IP addresses gracefully: 192.168.1.1 -> null', () => {
+      const extractor = extractors.subdomain()
+      const request = createMockRequest('http://192.168.1.1:8080/api/users')
+      expect(extractor(request)).toBe(null)
+    })
+  })
+
+  describe('path-based extraction', () => {
+    it('should extract tenant from path: /tenant1/api/users -> tenant1', () => {
+      const extractor = extractors.path()
+      const request = createMockRequest('https://app.com/tenant1/api/users')
+      expect(extractor(request)).toBe('tenant1')
+    })
+
+    it('should extract tenant with custom prefix: /orgs/tenant1/api -> tenant1', () => {
+      const extractor = extractors.path('/orgs')
+      const request = createMockRequest('https://app.com/orgs/tenant1/api')
+      expect(extractor(request)).toBe('tenant1')
+    })
+
+    it('should return null for root path: / -> null', () => {
+      const extractor = extractors.path()
+      const request = createMockRequest('https://app.com/')
+      expect(extractor(request)).toBe(null)
+    })
+
+    it('should handle URL-encoded tenant names: /tenant%20name/api -> tenant name', () => {
+      const extractor = extractors.path()
+      const request = createMockRequest('https://app.com/tenant%20name/api')
+      expect(extractor(request)).toBe('tenant name')
+    })
+
+    it('should preserve remaining path after tenant extraction', async () => {
+      const mockNamespace = createMockDONamespace()
+      const router = createTenantRouter({
+        doNamespace: mockNamespace,
+        extractTenant: 'path',
+        stripTenantFromPath: true,
+      })
+
+      const request = createMockRequest('https://app.com/tenant1/api/users')
+      const result = await router.extractTenant(request)
+      expect(result.modifiedPath).toBe('/api/users')
+    })
+
+    it('should handle trailing slashes: /tenant1/ -> tenant1', () => {
+      const extractor = extractors.path()
+      const request = createMockRequest('https://app.com/tenant1/')
+      expect(extractor(request)).toBe('tenant1')
+    })
+  })
+
+  describe('header-based extraction', () => {
+    it('should extract tenant from X-Tenant-ID header', () => {
+      const extractor = extractors.header()
+      const request = createMockRequest('https://app.com/api', {
+        headers: { 'X-Tenant-ID': 'tenant1' },
+      })
+      expect(extractor(request)).toBe('tenant1')
+    })
+
+    it('should support custom header name via config', () => {
+      const extractor = extractors.header('X-Org-ID')
+      const request = createMockRequest('https://app.com/api', {
+        headers: { 'X-Org-ID': 'org123' },
+      })
+      expect(extractor(request)).toBe('org123')
+    })
+
+    it('should return null when header is missing', () => {
+      const extractor = extractors.header()
+      const request = createMockRequest('https://app.com/api')
+      expect(extractor(request)).toBe(null)
+    })
+
+    it('should trim whitespace from header value', () => {
+      const extractor = extractors.header()
+      const request = createMockRequest('https://app.com/api', {
+        headers: { 'X-Tenant-ID': '  tenant1  ' },
+      })
+      expect(extractor(request)).toBe('tenant1')
+    })
+
+    it('should handle empty header value: X-Tenant-ID: "" -> null', () => {
+      const extractor = extractors.header()
+      const request = createMockRequest('https://app.com/api', {
+        headers: { 'X-Tenant-ID': '' },
+      })
+      expect(extractor(request)).toBe(null)
+    })
+
+    it('should be case-insensitive for header name lookup', () => {
+      const extractor = extractors.header('X-Tenant-ID')
+      const request = createMockRequest('https://app.com/api', {
+        headers: { 'x-tenant-id': 'tenant1' },
+      })
+      expect(extractor(request)).toBe('tenant1')
+    })
+  })
+
+  describe('custom extractor', () => {
+    it('should support custom tenant resolver function', async () => {
+      const mockNamespace = createMockDONamespace()
+      const customExtractor: SimpleTenantExtractor = (request: Request) => {
+        const url = new URL(request.url)
+        return url.searchParams.get('tenant')
+      }
+
+      const router = createTenantRouter({
+        doNamespace: mockNamespace,
+        extractTenant: customExtractor,
+      })
+
+      const request = createMockRequest('https://app.com/api?tenant=custom1')
+      const tenantId = await router.getTenantId(request)
+      expect(tenantId).toBe('custom1')
+    })
+
+    it('should pass full request to custom extractor', async () => {
+      const mockNamespace = createMockDONamespace()
+      let receivedRequest: Request | null = null
+
+      const customExtractor: SimpleTenantExtractor = (request: Request) => {
+        receivedRequest = request
+        return 'tenant1'
+      }
+
+      const router = createTenantRouter({
+        doNamespace: mockNamespace,
+        extractTenant: customExtractor,
+      })
+
+      const request = createMockRequest('https://app.com/api', {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+      })
+
+      await router.getTenantId(request)
+      expect(receivedRequest).not.toBe(null)
+      expect(receivedRequest!.method).toBe('POST')
+      expect(receivedRequest!.headers.get('Content-Type')).toBe('application/json')
+    })
+
+    it('should handle async custom extractors', async () => {
+      const mockNamespace = createMockDONamespace()
+      const asyncExtractor: TenantExtractor = async (request: Request) => {
+        await new Promise((resolve) => setTimeout(resolve, 10))
+        const url = new URL(request.url)
+        return {
+          tenantId: url.searchParams.get('tenant'),
+          source: 'custom' as const,
+          originalHostname: url.hostname,
+        }
+      }
+
+      const router = createTenantRouter({
+        doNamespace: mockNamespace,
+        extractTenant: asyncExtractor,
+      })
+
+      const request = createMockRequest('https://app.com/api?tenant=async1')
+      const tenantId = await router.getTenantId(request)
+      expect(tenantId).toBe('async1')
+    })
+
+    it('should allow custom extractor to return metadata', async () => {
+      const mockNamespace = createMockDONamespace()
+      const customExtractor: TenantExtractor = (request: Request) => {
+        const url = new URL(request.url)
+        return {
+          tenantId: url.searchParams.get('tenant'),
+          source: 'custom' as const,
+          originalHostname: url.hostname,
+          metadata: {
+            plan: 'enterprise',
+            region: 'us-east-1',
+          },
+        }
+      }
+
+      const router = createTenantRouter({
+        doNamespace: mockNamespace,
+        extractTenant: customExtractor,
+      })
+
+      const request = createMockRequest('https://app.com/api?tenant=meta1')
+      const result = await router.extractTenant(request)
+      expect(result.metadata).toEqual({ plan: 'enterprise', region: 'us-east-1' })
+    })
+
+    it('should fallback to null when custom extractor throws', async () => {
+      const mockNamespace = createMockDONamespace()
+      const throwingExtractor: SimpleTenantExtractor = () => {
+        throw new Error('Extractor error')
+      }
+
+      const router = createTenantRouter({
+        doNamespace: mockNamespace,
+        extractTenant: throwingExtractor,
+      })
+
+      const request = createMockRequest('https://app.com/api')
+      // The route method should handle the error
+      const response = await router.route(request)
+      expect(response.status).toBe(500)
+    })
+  })
+
+  describe('DO routing', () => {
+    let mockNamespace: DurableObjectNamespace
+    let mockStub: { fetch: ReturnType<typeof vi.fn> }
+
+    beforeEach(() => {
+      mockStub = {
+        fetch: vi.fn().mockResolvedValue(new Response('OK', { status: 200 })),
+      }
+      mockNamespace = {
+        idFromName: vi.fn((name: string) => ({ name, toString: () => `id-${name}` })),
+        idFromString: vi.fn((id: string) => ({ id, toString: () => id })),
+        newUniqueId: vi.fn(() => ({ toString: () => 'unique-id' })),
+        get: vi.fn(() => mockStub),
+        jurisdiction: vi.fn(),
+      } as unknown as DurableObjectNamespace
+    })
+
+    it('should create DO ID from tenant identifier using idFromName', async () => {
+      const router = createTenantRouter({
+        doNamespace: mockNamespace,
+        extractTenant: 'header',
+      })
+
+      const request = createMockRequest('https://app.com/api', {
+        headers: { 'X-Tenant-ID': 'tenant1' },
+      })
+
+      await router.route(request)
+      expect(mockNamespace.idFromName).toHaveBeenCalledWith('tenant1')
+    })
+
+    it('should route request to correct DO stub', async () => {
+      const router = createTenantRouter({
+        doNamespace: mockNamespace,
+        extractTenant: 'header',
+      })
+
+      const request = createMockRequest('https://app.com/api', {
+        headers: { 'X-Tenant-ID': 'tenant1' },
+      })
+
+      await router.route(request)
+      expect(mockNamespace.get).toHaveBeenCalled()
+      expect(mockStub.fetch).toHaveBeenCalled()
+    })
+
+    it('should forward all original headers to DO', async () => {
+      const router = createTenantRouter({
+        doNamespace: mockNamespace,
+        extractTenant: 'header',
+      })
+
+      const request = createMockRequest('https://app.com/api', {
+        headers: {
+          'X-Tenant-ID': 'tenant1',
+          'Content-Type': 'application/json',
+          'Authorization': 'Bearer token123',
+        },
+      })
+
+      await router.route(request)
+
+      const forwardedRequest = mockStub.fetch.mock.calls[0][0] as Request
+      expect(forwardedRequest.headers.get('Content-Type')).toBe('application/json')
+      expect(forwardedRequest.headers.get('Authorization')).toBe('Bearer token123')
+    })
+
+    it('should forward request body to DO', async () => {
+      const router = createTenantRouter({
+        doNamespace: mockNamespace,
+        extractTenant: 'header',
+      })
+
+      const body = JSON.stringify({ data: 'test' })
+      const request = createMockRequest('https://app.com/api', {
+        method: 'POST',
+        headers: {
+          'X-Tenant-ID': 'tenant1',
+          'Content-Type': 'application/json',
+        },
+        body,
+      })
+
+      await router.route(request)
+
+      const forwardedRequest = mockStub.fetch.mock.calls[0][0] as Request
+      const forwardedBody = await forwardedRequest.text()
+      expect(forwardedBody).toBe(body)
+    })
+
+    it('should forward request method to DO', async () => {
+      const router = createTenantRouter({
+        doNamespace: mockNamespace,
+        extractTenant: 'header',
+      })
+
+      const request = createMockRequest('https://app.com/api', {
+        method: 'PUT',
+        headers: { 'X-Tenant-ID': 'tenant1' },
+      })
+
+      await router.route(request)
+
+      const forwardedRequest = mockStub.fetch.mock.calls[0][0] as Request
+      expect(forwardedRequest.method).toBe('PUT')
+    })
+
+    it('should add X-Tenant-ID header to forwarded request', async () => {
+      const router = createTenantRouter({
+        doNamespace: mockNamespace,
+        extractTenant: 'subdomain',
+        baseDomain: 'app.com',
+      })
+
+      const request = createMockRequest('https://tenant1.app.com/api')
+
+      await router.route(request)
+
+      const forwardedRequest = mockStub.fetch.mock.calls[0][0] as Request
+      expect(forwardedRequest.headers.get('X-Tenant-ID')).toBe('tenant1')
+    })
+
+    it('should preserve query string in forwarded request', async () => {
+      const router = createTenantRouter({
+        doNamespace: mockNamespace,
+        extractTenant: 'header',
+      })
+
+      const request = createMockRequest('https://app.com/api?foo=bar&baz=qux', {
+        headers: { 'X-Tenant-ID': 'tenant1' },
+      })
+
+      await router.route(request)
+
+      const forwardedRequest = mockStub.fetch.mock.calls[0][0] as Request
+      const url = new URL(forwardedRequest.url)
+      expect(url.searchParams.get('foo')).toBe('bar')
+      expect(url.searchParams.get('baz')).toBe('qux')
+    })
+
+    it('should handle streaming request bodies', async () => {
+      const router = createTenantRouter({
+        doNamespace: mockNamespace,
+        extractTenant: 'header',
+      })
+
+      // Create a streaming body using ReadableStream
+      const stream = new ReadableStream({
+        start(controller) {
+          controller.enqueue(new TextEncoder().encode('chunk1'))
+          controller.enqueue(new TextEncoder().encode('chunk2'))
+          controller.close()
+        },
+      })
+
+      const request = new Request('https://app.com/api', {
+        method: 'POST',
+        headers: { 'X-Tenant-ID': 'tenant1' },
+        body: stream,
+        // @ts-expect-error duplex is needed for streaming
+        duplex: 'half',
+      })
+
+      await router.route(request)
+      expect(mockStub.fetch).toHaveBeenCalled()
+    })
+
+    it('should return DO response directly to caller', async () => {
+      mockStub.fetch.mockResolvedValue(
+        new Response(JSON.stringify({ result: 'success' }), {
+          status: 201,
+          headers: { 'Content-Type': 'application/json' },
+        })
+      )
+
+      const router = createTenantRouter({
+        doNamespace: mockNamespace,
+        extractTenant: 'header',
+      })
+
+      const request = createMockRequest('https://app.com/api', {
+        headers: { 'X-Tenant-ID': 'tenant1' },
+      })
+
+      const response = await router.route(request)
+      expect(response.status).toBe(201)
+      expect(response.headers.get('Content-Type')).toBe('application/json')
+      const body = await response.json()
+      expect(body).toEqual({ result: 'success' })
+    })
+
+    it('should timeout DO requests after configured duration', async () => {
+      // The timeout is implemented using AbortController
+      // For this test, we simulate the abort by having fetch reject with AbortError
+      const abortError = new Error('Aborted')
+      abortError.name = 'AbortError'
+      mockStub.fetch.mockRejectedValue(abortError)
+
+      const router = createTenantRouter({
+        doNamespace: mockNamespace,
+        extractTenant: 'header',
+        requestTimeoutMs: 50, // Very short timeout for testing
+      })
+
+      const request = createMockRequest('https://app.com/api', {
+        headers: { 'X-Tenant-ID': 'tenant1' },
+      })
+
+      const response = await router.route(request)
+      expect(response.status).toBe(504)
+    })
+  })
+
+  describe('tenant isolation', () => {
+    let mockNamespace: DurableObjectNamespace
+    let stubCalls: Map<string, DurableObjectStub>
+
+    beforeEach(() => {
+      stubCalls = new Map()
+      mockNamespace = {
+        idFromName: vi.fn((name: string) => ({ name, toString: () => `id-${name}` })),
+        idFromString: vi.fn((id: string) => ({ id, toString: () => id })),
+        newUniqueId: vi.fn(() => ({ toString: () => 'unique-id' })),
+        get: vi.fn((id: { name: string }) => {
+          const stub = {
+            fetch: vi.fn().mockResolvedValue(new Response(`Response for ${id.name}`)),
+          }
+          stubCalls.set(id.name, stub as unknown as DurableObjectStub)
+          return stub
+        }),
+        jurisdiction: vi.fn(),
+      } as unknown as DurableObjectNamespace
+    })
+
+    it('should never route tenant1 requests to tenant2 DO', async () => {
+      const router = createTenantRouter({
+        doNamespace: mockNamespace,
+        extractTenant: 'header',
+      })
+
+      const request1 = createMockRequest('https://app.com/api', {
+        headers: { 'X-Tenant-ID': 'tenant1' },
+      })
+      const request2 = createMockRequest('https://app.com/api', {
+        headers: { 'X-Tenant-ID': 'tenant2' },
+      })
+
+      await router.route(request1)
+      await router.route(request2)
+
+      expect(mockNamespace.idFromName).toHaveBeenCalledWith('tenant1')
+      expect(mockNamespace.idFromName).toHaveBeenCalledWith('tenant2')
+      expect(stubCalls.has('tenant1')).toBe(true)
+      expect(stubCalls.has('tenant2')).toBe(true)
+    })
+
+    it('should create separate DO for each unique tenant', async () => {
+      const router = createTenantRouter({
+        doNamespace: mockNamespace,
+        extractTenant: 'header',
+      })
+
+      for (const tenant of ['tenant1', 'tenant2', 'tenant3']) {
+        const request = createMockRequest('https://app.com/api', {
+          headers: { 'X-Tenant-ID': tenant },
+        })
+        await router.route(request)
+      }
+
+      expect(mockNamespace.idFromName).toHaveBeenCalledTimes(3)
+      expect(stubCalls.size).toBe(3)
+    })
+
+    it('should use consistent DO ID for same tenant across requests', async () => {
+      const router = createTenantRouter({
+        doNamespace: mockNamespace,
+        extractTenant: 'header',
+      })
+
+      for (let i = 0; i < 3; i++) {
+        const request = createMockRequest('https://app.com/api', {
+          headers: { 'X-Tenant-ID': 'tenant1' },
+        })
+        await router.route(request)
+      }
+
+      // All calls should use the same tenant ID
+      expect(mockNamespace.idFromName).toHaveBeenCalledWith('tenant1')
+      expect(mockNamespace.idFromName).toHaveBeenCalledTimes(3)
+    })
+
+    it('should not leak tenant information in error responses', async () => {
+      const router = createTenantRouter({
+        doNamespace: mockNamespace,
+        extractTenant: 'header',
+        blockedTenants: ['blocked-tenant'],
+      })
+
+      const request = createMockRequest('https://app.com/api', {
+        headers: { 'X-Tenant-ID': 'blocked-tenant' },
+      })
+
+      const response = await router.route(request)
+      const body = await response.json() as { error: string }
+
+      // Should return generic 404, not mention tenant
+      expect(response.status).toBe(404)
+      expect(body.error).toBe('Not Found')
+      expect(body.error).not.toContain('blocked-tenant')
+    })
+
+    it('should validate tenant ID format before routing', async () => {
+      const router = createTenantRouter({
+        doNamespace: mockNamespace,
+        extractTenant: 'header',
+      })
+
+      const request = createMockRequest('https://app.com/api', {
+        headers: { 'X-Tenant-ID': '../malicious' },
+      })
+
+      const response = await router.route(request)
+      expect(response.status).toBe(400)
+    })
+
+    it('should prevent tenant ID injection via path traversal', async () => {
+      const router = createTenantRouter({
+        doNamespace: mockNamespace,
+        extractTenant: 'header',
+      })
+
+      // Using header-based extraction to test the validation directly
+      // Path-based URLs get normalized by URL parser before we see them
+      const request = createMockRequest('https://app.com/api', {
+        headers: { 'X-Tenant-ID': 'tenant/../../etc/passwd' },
+      })
+
+      const response = await router.route(request)
+      expect(response.status).toBe(400)
+    })
+  })
+
+  describe('configuration', () => {
+    let mockNamespace: DurableObjectNamespace
+
+    beforeEach(() => {
+      mockNamespace = createMockDONamespace()
+    })
+
+    it('should support subdomain-based tenancy mode', async () => {
+      const router = createTenantRouter({
+        doNamespace: mockNamespace,
+        extractTenant: 'subdomain',
+        baseDomain: 'app.com',
+      })
+
+      const request = createMockRequest('https://tenant1.app.com/api')
+      const tenantId = await router.getTenantId(request)
+      expect(tenantId).toBe('tenant1')
+    })
+
+    it('should support path-based tenancy mode: /tenant1/...', async () => {
+      const router = createTenantRouter({
+        doNamespace: mockNamespace,
+        extractTenant: 'path',
+      })
+
+      const request = createMockRequest('https://app.com/tenant1/api')
+      const tenantId = await router.getTenantId(request)
+      expect(tenantId).toBe('tenant1')
+    })
+
+    it('should support header-based tenancy mode: X-Tenant-ID', async () => {
+      const router = createTenantRouter({
+        doNamespace: mockNamespace,
+        extractTenant: 'header',
+      })
+
+      const request = createMockRequest('https://app.com/api', {
+        headers: { 'X-Tenant-ID': 'tenant1' },
+      })
+      const tenantId = await router.getTenantId(request)
+      expect(tenantId).toBe('tenant1')
+    })
+
+    it('should support custom tenant resolver function', async () => {
+      const customResolver: SimpleTenantExtractor = (request: Request) => {
+        const url = new URL(request.url)
+        return url.searchParams.get('org')
+      }
+
+      const router = createTenantRouter({
+        doNamespace: mockNamespace,
+        extractTenant: customResolver,
+      })
+
+      const request = createMockRequest('https://app.com/api?org=myorg')
+      const tenantId = await router.getTenantId(request)
+      expect(tenantId).toBe('myorg')
+    })
+
+    it('should allow combining multiple extraction strategies with priority', async () => {
+      const combinedExtractor = extractors.combined([
+        extractors.header(),
+        extractors.subdomain('app.com'),
+        extractors.path(),
+      ])
+
+      const router = createTenantRouter({
+        doNamespace: mockNamespace,
+        extractTenant: combinedExtractor,
+      })
+
+      // Header takes priority
+      const req1 = createMockRequest('https://tenant2.app.com/tenant3/api', {
+        headers: { 'X-Tenant-ID': 'tenant1' },
+      })
+      expect(await router.getTenantId(req1)).toBe('tenant1')
+
+      // Subdomain is next
+      const req2 = createMockRequest('https://tenant2.app.com/tenant3/api')
+      expect(await router.getTenantId(req2)).toBe('tenant2')
+    })
+
+    it('should support tenant ID transformation function', async () => {
+      const router = createTenantRouter({
+        doNamespace: mockNamespace,
+        extractTenant: 'header',
+        transformTenant: (id) => `prefix_${id.toLowerCase()}`,
+      })
+
+      const request = createMockRequest('https://app.com/api', {
+        headers: { 'X-Tenant-ID': 'MyTenant' },
+      })
+      const tenantId = await router.getTenantId(request)
+      expect(tenantId).toBe('prefix_mytenant')
+    })
+
+    it('should support configurable DO namespace', async () => {
+      const namespace1 = createMockDONamespace()
+      const namespace2 = createMockDONamespace()
+
+      const router1 = createTenantRouter({
+        doNamespace: namespace1,
+        extractTenant: 'header',
+      })
+      const router2 = createTenantRouter({
+        doNamespace: namespace2,
+        extractTenant: 'header',
+      })
+
+      const request = createMockRequest('https://app.com/api', {
+        headers: { 'X-Tenant-ID': 'tenant1' },
+      })
+
+      await router1.route(request)
+      await router2.route(request)
+
+      expect(namespace1.idFromName).toHaveBeenCalledWith('tenant1')
+      expect(namespace2.idFromName).toHaveBeenCalledWith('tenant1')
+    })
+
+    it('should support request timeout configuration', () => {
+      // This is validated by the timeout test in DO routing section
+      const router = createTenantRouter({
+        doNamespace: mockNamespace,
+        extractTenant: 'header',
+        requestTimeoutMs: 5000,
+      })
+
+      expect(router).toBeDefined()
+    })
+
+    it('should support base path stripping for path-based tenancy', async () => {
+      const router = createTenantRouter({
+        doNamespace: mockNamespace,
+        extractTenant: 'path',
+        pathPrefix: '/v1/tenants',
+        stripTenantFromPath: true,
+      })
+
+      const request = createMockRequest('https://app.com/v1/tenants/tenant1/users/123')
+      const result = await router.extractTenant(request)
+
+      expect(result.tenantId).toBe('tenant1')
+      expect(result.modifiedPath).toBe('/users/123')
+    })
+  })
+
+  describe('blocked tenants', () => {
+    let mockNamespace: DurableObjectNamespace
+
+    beforeEach(() => {
+      mockNamespace = createMockDONamespace()
+    })
+
+    it('should return 404 for blocked tenants', async () => {
+      const router = createTenantRouter({
+        doNamespace: mockNamespace,
+        extractTenant: 'header',
+        blockedTenants: ['blocked'],
+      })
+
+      const request = createMockRequest('https://app.com/api', {
+        headers: { 'X-Tenant-ID': 'blocked' },
+      })
+
+      const response = await router.route(request)
+      expect(response.status).toBe(404)
+    })
+
+    it('should check blocked list before routing', async () => {
+      const router = createTenantRouter({
+        doNamespace: mockNamespace,
+        extractTenant: 'header',
+        blockedTenants: ['blocked'],
+      })
+
+      const request = createMockRequest('https://app.com/api', {
+        headers: { 'X-Tenant-ID': 'blocked' },
+      })
+
+      await router.route(request)
+
+      // Should not have routed to DO
+      expect(mockNamespace.get).not.toHaveBeenCalled()
+    })
+
+    it('should support wildcard patterns in blocked list: admin*', async () => {
+      const router = createTenantRouter({
+        doNamespace: mockNamespace,
+        extractTenant: 'header',
+        blockedTenants: ['admin*'],
+      })
+
+      const request1 = createMockRequest('https://app.com/api', {
+        headers: { 'X-Tenant-ID': 'admin' },
+      })
+      const request2 = createMockRequest('https://app.com/api', {
+        headers: { 'X-Tenant-ID': 'admin123' },
+      })
+      const request3 = createMockRequest('https://app.com/api', {
+        headers: { 'X-Tenant-ID': 'administrator' },
+      })
+
+      expect((await router.route(request1)).status).toBe(404)
+      expect((await router.route(request2)).status).toBe(404)
+      expect((await router.route(request3)).status).toBe(404)
+    })
+
+    it('should support blocked tenant callback for dynamic checks', async () => {
+      const blockedCallback = vi.fn().mockResolvedValue(true)
+
+      const router = createTenantRouter({
+        doNamespace: mockNamespace,
+        extractTenant: 'header',
+        isBlocked: blockedCallback,
+      })
+
+      const request = createMockRequest('https://app.com/api', {
+        headers: { 'X-Tenant-ID': 'dynamically-blocked' },
+      })
+
+      const response = await router.route(request)
+      expect(response.status).toBe(404)
+      expect(blockedCallback).toHaveBeenCalledWith('dynamically-blocked', expect.any(Request))
+    })
+
+    it('should log blocked tenant access attempts', async () => {
+      // The implementation uses error formatter for blocked tenants
+      // We can verify through the response that includes correlation ID
+      const router = createTenantRouter({
+        doNamespace: mockNamespace,
+        extractTenant: 'header',
+        blockedTenants: ['blocked'],
+      })
+
+      const request = createMockRequest('https://app.com/api', {
+        headers: { 'X-Tenant-ID': 'blocked' },
+      })
+
+      const response = await router.route(request)
+      expect(response.headers.get('X-Correlation-ID')).toBeTruthy()
+    })
+  })
+
+  describe('error handling', () => {
+    let mockNamespace: DurableObjectNamespace
+    let mockStub: { fetch: ReturnType<typeof vi.fn> }
+
+    beforeEach(() => {
+      mockStub = {
+        fetch: vi.fn().mockResolvedValue(new Response('OK', { status: 200 })),
+      }
+      mockNamespace = {
+        idFromName: vi.fn((name: string) => ({ name, toString: () => `id-${name}` })),
+        idFromString: vi.fn((id: string) => ({ id, toString: () => id })),
+        newUniqueId: vi.fn(() => ({ toString: () => 'unique-id' })),
+        get: vi.fn(() => mockStub),
+        jurisdiction: vi.fn(),
+      } as unknown as DurableObjectNamespace
+    })
+
+    it('should return 400 for missing tenant identifier', async () => {
+      const router = createTenantRouter({
+        doNamespace: mockNamespace,
+        extractTenant: 'header',
+      })
+
+      const request = createMockRequest('https://app.com/api')
+      const response = await router.route(request)
+      expect(response.status).toBe(400)
+    })
+
+    it('should return 400 for invalid tenant identifier format', async () => {
+      const router = createTenantRouter({
+        doNamespace: mockNamespace,
+        extractTenant: 'header',
+      })
+
+      const request = createMockRequest('https://app.com/api', {
+        headers: { 'X-Tenant-ID': 'tenant/../hack' },
+      })
+
+      const response = await router.route(request)
+      expect(response.status).toBe(400)
+    })
+
+    it('should return 404 for blocked tenants', async () => {
+      const router = createTenantRouter({
+        doNamespace: mockNamespace,
+        extractTenant: 'header',
+        blockedTenants: ['blocked'],
+      })
+
+      const request = createMockRequest('https://app.com/api', {
+        headers: { 'X-Tenant-ID': 'blocked' },
+      })
+
+      const response = await router.route(request)
+      expect(response.status).toBe(404)
+    })
+
+    it('should return 502 when DO is unreachable', async () => {
+      mockStub.fetch.mockRejectedValue(new Error('Network error'))
+
+      const router = createTenantRouter({
+        doNamespace: mockNamespace,
+        extractTenant: 'header',
+      })
+
+      const request = createMockRequest('https://app.com/api', {
+        headers: { 'X-Tenant-ID': 'tenant1' },
+      })
+
+      const response = await router.route(request)
+      expect(response.status).toBe(502)
+    })
+
+    it('should return 504 when DO request times out', async () => {
+      // Simulate AbortError which is what happens when timeout triggers
+      const abortError = new Error('Aborted')
+      abortError.name = 'AbortError'
+      mockStub.fetch.mockRejectedValue(abortError)
+
+      const router = createTenantRouter({
+        doNamespace: mockNamespace,
+        extractTenant: 'header',
+        requestTimeoutMs: 50,
+      })
+
+      const request = createMockRequest('https://app.com/api', {
+        headers: { 'X-Tenant-ID': 'tenant1' },
+      })
+
+      const response = await router.route(request)
+      expect(response.status).toBe(504)
+    })
+
+    it('should handle DO errors gracefully with proper status codes', async () => {
+      mockStub.fetch.mockResolvedValue(new Response('Service Error', { status: 500 }))
+
+      const router = createTenantRouter({
+        doNamespace: mockNamespace,
+        extractTenant: 'header',
+      })
+
+      const request = createMockRequest('https://app.com/api', {
+        headers: { 'X-Tenant-ID': 'tenant1' },
+      })
+
+      // DO errors should pass through
+      const response = await router.route(request)
+      expect(response.status).toBe(500)
+    })
+
+    it('should include correlation ID in error responses', async () => {
+      const router = createTenantRouter({
+        doNamespace: mockNamespace,
+        extractTenant: 'header',
+      })
+
+      const request = createMockRequest('https://app.com/api')
+      const response = await router.route(request)
+
+      expect(response.headers.get('X-Correlation-ID')).toBeTruthy()
+    })
+
+    it('should not expose internal error details to client', async () => {
+      mockStub.fetch.mockRejectedValue(new Error('Internal database connection failed'))
+
+      const router = createTenantRouter({
+        doNamespace: mockNamespace,
+        extractTenant: 'header',
+      })
+
+      const request = createMockRequest('https://app.com/api', {
+        headers: { 'X-Tenant-ID': 'tenant1' },
+      })
+
+      const response = await router.route(request)
+      const body = await response.json() as { error: string }
+
+      expect(body.error).not.toContain('database')
+      expect(body.error).toBe('Bad Gateway')
+    })
+
+    it('should support custom error response formatter', async () => {
+      const customFormatter = vi.fn().mockReturnValue(
+        new Response('Custom Error', { status: 418 })
+      )
+
+      const router = createTenantRouter({
+        doNamespace: mockNamespace,
+        extractTenant: 'header',
+        formatError: customFormatter,
+      })
+
+      const request = createMockRequest('https://app.com/api')
+      const response = await router.route(request)
+
+      expect(response.status).toBe(418)
+      expect(customFormatter).toHaveBeenCalled()
+    })
+  })
+
+  describe('observability', () => {
+    let mockNamespace: DurableObjectNamespace
+    let mockStub: { fetch: ReturnType<typeof vi.fn> }
+
+    beforeEach(() => {
+      mockStub = {
+        fetch: vi.fn().mockResolvedValue(new Response('OK', { status: 200 })),
+      }
+      mockNamespace = {
+        idFromName: vi.fn((name: string) => ({ name, toString: () => `id-${name}` })),
+        idFromString: vi.fn((id: string) => ({ id, toString: () => id })),
+        newUniqueId: vi.fn(() => ({ toString: () => 'unique-id' })),
+        get: vi.fn(() => mockStub),
+        jurisdiction: vi.fn(),
+      } as unknown as DurableObjectNamespace
+    })
+
+    it('should emit metrics for each routed request', async () => {
+      const recordedMetrics: RequestMetrics[] = []
+      const metricsCollector: MetricsCollector = {
+        recordRequest: vi.fn((metrics: RequestMetrics) => {
+          recordedMetrics.push(metrics)
+        }),
+        incrementRequestCount: vi.fn(),
+        recordLatency: vi.fn(),
+        recordDoResponseTime: vi.fn(),
+      }
+
+      const router = createTenantRouter({
+        doNamespace: mockNamespace,
+        extractTenant: 'header',
+        metricsCollector,
+      })
+
+      const request = createMockRequest('https://app.com/api/users', {
+        headers: { 'X-Tenant-ID': 'tenant1' },
+      })
+
+      await router.route(request)
+
+      expect(metricsCollector.recordRequest).toHaveBeenCalledTimes(1)
+      expect(recordedMetrics[0].tenantId).toBe('tenant1')
+      expect(recordedMetrics[0].method).toBe('GET')
+      expect(recordedMetrics[0].path).toBe('/api/users')
+      expect(recordedMetrics[0].status).toBe(200)
+    })
+
+    it('should track request latency', async () => {
+      const latencies: Array<{ tenantId: string; latencyMs: number }> = []
+      const metricsCollector: MetricsCollector = {
+        recordRequest: vi.fn(),
+        incrementRequestCount: vi.fn(),
+        recordLatency: vi.fn((tenantId: string, latencyMs: number) => {
+          latencies.push({ tenantId, latencyMs })
+        }),
+        recordDoResponseTime: vi.fn(),
+      }
+
+      const router = createTenantRouter({
+        doNamespace: mockNamespace,
+        extractTenant: 'header',
+        metricsCollector,
+      })
+
+      const request = createMockRequest('https://app.com/api', {
+        headers: { 'X-Tenant-ID': 'tenant1' },
+      })
+
+      await router.route(request)
+
+      expect(metricsCollector.recordLatency).toHaveBeenCalledTimes(1)
+      expect(latencies[0].tenantId).toBe('tenant1')
+      expect(latencies[0].latencyMs).toBeGreaterThanOrEqual(0)
+    })
+
+    it('should count requests per tenant', async () => {
+      const requestCounts: string[] = []
+      const metricsCollector: MetricsCollector = {
+        recordRequest: vi.fn(),
+        incrementRequestCount: vi.fn((tenantId: string) => {
+          requestCounts.push(tenantId)
+        }),
+        recordLatency: vi.fn(),
+        recordDoResponseTime: vi.fn(),
+      }
+
+      const router = createTenantRouter({
+        doNamespace: mockNamespace,
+        extractTenant: 'header',
+        metricsCollector,
+      })
+
+      // Make requests for different tenants
+      const request1 = createMockRequest('https://app.com/api', {
+        headers: { 'X-Tenant-ID': 'tenant1' },
+      })
+      const request2 = createMockRequest('https://app.com/api', {
+        headers: { 'X-Tenant-ID': 'tenant2' },
+      })
+      const request3 = createMockRequest('https://app.com/api', {
+        headers: { 'X-Tenant-ID': 'tenant1' },
+      })
+
+      await router.route(request1)
+      await router.route(request2)
+      await router.route(request3)
+
+      expect(metricsCollector.incrementRequestCount).toHaveBeenCalledTimes(3)
+      expect(requestCounts).toEqual(['tenant1', 'tenant2', 'tenant1'])
+    })
+
+    it('should support custom metrics collector', async () => {
+      const doResponseTimes: Array<{ tenantId: string; responseTimeMs: number }> = []
+      const customCollector: MetricsCollector = {
+        recordRequest: vi.fn(),
+        incrementRequestCount: vi.fn(),
+        recordLatency: vi.fn(),
+        recordDoResponseTime: vi.fn((tenantId: string, responseTimeMs: number) => {
+          doResponseTimes.push({ tenantId, responseTimeMs })
+        }),
+      }
+
+      const router = createTenantRouter({
+        doNamespace: mockNamespace,
+        extractTenant: 'header',
+        metricsCollector: customCollector,
+      })
+
+      const request = createMockRequest('https://app.com/api', {
+        headers: { 'X-Tenant-ID': 'custom-tenant' },
+      })
+
+      await router.route(request)
+
+      expect(customCollector.recordDoResponseTime).toHaveBeenCalledTimes(1)
+      expect(doResponseTimes[0].tenantId).toBe('custom-tenant')
+      expect(doResponseTimes[0].responseTimeMs).toBeGreaterThanOrEqual(0)
+    })
+
+    it('should include trace context in forwarded requests', async () => {
+      const traceContextExtractor: TraceContextExtractor = (request: Request): TraceContext | null => {
+        const traceId = request.headers.get('X-Trace-ID')
+        const spanId = request.headers.get('X-Span-ID')
+        if (traceId && spanId) {
+          return {
+            traceId,
+            spanId,
+            parentSpanId: request.headers.get('X-Parent-Span-ID') || undefined,
+          }
+        }
+        return null
+      }
+
+      const router = createTenantRouter({
+        doNamespace: mockNamespace,
+        extractTenant: 'header',
+        traceContextExtractor,
+        propagateTraceContext: true,
+      })
+
+      const request = createMockRequest('https://app.com/api', {
+        headers: {
+          'X-Tenant-ID': 'tenant1',
+          'X-Trace-ID': 'trace-abc123',
+          'X-Span-ID': 'span-def456',
+          'X-Parent-Span-ID': 'parent-ghi789',
+        },
+      })
+
+      await router.route(request)
+
+      const forwardedRequest = mockStub.fetch.mock.calls[0][0] as Request
+      expect(forwardedRequest.headers.get('X-Trace-ID')).toBe('trace-abc123')
+      expect(forwardedRequest.headers.get('X-Span-ID')).toBe('span-def456')
+      expect(forwardedRequest.headers.get('X-Parent-Span-ID')).toBe('parent-ghi789')
+    })
+
+    it('should log tenant extraction failures', async () => {
+      const logEntries: Array<{ level: string; message: string; data?: Record<string, unknown> }> = []
+      const mockLogger: TenantRouterLogger = {
+        log: vi.fn(),
+        debug: vi.fn((message: string, data?: Record<string, unknown>) => {
+          logEntries.push({ level: 'debug', message, data })
+        }),
+        info: vi.fn(),
+        warn: vi.fn((message: string, data?: Record<string, unknown>) => {
+          logEntries.push({ level: 'warn', message, data })
+        }),
+        error: vi.fn(),
+      }
+
+      const router = createTenantRouter({
+        doNamespace: mockNamespace,
+        extractTenant: 'header',
+        logger: mockLogger,
+      })
+
+      // Request without tenant header - should fail extraction
+      const request = createMockRequest('https://app.com/api')
+
+      await router.route(request)
+
+      expect(mockLogger.warn).toHaveBeenCalled()
+      const failureLog = logEntries.find(e => e.level === 'warn' && e.message.includes('extraction failed'))
+      expect(failureLog).toBeDefined()
+      expect(failureLog?.data?.path).toBe('/api')
+    })
+  })
+
+  describe('caching', () => {
+    it('should cache custom domain to tenant mappings', () => {
+      const cache = createDomainMappingCache({ ttlMs: 300000 }) // 5 minute TTL
+
+      // Set some domain mappings
+      cache.set('custom.example.org', 'tenant1')
+      cache.set('another.example.org', 'tenant2')
+
+      // Verify they are cached
+      const entry1 = cache.get('custom.example.org')
+      const entry2 = cache.get('another.example.org')
+
+      expect(entry1).not.toBeNull()
+      expect(entry1!.tenantId).toBe('tenant1')
+      expect(entry2).not.toBeNull()
+      expect(entry2!.tenantId).toBe('tenant2')
+
+      // Verify cache stats
+      const stats = cache.stats()
+      expect(stats.hits).toBe(2)
+      expect(stats.size).toBe(2)
+    })
+
+    it('should invalidate cache on TTL expiry', async () => {
+      // Use a very short TTL for testing
+      const cache = createDomainMappingCache({ ttlMs: 50 }) // 50ms TTL
+
+      cache.set('expires.example.org', 'tenant1')
+
+      // Verify entry exists immediately
+      expect(cache.get('expires.example.org')).not.toBeNull()
+
+      // Wait for TTL to expire
+      await new Promise((resolve) => setTimeout(resolve, 60))
+
+      // Entry should now be expired and return null
+      const expiredEntry = cache.get('expires.example.org')
+      expect(expiredEntry).toBeNull()
+
+      // Stats should show a miss for the expired entry
+      const stats = cache.stats()
+      expect(stats.misses).toBeGreaterThanOrEqual(1)
+    })
+
+    it('should support cache warming for known tenants', () => {
+      const cache = createDomainMappingCache({ ttlMs: 300000 })
+
+      // Warm cache with known domain mappings
+      cache.warm({
+        'acme.com': 'acme-inc',
+        'bigcorp.io': 'bigcorp',
+        'startup.dev': 'startup-tenant',
+      })
+
+      // Verify all mappings are available
+      expect(cache.size()).toBe(3)
+      expect(cache.get('acme.com')?.tenantId).toBe('acme-inc')
+      expect(cache.get('bigcorp.io')?.tenantId).toBe('bigcorp')
+      expect(cache.get('startup.dev')?.tenantId).toBe('startup-tenant')
+
+      // Verify cache has entries
+      expect(cache.has('acme.com')).toBe(true)
+      expect(cache.has('bigcorp.io')).toBe(true)
+    })
+
+    it('should handle cache miss gracefully', () => {
+      const cache = createDomainMappingCache({ ttlMs: 300000 })
+
+      // Get a non-existent domain
+      const entry = cache.get('nonexistent.example.org')
+      expect(entry).toBeNull()
+
+      // has() should return false
+      expect(cache.has('nonexistent.example.org')).toBe(false)
+
+      // Stats should show a miss
+      const stats = cache.stats()
+      expect(stats.misses).toBeGreaterThanOrEqual(1)
+
+      // Invalidating non-existent entry should not throw
+      cache.invalidate('nonexistent.example.org')
+      expect(cache.stats().invalidations).toBe(0) // No actual invalidation happened
+
+      // invalidateAll should work even on empty cache
+      cache.invalidateAll()
+      expect(cache.size()).toBe(0)
+    })
+  })
+
+  describe('rate limiting', () => {
+    it('should enforce per-tenant rate limits', async () => {
+      const rateLimiter = new TenantRateLimiter({
+        maxRequests: 3,
+        windowMs: 60000,
+      })
+
+      const request = createMockRequest('https://app.com/api')
+
+      // First 3 requests should be allowed
+      const result1 = await rateLimiter.check('tenant1', request)
+      const result2 = await rateLimiter.check('tenant1', request)
+      const result3 = await rateLimiter.check('tenant1', request)
+
+      expect(result1.allowed).toBe(true)
+      expect(result1.currentCount).toBe(1)
+      expect(result2.allowed).toBe(true)
+      expect(result2.currentCount).toBe(2)
+      expect(result3.allowed).toBe(true)
+      expect(result3.currentCount).toBe(3)
+
+      // 4th request should be denied
+      const result4 = await rateLimiter.check('tenant1', request)
+      expect(result4.allowed).toBe(false)
+      expect(result4.currentCount).toBe(3)
+    })
+
+    it('should return 429 when rate limit exceeded', async () => {
+      const rateLimiter = new TenantRateLimiter({
+        maxRequests: 2,
+        windowMs: 60000,
+      })
+
+      const request = createMockRequest('https://app.com/api')
+
+      // Exhaust the rate limit
+      await rateLimiter.check('tenant1', request)
+      await rateLimiter.check('tenant1', request)
+
+      // Third request should be rate limited
+      const result = await rateLimiter.check('tenant1', request)
+      expect(result.allowed).toBe(false)
+      expect(result.maxRequests).toBe(2)
+      expect(result.retryAfterSeconds).toBeGreaterThan(0)
+
+      // Simulate 429 response
+      if (!result.allowed) {
+        const response = new Response(
+          JSON.stringify({ error: 'Rate limit exceeded' }),
+          {
+            status: 429,
+            headers: {
+              'Content-Type': 'application/json',
+              'Retry-After': String(result.retryAfterSeconds),
+            },
+          }
+        )
+        expect(response.status).toBe(429)
+        expect(response.headers.get('Retry-After')).toBeTruthy()
+      }
+    })
+
+    it('should support configurable rate limit windows', async () => {
+      // Create rate limiter with a very short window
+      const rateLimiter = new TenantRateLimiter({
+        maxRequests: 2,
+        windowMs: 100, // 100ms window
+      })
+
+      const request = createMockRequest('https://app.com/api')
+
+      // Exhaust the rate limit
+      await rateLimiter.check('tenant1', request)
+      await rateLimiter.check('tenant1', request)
+
+      // Should be rate limited
+      const resultBefore = await rateLimiter.check('tenant1', request)
+      expect(resultBefore.allowed).toBe(false)
+
+      // Wait for window to expire
+      await new Promise((resolve) => setTimeout(resolve, 150))
+
+      // Should be allowed again after window expires
+      const resultAfter = await rateLimiter.check('tenant1', request)
+      expect(resultAfter.allowed).toBe(true)
+      expect(resultAfter.currentCount).toBe(1)
+    })
+
+    it('should allow rate limit bypass for specific tenants', async () => {
+      const rateLimiter = new TenantRateLimiter({
+        maxRequests: 1,
+        windowMs: 60000,
+        bypassTenants: ['premium-tenant', 'admin-tenant'],
+      })
+
+      const request = createMockRequest('https://app.com/api')
+
+      // Regular tenant should be limited after 1 request
+      const normalResult1 = await rateLimiter.check('regular-tenant', request)
+      const normalResult2 = await rateLimiter.check('regular-tenant', request)
+      expect(normalResult1.allowed).toBe(true)
+      expect(normalResult2.allowed).toBe(false)
+
+      // Bypass tenant should never be limited
+      for (let i = 0; i < 10; i++) {
+        const result = await rateLimiter.check('premium-tenant', request)
+        expect(result.allowed).toBe(true)
+        expect(result.bypassed).toBe(true)
+      }
+
+      // Another bypass tenant
+      for (let i = 0; i < 10; i++) {
+        const result = await rateLimiter.check('admin-tenant', request)
+        expect(result.allowed).toBe(true)
+        expect(result.bypassed).toBe(true)
+      }
+    })
+  })
+
+  describe('preset extractors', () => {
+    describe('extractors.subdomain', () => {
+      it('should extract first subdomain segment', () => {
+        const extractor = extractors.subdomain('example.com')
+        const request = createMockRequest('https://tenant1.example.com/api')
+        expect(extractor(request)).toBe('tenant1')
+      })
+
+      it('should handle two-part TLDs: tenant1.app.co.uk -> tenant1', () => {
+        const extractor = extractors.subdomain('app.co.uk')
+        const request = createMockRequest('https://tenant1.app.co.uk/api')
+        expect(extractor(request)).toBe('tenant1')
+      })
+
+      it('should return null for apex domains', () => {
+        const extractor = extractors.subdomain('example.com')
+        const request = createMockRequest('https://example.com/api')
+        expect(extractor(request)).toBe(null)
+      })
+    })
+
+    describe('extractors.path', () => {
+      it('should extract first path segment by default', () => {
+        const extractor = extractors.path()
+        const request = createMockRequest('https://app.com/tenant1/api/users')
+        expect(extractor(request)).toBe('tenant1')
+      })
+
+      it('should support configurable path prefix', () => {
+        const extractor = extractors.path('/v1/orgs')
+        const request = createMockRequest('https://app.com/v1/orgs/myorg/users')
+        expect(extractor(request)).toBe('myorg')
+      })
+
+      it('should decode URL-encoded segments', () => {
+        const extractor = extractors.path()
+        const request = createMockRequest('https://app.com/my%20org/users')
+        expect(extractor(request)).toBe('my org')
+      })
+    })
+
+    describe('extractors.header', () => {
+      it('should return extractor function for given header name', () => {
+        const extractor = extractors.header('X-Custom-Tenant')
+        const request = createMockRequest('https://app.com/api', {
+          headers: { 'X-Custom-Tenant': 'custom-tenant' },
+        })
+        expect(extractor(request)).toBe('custom-tenant')
+      })
+
+      it('should use X-Tenant-ID as default header name', () => {
+        const extractor = extractors.header()
+        const request = createMockRequest('https://app.com/api', {
+          headers: { 'X-Tenant-ID': 'default-header' },
+        })
+        expect(extractor(request)).toBe('default-header')
+      })
+    })
+
+    describe('extractors.combined', () => {
+      it('should try extractors in order until one succeeds', async () => {
+        const combined = extractors.combined([
+          extractors.header('X-Missing'),
+          extractors.header('X-Tenant-ID'),
+          extractors.path(),
+        ])
+
+        const request = createMockRequest('https://app.com/path-tenant/api', {
+          headers: { 'X-Tenant-ID': 'header-tenant' },
+        })
+
+        expect(await combined(request)).toBe('header-tenant')
+      })
+
+      it('should return null if all extractors fail', async () => {
+        const combined = extractors.combined([
+          extractors.header('X-Missing'),
+          extractors.subdomain('example.com'),
+        ])
+
+        const request = createMockRequest('https://example.com/')
+        expect(await combined(request)).toBe(null)
+      })
+    })
+  })
+})
+
+describe('TenantExtractionResult', () => {
+  let mockNamespace: DurableObjectNamespace
+
+  beforeEach(() => {
+    mockNamespace = createMockDONamespace()
+  })
+
+  it('should include tenantId when extraction succeeds', async () => {
+    const router = createTenantRouter({
+      doNamespace: mockNamespace,
+      extractTenant: 'header',
+    })
+
+    const request = createMockRequest('https://app.com/api', {
+      headers: { 'X-Tenant-ID': 'tenant1' },
+    })
+
+    const result = await router.extractTenant(request)
+    expect(result.tenantId).toBe('tenant1')
+  })
+
+  it('should include extraction source (subdomain, path, header, custom)', async () => {
+    const headerRouter = createTenantRouter({
+      doNamespace: mockNamespace,
+      extractTenant: 'header',
+    })
+    const pathRouter = createTenantRouter({
+      doNamespace: mockNamespace,
+      extractTenant: 'path',
+    })
+    const subdomainRouter = createTenantRouter({
+      doNamespace: mockNamespace,
+      extractTenant: 'subdomain',
+      baseDomain: 'app.com',
+    })
+
+    const headerRequest = createMockRequest('https://app.com/api', {
+      headers: { 'X-Tenant-ID': 'tenant1' },
+    })
+    const pathRequest = createMockRequest('https://app.com/tenant1/api')
+    const subdomainRequest = createMockRequest('https://tenant1.app.com/api')
+
+    expect((await headerRouter.extractTenant(headerRequest)).source).toBe('header')
+    expect((await pathRouter.extractTenant(pathRequest)).source).toBe('path')
+    expect((await subdomainRouter.extractTenant(subdomainRequest)).source).toBe('subdomain')
+  })
+
+  it('should include original hostname', async () => {
+    const router = createTenantRouter({
+      doNamespace: mockNamespace,
+      extractTenant: 'header',
+    })
+
+    const request = createMockRequest('https://my-app.example.com/api', {
+      headers: { 'X-Tenant-ID': 'tenant1' },
+    })
+
+    const result = await router.extractTenant(request)
+    expect(result.originalHostname).toBe('my-app.example.com')
+  })
+
+  it('should include modified path for path-based extraction', async () => {
+    const router = createTenantRouter({
+      doNamespace: mockNamespace,
+      extractTenant: 'path',
+      stripTenantFromPath: true,
+    })
+
+    const request = createMockRequest('https://app.com/tenant1/api/users/123')
+
+    const result = await router.extractTenant(request)
+    expect(result.modifiedPath).toBe('/api/users/123')
+  })
+
+  it('should include metadata from custom extractors', async () => {
+    const customExtractor: TenantExtractor = (request: Request) => {
+      const url = new URL(request.url)
+      return {
+        tenantId: 'tenant1',
+        source: 'custom' as const,
+        originalHostname: url.hostname,
+        metadata: {
+          customField: 'customValue',
+          tier: 'premium',
+        },
+      }
+    }
+
+    const router = createTenantRouter({
+      doNamespace: mockNamespace,
+      extractTenant: customExtractor,
+    })
+
+    const request = createMockRequest('https://app.com/api')
+    const result = await router.extractTenant(request)
+
+    expect(result.metadata).toEqual({
+      customField: 'customValue',
+      tier: 'premium',
+    })
+  })
+})
+
+describe('TenantRoutingResult', () => {
+  let mockNamespace: DurableObjectNamespace
+  let mockStub: { fetch: ReturnType<typeof vi.fn> }
+
+  beforeEach(() => {
+    mockStub = {
+      fetch: vi.fn().mockResolvedValue(new Response('DO Response', { status: 200 })),
+    }
+    mockNamespace = {
+      idFromName: vi.fn((name: string) => ({ name, toString: () => `id-${name}` })),
+      idFromString: vi.fn((id: string) => ({ id, toString: () => id })),
+      newUniqueId: vi.fn(() => ({ toString: () => 'unique-id' })),
+      get: vi.fn(() => mockStub),
+      jurisdiction: vi.fn(),
+    } as unknown as DurableObjectNamespace
+  })
+
+  it('should include response from DO', async () => {
+    mockStub.fetch.mockResolvedValue(
+      new Response(JSON.stringify({ data: 'test-data' }), {
+        status: 200,
+        headers: { 'Content-Type': 'application/json' },
+      })
+    )
+
+    const router = createTenantRouter({
+      doNamespace: mockNamespace,
+      extractTenant: 'header',
+    })
+
+    const request = createMockRequest('https://app.com/api', {
+      headers: { 'X-Tenant-ID': 'tenant1' },
+    })
+
+    const result = await router.routeWithResult(request)
+
+    expect(result.response).toBeInstanceOf(Response)
+    expect(result.response.status).toBe(200)
+    const body = await result.response.json()
+    expect(body).toEqual({ data: 'test-data' })
+  })
+
+  it('should include routing metadata', async () => {
+    const router = createTenantRouter({
+      doNamespace: mockNamespace,
+      extractTenant: 'header',
+    })
+
+    const request = createMockRequest('https://app.com/api', {
+      headers: { 'X-Tenant-ID': 'tenant1' },
+    })
+
+    const result = await router.routeWithResult(request)
+
+    expect(result.routingMetadata).toBeDefined()
+    expect(result.routingMetadata.extractorType).toBe('header')
+    expect(result.routingMetadata.doId).toBe('id-tenant1')
+  })
+
+  it('should include timing information', async () => {
+    const router = createTenantRouter({
+      doNamespace: mockNamespace,
+      extractTenant: 'header',
+    })
+
+    const request = createMockRequest('https://app.com/api', {
+      headers: { 'X-Tenant-ID': 'tenant1' },
+    })
+
+    const beforeTime = Date.now()
+    const result = await router.routeWithResult(request)
+    const afterTime = Date.now()
+
+    expect(result.timing).toBeDefined()
+    expect(result.timing.extractionTimeMs).toBeGreaterThanOrEqual(0)
+    expect(result.timing.routingTimeMs).toBeGreaterThanOrEqual(0)
+    expect(result.timing.totalTimeMs).toBeGreaterThanOrEqual(0)
+    expect(result.timing.startTimestamp).toBeGreaterThanOrEqual(beforeTime)
+    expect(result.timing.startTimestamp).toBeLessThanOrEqual(afterTime)
+  })
+
+  it('should include tenant context', async () => {
+    const customExtractor: TenantExtractor = (request: Request) => {
+      const url = new URL(request.url)
+      return {
+        tenantId: url.searchParams.get('tenant'),
+        source: 'custom' as const,
+        originalHostname: url.hostname,
+        metadata: {
+          plan: 'enterprise',
+          region: 'us-west-2',
+        },
+      }
+    }
+
+    const router = createTenantRouter({
+      doNamespace: mockNamespace,
+      extractTenant: customExtractor,
+    })
+
+    const request = createMockRequest('https://app.com/api?tenant=tenant1')
+
+    const result = await router.routeWithResult(request)
+
+    expect(result.tenantContext).toBeDefined()
+    expect(result.tenantContext.tenantId).toBe('tenant1')
+    expect(result.tenantContext.source).toBe('custom')
+    expect(result.tenantContext.metadata).toEqual({
+      plan: 'enterprise',
+      region: 'us-west-2',
+    })
+  })
+})
+
+describe('createTenantRouter', () => {
+  let mockNamespace: DurableObjectNamespace
+
+  beforeEach(() => {
+    mockNamespace = createMockDONamespace()
+  })
+
+  it('should create router with subdomain extraction when extractTenant is "subdomain"', async () => {
+    const router = createTenantRouter({
+      doNamespace: mockNamespace,
+      extractTenant: 'subdomain',
+      baseDomain: 'myapp.com',
+    })
+
+    const request = createMockRequest('https://acme.myapp.com/api')
+    const tenantId = await router.getTenantId(request)
+    expect(tenantId).toBe('acme')
+  })
+
+  it('should create router with path extraction when extractTenant is "path"', async () => {
+    const router = createTenantRouter({
+      doNamespace: mockNamespace,
+      extractTenant: 'path',
+    })
+
+    const request = createMockRequest('https://app.com/acme/api')
+    const tenantId = await router.getTenantId(request)
+    expect(tenantId).toBe('acme')
+  })
+
+  it('should create router with header extraction when extractTenant is "header"', async () => {
+    const router = createTenantRouter({
+      doNamespace: mockNamespace,
+      extractTenant: 'header',
+    })
+
+    const request = createMockRequest('https://app.com/api', {
+      headers: { 'X-Tenant-ID': 'acme' },
+    })
+    const tenantId = await router.getTenantId(request)
+    expect(tenantId).toBe('acme')
+  })
+
+  it('should create router with custom function when extractTenant is a function', async () => {
+    const customFn: SimpleTenantExtractor = (req) => {
+      const url = new URL(req.url)
+      return url.searchParams.get('t')
+    }
+
+    const router = createTenantRouter({
+      doNamespace: mockNamespace,
+      extractTenant: customFn,
+    })
+
+    const request = createMockRequest('https://app.com/api?t=custom-tenant')
+    const tenantId = await router.getTenantId(request)
+    expect(tenantId).toBe('custom-tenant')
+  })
+
+  it('should throw error for invalid extractTenant value', () => {
+    expect(() => {
+      createTenantRouter({
+        doNamespace: mockNamespace,
+        // @ts-expect-error - intentionally passing invalid value
+        extractTenant: 'invalid',
+      })
+    }).toThrow('Invalid extractTenant value: invalid')
+  })
+
+  it('should apply default configuration values', async () => {
+    // Default header name should be X-Tenant-ID
+    const router = createTenantRouter({
+      doNamespace: mockNamespace,
+      extractTenant: 'header',
+    })
+
+    const request = createMockRequest('https://app.com/api', {
+      headers: { 'X-Tenant-ID': 'default-tenant' },
+    })
+
+    const tenantId = await router.getTenantId(request)
+    expect(tenantId).toBe('default-tenant')
+  })
+})
+
+describe('nested sub-config support', () => {
+  let mockNamespace: DurableObjectNamespace
+  let mockStub: { fetch: ReturnType<typeof vi.fn> }
+
+  beforeEach(() => {
+    mockStub = {
+      fetch: vi.fn().mockResolvedValue(new Response('OK', { status: 200 })),
+    }
+    mockNamespace = {
+      idFromName: vi.fn((name: string) => ({ name, toString: () => `id-${name}` })),
+      idFromString: vi.fn((id: string) => ({ id, toString: () => id })),
+      newUniqueId: vi.fn(() => ({ toString: () => 'unique-id' })),
+      get: vi.fn(() => mockStub),
+      jurisdiction: vi.fn(),
+    } as unknown as DurableObjectNamespace
+  })
+
+  describe('observability config', () => {
+    it('should use nested observability.metricsCollector', async () => {
+      const recordedMetrics: RequestMetrics[] = []
+      const metricsCollector: MetricsCollector = {
+        recordRequest: vi.fn((metrics: RequestMetrics) => {
+          recordedMetrics.push(metrics)
+        }),
+        incrementRequestCount: vi.fn(),
+        recordLatency: vi.fn(),
+        recordDoResponseTime: vi.fn(),
+      }
+
+      const router = createTenantRouter({
+        doNamespace: mockNamespace,
+        extractTenant: 'header',
+        observability: {
+          metricsCollector,
+        },
+      })
+
+      const request = createMockRequest('https://app.com/api/users', {
+        headers: { 'X-Tenant-ID': 'tenant1' },
+      })
+
+      await router.route(request)
+
+      expect(metricsCollector.recordRequest).toHaveBeenCalledTimes(1)
+      expect(recordedMetrics[0].tenantId).toBe('tenant1')
+    })
+
+    it('should use nested observability.logger', async () => {
+      const logEntries: Array<{ level: string; message: string; data?: Record<string, unknown> }> = []
+      const mockLogger: TenantRouterLogger = {
+        log: vi.fn(),
+        debug: vi.fn((message: string, data?: Record<string, unknown>) => {
+          logEntries.push({ level: 'debug', message, data })
+        }),
+        info: vi.fn(),
+        warn: vi.fn((message: string, data?: Record<string, unknown>) => {
+          logEntries.push({ level: 'warn', message, data })
+        }),
+        error: vi.fn(),
+      }
+
+      const router = createTenantRouter({
+        doNamespace: mockNamespace,
+        extractTenant: 'header',
+        observability: {
+          logger: mockLogger,
+        },
+      })
+
+      const request = createMockRequest('https://app.com/api')
+      await router.route(request)
+
+      expect(mockLogger.warn).toHaveBeenCalled()
+    })
+
+    it('should use nested observability.traceContextExtractor and propagateTraceContext', async () => {
+      const traceContextExtractor: TraceContextExtractor = (request: Request): TraceContext | null => {
+        const traceId = request.headers.get('X-Trace-ID')
+        const spanId = request.headers.get('X-Span-ID')
+        if (traceId && spanId) {
+          return { traceId, spanId }
+        }
+        return null
+      }
+
+      const router = createTenantRouter({
+        doNamespace: mockNamespace,
+        extractTenant: 'header',
+        observability: {
+          traceContextExtractor,
+          propagateTraceContext: true,
+        },
+      })
+
+      const request = createMockRequest('https://app.com/api', {
+        headers: {
+          'X-Tenant-ID': 'tenant1',
+          'X-Trace-ID': 'nested-trace-123',
+          'X-Span-ID': 'nested-span-456',
+        },
+      })
+
+      await router.route(request)
+
+      const forwardedRequest = mockStub.fetch.mock.calls[0][0] as Request
+      expect(forwardedRequest.headers.get('X-Trace-ID')).toBe('nested-trace-123')
+      expect(forwardedRequest.headers.get('X-Span-ID')).toBe('nested-span-456')
+    })
+
+    it('should disable trace propagation when observability.propagateTraceContext is false', async () => {
+      const traceContextExtractor: TraceContextExtractor = (request: Request): TraceContext | null => {
+        const traceId = request.headers.get('X-Trace-ID')
+        const spanId = request.headers.get('X-Span-ID')
+        if (traceId && spanId) {
+          return { traceId, spanId }
+        }
+        return null
+      }
+
+      const router = createTenantRouter({
+        doNamespace: mockNamespace,
+        extractTenant: 'header',
+        observability: {
+          traceContextExtractor,
+          propagateTraceContext: false,
+        },
+      })
+
+      const request = createMockRequest('https://app.com/api', {
+        headers: {
+          'X-Tenant-ID': 'tenant1',
+          'X-Trace-ID': 'trace-abc',
+          'X-Span-ID': 'span-def',
+        },
+      })
+
+      await router.route(request)
+
+      const forwardedRequest = mockStub.fetch.mock.calls[0][0] as Request
+      // Trace headers should NOT be propagated
+      expect(forwardedRequest.headers.get('X-Trace-ID')).toBeNull()
+      expect(forwardedRequest.headers.get('X-Span-ID')).toBeNull()
+    })
+  })
+
+  describe('backward compatibility with legacy flat config', () => {
+    it('should still support legacy flat metricsCollector option', async () => {
+      const recordedMetrics: RequestMetrics[] = []
+      const metricsCollector: MetricsCollector = {
+        recordRequest: vi.fn((metrics: RequestMetrics) => {
+          recordedMetrics.push(metrics)
+        }),
+        incrementRequestCount: vi.fn(),
+        recordLatency: vi.fn(),
+        recordDoResponseTime: vi.fn(),
+      }
+
+      const router = createTenantRouter({
+        doNamespace: mockNamespace,
+        extractTenant: 'header',
+        metricsCollector, // legacy flat option
+      })
+
+      const request = createMockRequest('https://app.com/api', {
+        headers: { 'X-Tenant-ID': 'tenant1' },
+      })
+
+      await router.route(request)
+
+      expect(metricsCollector.recordRequest).toHaveBeenCalledTimes(1)
+    })
+
+    it('should still support legacy flat logger option', async () => {
+      const mockLogger: TenantRouterLogger = {
+        log: vi.fn(),
+        debug: vi.fn(),
+        info: vi.fn(),
+        warn: vi.fn(),
+        error: vi.fn(),
+      }
+
+      const router = createTenantRouter({
+        doNamespace: mockNamespace,
+        extractTenant: 'header',
+        logger: mockLogger, // legacy flat option
+      })
+
+      const request = createMockRequest('https://app.com/api')
+      await router.route(request)
+
+      expect(mockLogger.warn).toHaveBeenCalled()
+    })
+
+    it('should still support legacy flat traceContextExtractor option', async () => {
+      const traceContextExtractor: TraceContextExtractor = (request: Request): TraceContext | null => {
+        const traceId = request.headers.get('X-Trace-ID')
+        const spanId = request.headers.get('X-Span-ID')
+        if (traceId && spanId) {
+          return { traceId, spanId }
+        }
+        return null
+      }
+
+      const router = createTenantRouter({
+        doNamespace: mockNamespace,
+        extractTenant: 'header',
+        traceContextExtractor, // legacy flat option
+        propagateTraceContext: true, // legacy flat option
+      })
+
+      const request = createMockRequest('https://app.com/api', {
+        headers: {
+          'X-Tenant-ID': 'tenant1',
+          'X-Trace-ID': 'legacy-trace-123',
+          'X-Span-ID': 'legacy-span-456',
+        },
+      })
+
+      await router.route(request)
+
+      const forwardedRequest = mockStub.fetch.mock.calls[0][0] as Request
+      expect(forwardedRequest.headers.get('X-Trace-ID')).toBe('legacy-trace-123')
+    })
+
+    it('should prefer nested config over legacy flat config', async () => {
+      const nestedMetrics: RequestMetrics[] = []
+      const legacyMetrics: RequestMetrics[] = []
+
+      const nestedCollector: MetricsCollector = {
+        recordRequest: vi.fn((metrics: RequestMetrics) => {
+          nestedMetrics.push(metrics)
+        }),
+        incrementRequestCount: vi.fn(),
+        recordLatency: vi.fn(),
+        recordDoResponseTime: vi.fn(),
+      }
+
+      const legacyCollector: MetricsCollector = {
+        recordRequest: vi.fn((metrics: RequestMetrics) => {
+          legacyMetrics.push(metrics)
+        }),
+        incrementRequestCount: vi.fn(),
+        recordLatency: vi.fn(),
+        recordDoResponseTime: vi.fn(),
+      }
+
+      const router = createTenantRouter({
+        doNamespace: mockNamespace,
+        extractTenant: 'header',
+        observability: {
+          metricsCollector: nestedCollector, // this should take precedence
+        },
+        metricsCollector: legacyCollector, // this should be ignored
+      })
+
+      const request = createMockRequest('https://app.com/api', {
+        headers: { 'X-Tenant-ID': 'tenant1' },
+      })
+
+      await router.route(request)
+
+      // Nested config should be used
+      expect(nestedCollector.recordRequest).toHaveBeenCalledTimes(1)
+      expect(nestedMetrics.length).toBe(1)
+
+      // Legacy config should NOT be used
+      expect(legacyCollector.recordRequest).not.toHaveBeenCalled()
+      expect(legacyMetrics.length).toBe(0)
+    })
+  })
+
+  describe('blockedTenantCallback config', () => {
+    it('should use blockedTenantCallback for dynamic blocking', async () => {
+      const blockedCallback = vi.fn().mockResolvedValue(true)
+
+      const router = createTenantRouter({
+        doNamespace: mockNamespace,
+        extractTenant: 'header',
+        blockedTenantCallback: blockedCallback,
+      })
+
+      const request = createMockRequest('https://app.com/api', {
+        headers: { 'X-Tenant-ID': 'dynamically-blocked' },
+      })
+
+      const response = await router.route(request)
+      expect(response.status).toBe(404)
+      expect(blockedCallback).toHaveBeenCalledWith('dynamically-blocked', expect.any(Request))
+    })
+
+    it('should prefer blockedTenantCallback over legacy isBlocked', async () => {
+      const newCallback = vi.fn().mockResolvedValue(false)
+      const legacyCallback = vi.fn().mockResolvedValue(true)
+
+      const router = createTenantRouter({
+        doNamespace: mockNamespace,
+        extractTenant: 'header',
+        blockedTenantCallback: newCallback, // should be used
+        isBlocked: legacyCallback, // should be ignored
+      })
+
+      const request = createMockRequest('https://app.com/api', {
+        headers: { 'X-Tenant-ID': 'test-tenant' },
+      })
+
+      await router.route(request)
+
+      // New callback should be used
+      expect(newCallback).toHaveBeenCalled()
+      // Legacy callback should NOT be used
+      expect(legacyCallback).not.toHaveBeenCalled()
+    })
+  })
+
+  describe('errorResponseFormatter config', () => {
+    it('should use errorResponseFormatter for custom error responses', async () => {
+      const customFormatter = vi.fn().mockReturnValue(
+        new Response('Custom Error', { status: 418 })
+      )
+
+      const router = createTenantRouter({
+        doNamespace: mockNamespace,
+        extractTenant: 'header',
+        errorResponseFormatter: customFormatter,
+      })
+
+      const request = createMockRequest('https://app.com/api')
+      const response = await router.route(request)
+
+      expect(response.status).toBe(418)
+      expect(customFormatter).toHaveBeenCalled()
+    })
+
+    it('should prefer errorResponseFormatter over legacy formatError', async () => {
+      const newFormatter = vi.fn().mockReturnValue(
+        new Response('New Formatter', { status: 418 })
+      )
+      const legacyFormatter = vi.fn().mockReturnValue(
+        new Response('Legacy Formatter', { status: 500 })
+      )
+
+      const router = createTenantRouter({
+        doNamespace: mockNamespace,
+        extractTenant: 'header',
+        errorResponseFormatter: newFormatter, // should be used
+        formatError: legacyFormatter, // should be ignored
+      })
+
+      const request = createMockRequest('https://app.com/api')
+      const response = await router.route(request)
+
+      expect(response.status).toBe(418)
+      expect(newFormatter).toHaveBeenCalled()
+      expect(legacyFormatter).not.toHaveBeenCalled()
+    })
+  })
+})
+
+describe('integration scenarios', () => {
+  let mockNamespace: DurableObjectNamespace
+  let mockStub: { fetch: ReturnType<typeof vi.fn> }
+
+  beforeEach(() => {
+    mockStub = {
+      fetch: vi.fn().mockResolvedValue(new Response('OK', { status: 200 })),
+    }
+    mockNamespace = {
+      idFromName: vi.fn((name: string) => ({ name, toString: () => `id-${name}` })),
+      idFromString: vi.fn((id: string) => ({ id, toString: () => id })),
+      newUniqueId: vi.fn(() => ({ toString: () => 'unique-id' })),
+      get: vi.fn(() => mockStub),
+      jurisdiction: vi.fn(),
+    } as unknown as DurableObjectNamespace
+  })
+
+  describe('SaaS multi-tenant application', () => {
+    it('should route customer1.myapp.com to customer1 DO', async () => {
+      const router = createTenantRouter({
+        doNamespace: mockNamespace,
+        extractTenant: 'subdomain',
+        baseDomain: 'myapp.com',
+      })
+
+      const request = createMockRequest('https://customer1.myapp.com/dashboard')
+      await router.route(request)
+
+      expect(mockNamespace.idFromName).toHaveBeenCalledWith('customer1')
+    })
+
+    it('should route customer2.myapp.com to customer2 DO', async () => {
+      const router = createTenantRouter({
+        doNamespace: mockNamespace,
+        extractTenant: 'subdomain',
+        baseDomain: 'myapp.com',
+      })
+
+      const request = createMockRequest('https://customer2.myapp.com/dashboard')
+      await router.route(request)
+
+      expect(mockNamespace.idFromName).toHaveBeenCalledWith('customer2')
+    })
+
+    it('should route custom domain mappings correctly', async () => {
+      const domainToTenant: Record<string, string> = {
+        'acme.com': 'acme-inc',
+        'bigcorp.io': 'bigcorp',
+      }
+
+      const customExtractor: SimpleTenantExtractor = (request: Request) => {
+        const url = new URL(request.url)
+        return domainToTenant[url.hostname] || null
+      }
+
+      const router = createTenantRouter({
+        doNamespace: mockNamespace,
+        extractTenant: customExtractor,
+      })
+
+      const request1 = createMockRequest('https://acme.com/dashboard')
+      const request2 = createMockRequest('https://bigcorp.io/dashboard')
+
+      await router.route(request1)
+      expect(mockNamespace.idFromName).toHaveBeenCalledWith('acme-inc')
+
+      await router.route(request2)
+      expect(mockNamespace.idFromName).toHaveBeenCalledWith('bigcorp')
+    })
+  })
+
+  describe('API gateway with path-based routing', () => {
+    it('should route /v1/tenants/acme/users to acme DO', async () => {
+      const router = createTenantRouter({
+        doNamespace: mockNamespace,
+        extractTenant: 'path',
+        pathPrefix: '/v1/tenants',
+      })
+
+      const request = createMockRequest('https://api.example.com/v1/tenants/acme/users')
+      await router.route(request)
+
+      expect(mockNamespace.idFromName).toHaveBeenCalledWith('acme')
+    })
+
+    it('should strip tenant prefix from forwarded path', async () => {
+      const router = createTenantRouter({
+        doNamespace: mockNamespace,
+        extractTenant: 'path',
+        pathPrefix: '/v1/tenants',
+        stripTenantFromPath: true,
+      })
+
+      const request = createMockRequest('https://api.example.com/v1/tenants/acme/users/123')
+      await router.route(request)
+
+      const forwardedRequest = mockStub.fetch.mock.calls[0][0] as Request
+      const url = new URL(forwardedRequest.url)
+      expect(url.pathname).toBe('/users/123')
+    })
+
+    it('should preserve API versioning in path', async () => {
+      // Using header-based extraction so path is not modified
+      const router = createTenantRouter({
+        doNamespace: mockNamespace,
+        extractTenant: 'header',
+      })
+
+      const request = createMockRequest('https://api.example.com/v2/users/123', {
+        headers: { 'X-Tenant-ID': 'acme' },
+      })
+
+      await router.route(request)
+
+      const forwardedRequest = mockStub.fetch.mock.calls[0][0] as Request
+      const url = new URL(forwardedRequest.url)
+      expect(url.pathname).toBe('/v2/users/123')
+    })
+  })
+
+  describe('internal service with header-based routing', () => {
+    it('should route based on X-Tenant-ID from upstream proxy', async () => {
+      const router = createTenantRouter({
+        doNamespace: mockNamespace,
+        extractTenant: 'header',
+        headerName: 'X-Tenant-ID',
+      })
+
+      const request = createMockRequest('https://internal-service/api/data', {
+        headers: {
+          'X-Tenant-ID': 'internal-tenant',
+          'X-Forwarded-For': '10.0.0.1',
+        },
+      })
+
+      await router.route(request)
+      expect(mockNamespace.idFromName).toHaveBeenCalledWith('internal-tenant')
+    })
+
+    it('should reject requests without tenant header', async () => {
+      const router = createTenantRouter({
+        doNamespace: mockNamespace,
+        extractTenant: 'header',
+      })
+
+      const request = createMockRequest('https://internal-service/api/data')
+      const response = await router.route(request)
+
+      expect(response.status).toBe(400)
+    })
+  })
+
+  describe('tenant ID boundary cases', () => {
+    it('should handle very long tenant ID at 128 character boundary', async () => {
+      const router = createTenantRouter({
+        doNamespace: mockNamespace,
+        extractTenant: 'header',
+      })
+
+      // Exactly 128 characters - typical maximum for identifiers
+      const tenantId128 = 'a'.repeat(128)
+      const request = createMockRequest('https://app.com/api', {
+        headers: { 'X-Tenant-ID': tenantId128 },
+      })
+
+      await router.route(request)
+      expect(mockNamespace.idFromName).toHaveBeenCalledWith(tenantId128)
+    })
+
+    it('should handle tenant ID just under 128 character boundary', async () => {
+      const router = createTenantRouter({
+        doNamespace: mockNamespace,
+        extractTenant: 'header',
+      })
+
+      const tenantId127 = 'b'.repeat(127)
+      const request = createMockRequest('https://app.com/api', {
+        headers: { 'X-Tenant-ID': tenantId127 },
+      })
+
+      await router.route(request)
+      expect(mockNamespace.idFromName).toHaveBeenCalledWith(tenantId127)
+    })
+
+    it('should reject tenant ID exceeding 128 character boundary', async () => {
+      const router = createTenantRouter({
+        doNamespace: mockNamespace,
+        extractTenant: 'header',
+        maxTenantIdLength: 128, // Explicit limit
+      })
+
+      const tenantId129 = 'c'.repeat(129)
+      const request = createMockRequest('https://app.com/api', {
+        headers: { 'X-Tenant-ID': tenantId129 },
+      })
+
+      const response = await router.route(request)
+      expect(response.status).toBe(400)
+    })
+
+    it('should handle empty tenant ID as missing tenant', async () => {
+      const router = createTenantRouter({
+        doNamespace: mockNamespace,
+        extractTenant: 'header',
+      })
+
+      const request = createMockRequest('https://app.com/api', {
+        headers: { 'X-Tenant-ID': '' },
+      })
+
+      const response = await router.route(request)
+      expect(response.status).toBe(400) // Should fail validation
+      expect(mockNamespace.get).not.toHaveBeenCalled()
+    })
+
+    it('should handle whitespace-only tenant ID as empty', async () => {
+      const router = createTenantRouter({
+        doNamespace: mockNamespace,
+        extractTenant: 'header',
+      })
+
+      const request = createMockRequest('https://app.com/api', {
+        headers: { 'X-Tenant-ID': '   ' },
+      })
+
+      const response = await router.route(request)
+      // After trimming, empty string should be treated as missing tenant
+      expect(response.status).toBe(400)
+    })
+
+    it('should handle tenant ID with special characters within 128 char limit', async () => {
+      const router = createTenantRouter({
+        doNamespace: mockNamespace,
+        extractTenant: 'header',
+      })
+
+      // Valid tenant ID with allowed special characters (hyphens, underscores)
+      const validTenantId = 'tenant-name_with-special_chars-123'
+      const request = createMockRequest('https://app.com/api', {
+        headers: { 'X-Tenant-ID': validTenantId },
+      })
+
+      await router.route(request)
+      expect(mockNamespace.idFromName).toHaveBeenCalledWith(validTenantId)
+    })
+  })
+})