@dotdo/postgres 0.1.0

package/src/iceberg/time-travel-api.test.ts

@@ -0,0 +1,1029 @@
+/**
+ * Time Travel REST API Module Tests
+ * Task: postgres-8gdz.1 - [RED] Audit source files vs test files for iceberg
+ *
+ * Tests for time-travel-api.ts module exports:
+ * - createTimeTravelApi()
+ * - timeTravelApiMiddleware()
+ * - TimeTravelApiConfig type
+ * - API endpoints:
+ *   - GET /v1/do/{doId}/query
+ *   - POST /v1/do/{doId}/sql
+ *   - GET /v1/do/{doId}/snapshots
+ *   - GET /v1/do/{doId}/snapshots/:snapshotId
+ *   - GET /v1/do/{doId}/time-range
+ *   - GET /v1/do/{doId}/resolve-timestamp
+ *   - GET /v1/do/{doId}/analytics/change-rate
+ *   - GET /v1/do/{doId}/analytics/growth
+ *   - GET /v1/do/{doId}/analytics/snapshot-comparison
+ *
+ * These are stub/failing tests for the RED phase of TDD.
+ */
+
+import { describe, it, expect, beforeEach, vi } from 'vitest'
+import type { Context } from 'hono'
+import {
+  createTimeTravelApi,
+  timeTravelApiMiddleware,
+  type TimeTravelApiConfig,
+  type TimeTravelQueryRequest,
+  type TimeTravelQueryResponse,
+  type SnapshotListResponse,
+  type TimeRangeResponse,
+} from './time-travel-api'
+import { IcebergCatalog, createIcebergCatalog } from './catalog'
+import type { IcebergTableMetadata } from './types'
+
+// ============================================================================
+// Mock R2Bucket
+// ============================================================================
+
+function createMockBucket(): R2Bucket {
+  const storage = new Map<string, { data: string | ArrayBuffer; metadata?: Record<string, string> }>()
+
+  return {
+    put: vi.fn(async (key: string, data: string | ArrayBuffer | ReadableStream, options?: R2PutOptions) => {
+      storage.set(key, {
+        data: data as string | ArrayBuffer,
+        metadata: options?.customMetadata,
+      })
+      return {
+        key,
+        version: 'test-version',
+        size: typeof data === 'string' ? data.length : (data as ArrayBuffer).byteLength,
+        etag: 'test-etag',
+        httpEtag: '"test-etag"',
+        uploaded: new Date(),
+        httpMetadata: options?.httpMetadata || {},
+        customMetadata: options?.customMetadata || {},
+      } as R2Object
+    }),
+    get: vi.fn(async (key: string) => {
+      const item = storage.get(key)
+      if (!item) return null
+
+      return {
+        key,
+        version: 'test-version',
+        size: typeof item.data === 'string' ? item.data.length : (item.data as ArrayBuffer).byteLength,
+        etag: 'test-etag',
+        httpEtag: '"test-etag"',
+        uploaded: new Date(),
+        httpMetadata: {},
+        customMetadata: item.metadata || {},
+        text: async () => typeof item.data === 'string' ? item.data : new TextDecoder().decode(item.data as ArrayBuffer),
+        json: async () => JSON.parse(typeof item.data === 'string' ? item.data : new TextDecoder().decode(item.data as ArrayBuffer)),
+        arrayBuffer: async () => typeof item.data === 'string' ? new TextEncoder().encode(item.data).buffer : item.data,
+        bytes: async () => typeof item.data === 'string' ? new TextEncoder().encode(item.data) : new Uint8Array(item.data as ArrayBuffer),
+        blob: async () => new Blob([item.data]),
+        body: null,
+        bodyUsed: false,
+        writeHttpMetadata: () => {},
+      } as R2ObjectBody
+    }),
+    head: vi.fn(async (key: string) => {
+      const item = storage.get(key)
+      if (!item) return null
+
+      return {
+        key,
+        version: 'test-version',
+        size: typeof item.data === 'string' ? item.data.length : (item.data as ArrayBuffer).byteLength,
+        etag: 'test-etag',
+        httpEtag: '"test-etag"',
+        uploaded: new Date(),
+        httpMetadata: {},
+        customMetadata: item.metadata || {},
+      } as R2Object
+    }),
+    delete: vi.fn(async (keys: string | string[]) => {
+      const keyList = Array.isArray(keys) ? keys : [keys]
+      for (const key of keyList) {
+        storage.delete(key)
+      }
+    }),
+    list: vi.fn(async (options?: R2ListOptions) => {
+      const prefix = options?.prefix || ''
+      const objects: R2Object[] = []
+
+      for (const [key, item] of storage) {
+        if (key.startsWith(prefix)) {
+          objects.push({
+            key,
+            version: 'test-version',
+            size: typeof item.data === 'string' ? item.data.length : (item.data as ArrayBuffer).byteLength,
+            etag: 'test-etag',
+            httpEtag: '"test-etag"',
+            uploaded: new Date(),
+            httpMetadata: {},
+            customMetadata: item.metadata || {},
+          } as R2Object)
+        }
+      }
+
+      return {
+        objects,
+        truncated: false,
+        cursor: undefined,
+        delimitedPrefixes: [],
+      } as R2Objects
+    }),
+    createMultipartUpload: vi.fn(),
+    resumeMultipartUpload: vi.fn(),
+  } as unknown as R2Bucket
+}
+
+// ============================================================================
+// Test Helpers
+// ============================================================================
+
+// The table location must match the catalog's structure
+const TABLE_LOCATION = 'iceberg/namespaces/default/test-table'
+
+function createTestMetadata(
+  snapshots: Array<{ id: number; timestampMs: number }> = []
+): IcebergTableMetadata {
+  return {
+    'format-version': 2,
+    'table-uuid': 'test-uuid-123',
+    location: TABLE_LOCATION,
+    'last-sequence-number': snapshots.length,
+    'last-updated-ms': Date.now(),
+    'last-column-id': 12,
+    'current-schema-id': 0,
+    schemas: [{ type: 'struct', 'schema-id': 0, fields: [] }],
+    'default-spec-id': 0,
+    'partition-specs': [{ 'spec-id': 0, fields: [] }],
+    'last-partition-id': 0,
+    'default-sort-order-id': 0,
+    'sort-orders': [{ 'order-id': 0, fields: [] }],
+    'current-snapshot-id': snapshots.length > 0 ? snapshots[snapshots.length - 1]!.id : undefined,
+    snapshots: snapshots.map((s, i) => ({
+      'snapshot-id': s.id,
+      'sequence-number': i + 1,
+      'timestamp-ms': s.timestampMs,
+      'manifest-list': `${TABLE_LOCATION}/metadata/snap-${s.id}.avro`,
+      summary: { operation: 'append' as const, 'total-records': '100', 'total-data-files': '1' },
+    })),
+  }
+}
+
+async function setupTestCatalog(bucket: R2Bucket, metadata: IcebergTableMetadata): Promise<IcebergCatalog> {
+  // Create catalog instance
+  const catalog = createIcebergCatalog({
+    bucket,
+    prefix: 'iceberg/',
+  })
+
+  // Initialize the catalog
+  await catalog.initialize()
+
+  // Create the default namespace
+  await catalog.createNamespace({ levels: ['default'] })
+
+  // Create the test table using the catalog API (registers it in the catalog)
+  await catalog.createTable(
+    {
+      namespace: { levels: ['default'] },
+      name: 'test-table',
+    },
+    metadata
+  )
+
+  // Create manifest list files for each snapshot
+  for (const snapshot of metadata.snapshots ?? []) {
+    const manifestListPath = snapshot['manifest-list']
+    const manifestPath = `${TABLE_LOCATION}/manifests/manifest-${snapshot['snapshot-id']}.avro`
+
+    // Create manifest list (contains references to manifests)
+    const manifestList = {
+      manifests: [
+        {
+          'manifest-path': manifestPath,
+          'manifest-length': 1000,
+          'partition-spec-id': 0,
+          'content': 0, // data
+          'sequence-number': snapshot['sequence-number'],
+          'min-sequence-number': 1,
+          'added-snapshot-id': snapshot['snapshot-id'],
+          'added-data-files-count': 1,
+          'existing-data-files-count': 0,
+          'deleted-data-files-count': 0,
+          'added-rows-count': 100,
+          'existing-rows-count': 0,
+          'deleted-rows-count': 0,
+        },
+      ],
+    }
+    await bucket.put(manifestListPath, JSON.stringify(manifestList))
+
+    // Create manifest file (contains data file entries)
+    const manifest = {
+      entries: [
+        {
+          status: 1, // ADDED
+          'snapshot-id': snapshot['snapshot-id'],
+          'data-file': {
+            'file-path': `${TABLE_LOCATION}/data/data-${snapshot['snapshot-id']}.parquet`,
+            'file-format': 'PARQUET',
+            'partition': {},
+            'record-count': 100,
+            'file-size-in-bytes': 1024,
+            'column-sizes': {},
+            'value-counts': {},
+            'null-value-counts': {},
+            'nan-value-counts': {},
+            'lower-bounds': {},
+            'upper-bounds': {},
+          },
+        },
+      ],
+    }
+    await bucket.put(manifestPath, JSON.stringify(manifest))
+  }
+
+  return catalog
+}
+
+// ============================================================================
+// createTimeTravelApi Tests
+// ============================================================================
+
+describe('createTimeTravelApi', () => {
+  let mockBucket: R2Bucket
+  let catalog: IcebergCatalog
+
+  beforeEach(async () => {
+    mockBucket = createMockBucket()
+    const metadata = createTestMetadata([
+      { id: 1, timestampMs: 1704067200000 },
+      { id: 2, timestampMs: 1704153600000 },
+    ])
+    catalog = await setupTestCatalog(mockBucket, metadata)
+  })
+
+  it('should create Hono app instance', () => {
+    const api = createTimeTravelApi({
+      catalog,
+      bucket: mockBucket,
+    })
+
+    expect(api).toBeDefined()
+    expect(typeof api.fetch).toBe('function')
+  })
+
+  it('should use default prefix /v1', () => {
+    const api = createTimeTravelApi({
+      catalog,
+      bucket: mockBucket,
+    })
+
+    expect(api).toBeDefined()
+  })
+
+  it('should accept custom prefix', () => {
+    const api = createTimeTravelApi({
+      catalog,
+      bucket: mockBucket,
+      prefix: '/api/v2',
+    })
+
+    expect(api).toBeDefined()
+  })
+
+  it('should enable CORS by default', () => {
+    const api = createTimeTravelApi({
+      catalog,
+      bucket: mockBucket,
+    })
+
+    expect(api).toBeDefined()
+  })
+
+  it('should support authentication handler', () => {
+    const authenticate = vi.fn().mockResolvedValue(true)
+
+    const api = createTimeTravelApi({
+      catalog,
+      bucket: mockBucket,
+      authenticate,
+    })
+
+    expect(api).toBeDefined()
+  })
+})
+
+// ============================================================================
+// Query Endpoint Tests
+// ============================================================================
+
+describe('GET /v1/do/:doId/query', () => {
+  let mockBucket: R2Bucket
+  let catalog: IcebergCatalog
+  let api: ReturnType<typeof createTimeTravelApi>
+
+  beforeEach(async () => {
+    mockBucket = createMockBucket()
+    const metadata = createTestMetadata([
+      { id: 1, timestampMs: 1704067200000 },
+      { id: 2, timestampMs: 1704153600000 },
+    ])
+    catalog = await setupTestCatalog(mockBucket, metadata)
+    api = createTimeTravelApi({ catalog, bucket: mockBucket })
+  })
+
+  it('should return 400 when sql parameter is missing', async () => {
+    const request = new Request('http://localhost/v1/do/test-table/query')
+    const response = await api.fetch(request)
+
+    expect(response.status).toBe(400)
+    const body = await response.json()
+    expect(body.error.type).toBe('BadRequestError')
+  })
+
+  it('should execute query with as_of parameter', async () => {
+    const request = new Request(
+      'http://localhost/v1/do/test-table/query?sql=SELECT%20*%20FROM%20users&as_of=2024-01-01T00:00:00Z'
+    )
+    const response = await api.fetch(request)
+
+    expect(response.status).toBe(200)
+    const body = await response.json() as TimeTravelQueryResponse
+    expect(body.success).toBe(true)
+    expect(body.timeTravel.mode).toBe('point-in-time')
+  })
+
+  it('should accept as_of from X-As-Of-Timestamp header', async () => {
+    const request = new Request(
+      'http://localhost/v1/do/test-table/query?sql=SELECT%20*%20FROM%20users',
+      {
+        headers: { 'X-As-Of-Timestamp': '2024-01-01T00:00:00Z' },
+      }
+    )
+    const response = await api.fetch(request)
+
+    expect(response.status).toBe(200)
+  })
+
+  it('should return 404 for non-existent table', async () => {
+    const request = new Request(
+      'http://localhost/v1/do/non-existent/query?sql=SELECT%201'
+    )
+    const response = await api.fetch(request)
+
+    expect(response.status).toBe(404)
+  })
+})
+
+// ============================================================================
+// POST /v1/do/:doId/sql Tests
+// ============================================================================
+
+describe('POST /v1/do/:doId/sql', () => {
+  let mockBucket: R2Bucket
+  let catalog: IcebergCatalog
+  let api: ReturnType<typeof createTimeTravelApi>
+
+  beforeEach(async () => {
+    mockBucket = createMockBucket()
+    const metadata = createTestMetadata([
+      { id: 1, timestampMs: 1704067200000 },
+      { id: 2, timestampMs: 1704153600000 },
+    ])
+    catalog = await setupTestCatalog(mockBucket, metadata)
+    api = createTimeTravelApi({ catalog, bucket: mockBucket })
+  })
+
+  it('should return 400 when query is missing', async () => {
+    const request = new Request('http://localhost/v1/do/test-table/sql', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({}),
+    })
+    const response = await api.fetch(request)
+
+    expect(response.status).toBe(400)
+  })
+
+  it('should execute SQL with as_of in body', async () => {
+    const request = new Request('http://localhost/v1/do/test-table/sql', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({
+        query: 'SELECT * FROM users',
+        as_of: '2024-01-01T00:00:00Z',
+      } satisfies TimeTravelQueryRequest),
+    })
+    const response = await api.fetch(request)
+
+    expect(response.status).toBe(200)
+    const body = await response.json() as TimeTravelQueryResponse
+    expect(body.success).toBe(true)
+  })
+
+  it('should parse AS OF clause from SQL', async () => {
+    const request = new Request('http://localhost/v1/do/test-table/sql', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({
+        query: "SELECT * FROM users AS OF TIMESTAMP '2024-01-01T00:00:00Z'",
+      }),
+    })
+    const response = await api.fetch(request)
+
+    expect(response.status).toBe(200)
+    const body = await response.json() as TimeTravelQueryResponse
+    expect(body.timeTravel.mode).toBe('point-in-time')
+  })
+
+  it('should support range queries with from/to timestamps', async () => {
+    const request = new Request('http://localhost/v1/do/test-table/sql', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({
+        query: 'SELECT * FROM users',
+        from_timestamp: '2024-01-01T00:00:00Z',
+        to_timestamp: '2024-01-02T00:00:00Z',
+      }),
+    })
+    const response = await api.fetch(request)
+
+    expect(response.status).toBe(200)
+    const body = await response.json() as TimeTravelQueryResponse
+    expect(body.timeTravel.mode).toBe('range')
+  })
+})
+
+// ============================================================================
+// Snapshot Endpoints Tests
+// ============================================================================
+
+describe('GET /v1/do/:doId/snapshots', () => {
+  let mockBucket: R2Bucket
+  let catalog: IcebergCatalog
+  let api: ReturnType<typeof createTimeTravelApi>
+
+  beforeEach(async () => {
+    mockBucket = createMockBucket()
+    const metadata = createTestMetadata([
+      { id: 1, timestampMs: 1704067200000 },
+      { id: 2, timestampMs: 1704153600000 },
+      { id: 3, timestampMs: 1704240000000 },
+    ])
+    catalog = await setupTestCatalog(mockBucket, metadata)
+    api = createTimeTravelApi({ catalog, bucket: mockBucket })
+  })
+
+  it('should list all snapshots', async () => {
+    const request = new Request('http://localhost/v1/do/test-table/snapshots')
+    const response = await api.fetch(request)
+
+    expect(response.status).toBe(200)
+    const body = await response.json() as SnapshotListResponse
+    expect(body.snapshots).toHaveLength(3)
+    expect(body.count).toBe(3)
+  })
+
+  it('should include current snapshot ID', async () => {
+    const request = new Request('http://localhost/v1/do/test-table/snapshots')
+    const response = await api.fetch(request)
+
+    const body = await response.json() as SnapshotListResponse
+    expect(body.currentSnapshotId).toBe(3)
+  })
+
+  it('should sort snapshots by timestamp descending', async () => {
+    const request = new Request('http://localhost/v1/do/test-table/snapshots')
+    const response = await api.fetch(request)
+
+    const body = await response.json() as SnapshotListResponse
+    expect(body.snapshots[0]?.snapshotId).toBe(3) // Most recent first
+    expect(body.snapshots[2]?.snapshotId).toBe(1)
+  })
+})
+
+describe('GET /v1/do/:doId/snapshots/:snapshotId', () => {
+  let mockBucket: R2Bucket
+  let catalog: IcebergCatalog
+  let api: ReturnType<typeof createTimeTravelApi>
+
+  beforeEach(async () => {
+    mockBucket = createMockBucket()
+    const metadata = createTestMetadata([
+      { id: 1, timestampMs: 1704067200000 },
+    ])
+    // Also add a manifest list for the snapshot
+    await mockBucket.put(
+      'iceberg/test-table/metadata/snap-1.avro',
+      JSON.stringify({ manifests: [] })
+    )
+    catalog = await setupTestCatalog(mockBucket, metadata)
+    api = createTimeTravelApi({ catalog, bucket: mockBucket })
+  })
+
+  it('should return snapshot details', async () => {
+    const request = new Request('http://localhost/v1/do/test-table/snapshots/1')
+    const response = await api.fetch(request)
+
+    expect(response.status).toBe(200)
+    const body = await response.json()
+    expect(body.snapshotId).toBe(1)
+    expect(body.timestampMs).toBe(1704067200000)
+  })
+
+  it('should return 400 for invalid snapshot ID', async () => {
+    const request = new Request('http://localhost/v1/do/test-table/snapshots/invalid')
+    const response = await api.fetch(request)
+
+    expect(response.status).toBe(400)
+  })
+
+  it('should return 404 for non-existent snapshot', async () => {
+    const request = new Request('http://localhost/v1/do/test-table/snapshots/999')
+    const response = await api.fetch(request)
+
+    expect(response.status).toBe(404)
+  })
+})
+
+// ============================================================================
+// Time Range Endpoints Tests
+// ============================================================================
+
+describe('GET /v1/do/:doId/time-range', () => {
+  let mockBucket: R2Bucket
+  let catalog: IcebergCatalog
+  let api: ReturnType<typeof createTimeTravelApi>
+
+  beforeEach(async () => {
+    mockBucket = createMockBucket()
+    const metadata = createTestMetadata([
+      { id: 1, timestampMs: 1704067200000 },
+      { id: 2, timestampMs: 1704153600000 },
+      { id: 3, timestampMs: 1704240000000 },
+    ])
+    catalog = await setupTestCatalog(mockBucket, metadata)
+    api = createTimeTravelApi({ catalog, bucket: mockBucket })
+  })
+
+  it('should return time range', async () => {
+    const request = new Request('http://localhost/v1/do/test-table/time-range')
+    const response = await api.fetch(request)
+
+    expect(response.status).toBe(200)
+    const body = await response.json() as TimeRangeResponse
+    expect(body.oldestTimestampMs).toBe(1704067200000)
+    expect(body.newestTimestampMs).toBe(1704240000000)
+  })
+
+  it('should include ISO formatted timestamps', async () => {
+    const request = new Request('http://localhost/v1/do/test-table/time-range')
+    const response = await api.fetch(request)
+
+    const body = await response.json() as TimeRangeResponse
+    expect(body.oldest).toBe('2024-01-01T00:00:00.000Z')
+    expect(body.newest).toBe('2024-01-03T00:00:00.000Z')
+  })
+
+  it('should include retention window', async () => {
+    const request = new Request('http://localhost/v1/do/test-table/time-range')
+    const response = await api.fetch(request)
+
+    const body = await response.json() as TimeRangeResponse
+    expect(body.retentionWindowMs).toBeDefined()
+  })
+})
+
+describe('GET /v1/do/:doId/resolve-timestamp', () => {
+  let mockBucket: R2Bucket
+  let catalog: IcebergCatalog
+  let api: ReturnType<typeof createTimeTravelApi>
+
+  beforeEach(async () => {
+    mockBucket = createMockBucket()
+    const metadata = createTestMetadata([
+      { id: 1, timestampMs: 1704067200000 },
+      { id: 2, timestampMs: 1704153600000 },
+    ])
+    catalog = await setupTestCatalog(mockBucket, metadata)
+    api = createTimeTravelApi({ catalog, bucket: mockBucket })
+  })
+
+  it('should return 400 when timestamp parameter is missing', async () => {
+    const request = new Request('http://localhost/v1/do/test-table/resolve-timestamp')
+    const response = await api.fetch(request)
+
+    expect(response.status).toBe(400)
+  })
+
+  it('should resolve timestamp to nearest snapshot', async () => {
+    const request = new Request(
+      'http://localhost/v1/do/test-table/resolve-timestamp?timestamp=2024-01-01T12:00:00Z'
+    )
+    const response = await api.fetch(request)
+
+    expect(response.status).toBe(200)
+    const body = await response.json()
+    expect(body.resolved.snapshotId).toBe(1)
+    expect(body.resolved.exactMatch).toBe(false)
+  })
+
+  it('should indicate exact match when timestamp matches snapshot', async () => {
+    const request = new Request(
+      'http://localhost/v1/do/test-table/resolve-timestamp?timestamp=2024-01-01T00:00:00Z'
+    )
+    const response = await api.fetch(request)
+
+    const body = await response.json()
+    expect(body.resolved.exactMatch).toBe(true)
+  })
+
+  it('should parse relative timestamps', async () => {
+    const request = new Request(
+      'http://localhost/v1/do/test-table/resolve-timestamp?timestamp=1%20hour%20ago'
+    )
+    const response = await api.fetch(request)
+
+    expect(response.status).toBe(200)
+    const body = await response.json()
+    expect(body.parsed.isRelative).toBe(true)
+  })
+})
+
+// ============================================================================
+// Analytics Endpoints Tests
+// ============================================================================
+
+describe('GET /v1/do/:doId/analytics/change-rate', () => {
+  let mockBucket: R2Bucket
+  let catalog: IcebergCatalog
+  let api: ReturnType<typeof createTimeTravelApi>
+
+  beforeEach(async () => {
+    mockBucket = createMockBucket()
+    const metadata = createTestMetadata([
+      { id: 1, timestampMs: 1704067200000 },
+      { id: 2, timestampMs: 1704153600000 },
+    ])
+    catalog = await setupTestCatalog(mockBucket, metadata)
+    api = createTimeTravelApi({ catalog, bucket: mockBucket })
+  })
+
+  it('should return 400 when start_time is missing', async () => {
+    const request = new Request(
+      'http://localhost/v1/do/test-table/analytics/change-rate?end_time=2024-01-02'
+    )
+    const response = await api.fetch(request)
+
+    expect(response.status).toBe(400)
+  })
+
+  it('should return 400 when end_time is missing', async () => {
+    const request = new Request(
+      'http://localhost/v1/do/test-table/analytics/change-rate?start_time=2024-01-01'
+    )
+    const response = await api.fetch(request)
+
+    expect(response.status).toBe(400)
+  })
+
+  it('should return change rate analysis', async () => {
+    const request = new Request(
+      'http://localhost/v1/do/test-table/analytics/change-rate?start_time=2024-01-01&end_time=2024-01-02'
+    )
+    const response = await api.fetch(request)
+
+    expect(response.status).toBe(200)
+    const body = await response.json()
+    // ChangeRateAnalysis uses netChangePerDay rather than changesPerSecond
+    expect(body).toHaveProperty('netChangePerDay')
+  })
+})
+
+describe('GET /v1/do/:doId/analytics/growth', () => {
+  let mockBucket: R2Bucket
+  let catalog: IcebergCatalog
+  let api: ReturnType<typeof createTimeTravelApi>
+
+  beforeEach(async () => {
+    mockBucket = createMockBucket()
+    const metadata = createTestMetadata([
+      { id: 1, timestampMs: 1704067200000 },
+    ])
+    catalog = await setupTestCatalog(mockBucket, metadata)
+    api = createTimeTravelApi({ catalog, bucket: mockBucket })
+  })
+
+  it('should return growth metrics', async () => {
+    const request = new Request('http://localhost/v1/do/test-table/analytics/growth')
+    const response = await api.fetch(request)
+
+    expect(response.status).toBe(200)
+    const body = await response.json()
+    // GrowthMetrics uses currentRecordCount and currentDataSizeBytes
+    expect(body).toHaveProperty('currentRecordCount')
+    expect(body).toHaveProperty('currentDataSizeBytes')
+  })
+
+  it('should accept sampling_interval parameter', async () => {
+    const request = new Request(
+      'http://localhost/v1/do/test-table/analytics/growth?sampling_interval=86400000'
+    )
+    const response = await api.fetch(request)
+
+    expect(response.status).toBe(200)
+  })
+})
+
+describe('GET /v1/do/:doId/analytics/snapshot-comparison', () => {
+  let mockBucket: R2Bucket
+  let catalog: IcebergCatalog
+  let api: ReturnType<typeof createTimeTravelApi>
+
+  beforeEach(async () => {
+    mockBucket = createMockBucket()
+    const metadata = createTestMetadata([
+      { id: 1, timestampMs: 1704067200000 },
+      { id: 2, timestampMs: 1704153600000 },
+    ])
+    catalog = await setupTestCatalog(mockBucket, metadata)
+    api = createTimeTravelApi({ catalog, bucket: mockBucket })
+  })
+
+  it('should return 400 when snapshot1 is missing', async () => {
+    const request = new Request(
+      'http://localhost/v1/do/test-table/analytics/snapshot-comparison?snapshot2=2'
+    )
+    const response = await api.fetch(request)
+
+    expect(response.status).toBe(400)
+  })
+
+  it('should return 400 when snapshot2 is missing', async () => {
+    const request = new Request(
+      'http://localhost/v1/do/test-table/analytics/snapshot-comparison?snapshot1=1'
+    )
+    const response = await api.fetch(request)
+
+    expect(response.status).toBe(400)
+  })
+
+  it('should return 400 for invalid snapshot IDs', async () => {
+    const request = new Request(
+      'http://localhost/v1/do/test-table/analytics/snapshot-comparison?snapshot1=invalid&snapshot2=2'
+    )
+    const response = await api.fetch(request)
+
+    expect(response.status).toBe(400)
+  })
+
+  it('should return snapshot comparison', async () => {
+    const request = new Request(
+      'http://localhost/v1/do/test-table/analytics/snapshot-comparison?snapshot1=1&snapshot2=2'
+    )
+    const response = await api.fetch(request)
+
+    expect(response.status).toBe(200)
+    const body = await response.json()
+    // SnapshotComparison uses recordCountDelta and dataSizeDelta
+    expect(body).toHaveProperty('recordCountDelta')
+    expect(body).toHaveProperty('dataSizeDelta')
+  })
+})
+
+// ============================================================================
+// CORS and Authentication Tests
+// ============================================================================
+
+describe('CORS handling', () => {
+  let mockBucket: R2Bucket
+  let catalog: IcebergCatalog
+
+  beforeEach(async () => {
+    mockBucket = createMockBucket()
+    const metadata = createTestMetadata([])
+    catalog = await setupTestCatalog(mockBucket, metadata)
+  })
+
+  it('should respond to OPTIONS preflight requests', async () => {
+    const api = createTimeTravelApi({ catalog, bucket: mockBucket, cors: true })
+    const request = new Request('http://localhost/v1/do/test/query', {
+      method: 'OPTIONS',
+    })
+    const response = await api.fetch(request)
+
+    expect(response.status).toBe(204)
+    expect(response.headers.get('Access-Control-Allow-Origin')).toBe('*')
+  })
+
+  it('should include CORS headers on responses', async () => {
+    const api = createTimeTravelApi({ catalog, bucket: mockBucket, cors: true })
+    const request = new Request('http://localhost/v1/do/test/time-range')
+    const response = await api.fetch(request)
+
+    expect(response.headers.get('Access-Control-Allow-Origin')).toBe('*')
+  })
+
+  it('should skip CORS when disabled', async () => {
+    const api = createTimeTravelApi({ catalog, bucket: mockBucket, cors: false })
+    const request = new Request('http://localhost/v1/do/test/time-range')
+    const response = await api.fetch(request)
+
+    expect(response.headers.get('Access-Control-Allow-Origin')).toBeNull()
+  })
+})
+
+describe('Authentication', () => {
+  let mockBucket: R2Bucket
+  let catalog: IcebergCatalog
+
+  beforeEach(async () => {
+    mockBucket = createMockBucket()
+    const metadata = createTestMetadata([])
+    catalog = await setupTestCatalog(mockBucket, metadata)
+  })
+
+  it('should return 401 when authentication fails', async () => {
+    const authenticate = vi.fn().mockResolvedValue(false)
+    const api = createTimeTravelApi({ catalog, bucket: mockBucket, authenticate })
+
+    const request = new Request('http://localhost/v1/do/test/snapshots')
+    const response = await api.fetch(request)
+
+    expect(response.status).toBe(401)
+    expect(authenticate).toHaveBeenCalled()
+  })
+
+  it('should proceed when authentication succeeds', async () => {
+    const authenticate = vi.fn().mockResolvedValue(true)
+    const api = createTimeTravelApi({ catalog, bucket: mockBucket, authenticate })
+
+    const request = new Request('http://localhost/v1/do/test/time-range')
+    const response = await api.fetch(request)
+
+    expect(authenticate).toHaveBeenCalled()
+    // Would be 200 or 404 depending on table existence, not 401
+    expect(response.status).not.toBe(401)
+  })
+})
+
+// ============================================================================
+// Error Handling Tests
+// ============================================================================
+
+describe('Error handling', () => {
+  let mockBucket: R2Bucket
+  let catalog: IcebergCatalog
+  let api: ReturnType<typeof createTimeTravelApi>
+
+  beforeEach(async () => {
+    mockBucket = createMockBucket()
+    const metadata = createTestMetadata([
+      { id: 1, timestampMs: 1704067200000 },
+    ])
+    catalog = await setupTestCatalog(mockBucket, metadata)
+    api = createTimeTravelApi({ catalog, bucket: mockBucket })
+  })
+
+  it('should return TimestampOutOfRangeError for future timestamps', async () => {
+    const futureTime = new Date(Date.now() + 86400000).toISOString() // Tomorrow
+    const request = new Request(
+      `http://localhost/v1/do/test-table/resolve-timestamp?timestamp=${encodeURIComponent(futureTime)}`
+    )
+    const response = await api.fetch(request)
+
+    expect(response.status).toBe(400)
+    const body = await response.json()
+    expect(body.error.type).toBe('TimestampOutOfRangeError')
+  })
+
+  it('should return InvalidTimestampError for invalid timestamp format', async () => {
+    const request = new Request(
+      'http://localhost/v1/do/test-table/resolve-timestamp?timestamp=not-a-timestamp'
+    )
+    const response = await api.fetch(request)
+
+    expect(response.status).toBe(400)
+    const body = await response.json()
+    expect(body.error.type).toBe('InvalidTimestampError')
+  })
+
+  it('should return TableNotFoundError for non-existent table', async () => {
+    const request = new Request('http://localhost/v1/do/non-existent-table/snapshots')
+    const response = await api.fetch(request)
+
+    expect(response.status).toBe(404)
+    const body = await response.json()
+    expect(body.error.type).toBe('TableNotFoundError')
+  })
+})
+
+// ============================================================================
+// timeTravelApiMiddleware Tests
+// ============================================================================
+
+describe('timeTravelApiMiddleware', () => {
+  it('should create same API as createTimeTravelApi', async () => {
+    const mockBucket = createMockBucket()
+    const metadata = createTestMetadata([])
+    const catalog = await setupTestCatalog(mockBucket, metadata)
+
+    const middleware = timeTravelApiMiddleware({ catalog, bucket: mockBucket })
+
+    expect(middleware).toBeDefined()
+    expect(typeof middleware.fetch).toBe('function')
+  })
+})
+
+// ============================================================================
+// DO ID Parsing Tests
+// ============================================================================
+
+describe('DO ID parsing', () => {
+  let mockBucket: R2Bucket
+  let catalog: IcebergCatalog
+  let api: ReturnType<typeof createTimeTravelApi>
+
+  beforeEach(async () => {
+    mockBucket = createMockBucket()
+    const metadata = createTestMetadata([
+      { id: 1, timestampMs: 1704067200000 },
+    ])
+    catalog = await setupTestCatalog(mockBucket, metadata)
+    api = createTimeTravelApi({ catalog, bucket: mockBucket })
+  })
+
+  it('should parse simple DO ID', async () => {
+    // 'test-table' should be resolved to namespace: ['default'], name: 'test-table'
+    const request = new Request('http://localhost/v1/do/test-table/time-range')
+    const response = await api.fetch(request)
+
+    // Should find the table in default namespace
+    expect(response.status).toBe(200)
+    const body = await response.json() as TimeRangeResponse
+    expect(body.oldestTimestampMs).toBe(1704067200000)
+  })
+
+  it('should parse namespace.doId format', async () => {
+    // Create a table in a custom namespace
+    await catalog.createNamespace({ levels: ['custom'] })
+    const customMetadata = createTestMetadata([
+      { id: 2, timestampMs: 1704153600000 },
+    ])
+    customMetadata.location = 'iceberg/namespaces/custom/my-table'
+    await catalog.createTable(
+      { namespace: { levels: ['custom'] }, name: 'my-table' },
+      customMetadata
+    )
+
+    // 'custom.my-table' should be resolved to namespace: ['custom'], name: 'my-table'
+    const request = new Request('http://localhost/v1/do/custom.my-table/time-range')
+    const response = await api.fetch(request)
+
+    expect(response.status).toBe(200)
+    const body = await response.json() as TimeRangeResponse
+    expect(body.oldestTimestampMs).toBe(1704153600000)
+  })
+
+  it('should parse namespace/doId format', async () => {
+    // Create a table in a custom namespace
+    await catalog.createNamespace({ levels: ['org'] })
+    const orgMetadata = createTestMetadata([
+      { id: 3, timestampMs: 1704240000000 },
+    ])
+    orgMetadata.location = 'iceberg/namespaces/org/org-table'
+    await catalog.createTable(
+      { namespace: { levels: ['org'] }, name: 'org-table' },
+      orgMetadata
+    )
+
+    // URL-encode the slash: 'org%2Forg-table'
+    const request = new Request('http://localhost/v1/do/org%2Forg-table/time-range')
+    const response = await api.fetch(request)
+
+    expect(response.status).toBe(200)
+    const body = await response.json() as TimeRangeResponse
+    expect(body.oldestTimestampMs).toBe(1704240000000)
+  })
+
+  it('should handle URL-encoded separators', async () => {
+    // Create a table with encoded characters
+    await catalog.createNamespace({ levels: ['encoded'] })
+    const encodedMetadata = createTestMetadata([
+      { id: 4, timestampMs: 1704326400000 },
+    ])
+    encodedMetadata.location = 'iceberg/namespaces/encoded/special-table'
+    await catalog.createTable(
+      { namespace: { levels: ['encoded'] }, name: 'special-table' },
+      encodedMetadata
+    )
+
+    // URL-encode the dot: 'encoded%2Especial-table'
+    const request = new Request('http://localhost/v1/do/encoded%2Especial-table/time-range')
+    const response = await api.fetch(request)
+
+    expect(response.status).toBe(200)
+    const body = await response.json() as TimeRangeResponse
+    expect(body.oldestTimestampMs).toBe(1704326400000)
+  })
+})