@dotdo/postgres 0.1.0

package/src/worker/cdc-backpressure.test.ts

@@ -0,0 +1,726 @@
+/**
+ * Tests for CDC Backpressure Coordinator
+ * Task: postgres-8pqw - CDC/WAL integration with streaming backpressure coordination
+ *
+ * Tests cover:
+ * 1. Consumer registration and management
+ * 2. Backpressure triggering and relief
+ * 3. Per-table water marks
+ * 4. Metrics collection
+ * 5. High-throughput load scenarios
+ * 6. WAL event conversion
+ */
+
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest'
+import {
+  CDCBackpressureCoordinator,
+  createCDCBackpressureCoordinator,
+  createBackpressureAwareBroadcast,
+  walEventToChangePayload,
+  consumeWALStream,
+  type CDCBackpressureConfig,
+  type CDCBackpressureEvent,
+  type WALEvent,
+} from './cdc-backpressure'
+import type { ChangePayload } from './types'
+
+// ============================================================================
+// Test Helpers
+// ============================================================================
+
+/**
+ * Create a change payload for testing
+ */
+function createChange(
+  table: string,
+  operation: 'INSERT' | 'UPDATE' | 'DELETE' = 'INSERT',
+  data: Record<string, unknown> = { id: 1 }
+): ChangePayload {
+  return {
+    table,
+    operation,
+    newRow: operation !== 'DELETE' ? data : undefined,
+    oldRow: operation !== 'INSERT' ? data : undefined,
+    timestamp: Date.now(),
+  }
+}
+
+/**
+ * Create a WAL event for testing
+ */
+function createWALEvent(
+  type: 'INSERT' | 'UPDATE' | 'DELETE',
+  table: string,
+  data: Record<string, unknown> = { id: 1 }
+): WALEvent {
+  return {
+    type,
+    table,
+    schema: 'public',
+    lsn: `${Date.now().toString(16)}/1`,
+    xid: 123,
+    newRow: type !== 'DELETE' ? data : undefined,
+    oldRow: type !== 'INSERT' ? data : undefined,
+    timestamp: Date.now(),
+  }
+}
+
+/**
+ * Consume all available items from an async iterator
+ */
+async function consumeAll<T>(
+  iterator: AsyncIterable<T>,
+  maxItems: number = 100,
+  timeoutMs: number = 100
+): Promise<T[]> {
+  const items: T[] = []
+  const timeoutPromise = new Promise<'timeout'>((resolve) =>
+    setTimeout(() => resolve('timeout'), timeoutMs)
+  )
+
+  const asyncIterator = iterator[Symbol.asyncIterator]()
+
+  for (let i = 0; i < maxItems; i++) {
+    const result = await Promise.race([
+      asyncIterator.next(),
+      timeoutPromise,
+    ])
+
+    if (result === 'timeout' || (typeof result === 'object' && result.done)) {
+      break
+    }
+
+    if (typeof result === 'object' && 'value' in result) {
+      items.push(result.value)
+    }
+  }
+
+  return items
+}
+
+/**
+ * Wait for a condition with timeout
+ */
+async function waitFor(
+  condition: () => boolean,
+  timeoutMs: number = 1000,
+  intervalMs: number = 10
+): Promise<boolean> {
+  const start = Date.now()
+  while (Date.now() - start < timeoutMs) {
+    if (condition()) return true
+    await new Promise((resolve) => setTimeout(resolve, intervalMs))
+  }
+  return false
+}
+
+// ============================================================================
+// CDCBackpressureCoordinator Tests
+// ============================================================================
+
+describe('CDCBackpressureCoordinator', () => {
+  let coordinator: CDCBackpressureCoordinator
+
+  beforeEach(() => {
+    coordinator = createCDCBackpressureCoordinator({
+      highWaterMark: 10,
+      lowWaterMark: 5,
+      maxBufferSize: 100,
+    })
+  })
+
+  afterEach(() => {
+    coordinator.shutdown()
+  })
+
+  describe('Consumer Management', () => {
+    it('should register a consumer', () => {
+      const consumerId = coordinator.registerConsumer(['users'])
+
+      expect(consumerId).toMatch(/^cdc-consumer-\d+-\d+$/)
+      expect(coordinator.hasConsumer(consumerId)).toBe(true)
+      expect(coordinator.getConsumerCount()).toBe(1)
+    })
+
+    it('should register multiple consumers', () => {
+      const consumer1 = coordinator.registerConsumer(['users'])
+      const consumer2 = coordinator.registerConsumer(['orders'])
+      const consumer3 = coordinator.registerConsumer() // All tables
+
+      expect(coordinator.getConsumerCount()).toBe(3)
+      expect(coordinator.getConsumerIds()).toContain(consumer1)
+      expect(coordinator.getConsumerIds()).toContain(consumer2)
+      expect(coordinator.getConsumerIds()).toContain(consumer3)
+    })
+
+    it('should unregister a consumer', () => {
+      const consumerId = coordinator.registerConsumer(['users'])
+
+      expect(coordinator.unregisterConsumer(consumerId)).toBe(true)
+      expect(coordinator.hasConsumer(consumerId)).toBe(false)
+      expect(coordinator.getConsumerCount()).toBe(0)
+    })
+
+    it('should return false when unregistering non-existent consumer', () => {
+      expect(coordinator.unregisterConsumer('non-existent')).toBe(false)
+    })
+
+    it('should allow per-consumer backpressure config', () => {
+      const consumerId = coordinator.registerConsumer(['users'], {
+        highWaterMark: 5,
+        lowWaterMark: 2,
+      })
+
+      const stats = coordinator.getConsumerStats(consumerId)
+      expect(stats).not.toBeNull()
+    })
+  })
+
+  describe('Change Production', () => {
+    it('should deliver changes to subscribed consumers', async () => {
+      const consumerId = coordinator.registerConsumer(['users'])
+      const change = createChange('users')
+
+      const delivered = await coordinator.pushChange(change)
+
+      expect(delivered).toBe(1)
+
+      const items = await consumeAll(coordinator.getConsumerIterator(consumerId))
+      expect(items).toHaveLength(1)
+      expect(items[0].table).toBe('users')
+    })
+
+    it('should not deliver changes to non-subscribed consumers', async () => {
+      const consumerId = coordinator.registerConsumer(['orders'])
+      const change = createChange('users')
+
+      const delivered = await coordinator.pushChange(change)
+
+      expect(delivered).toBe(0)
+    })
+
+    it('should deliver to consumers subscribed to all tables', async () => {
+      const consumerId = coordinator.registerConsumer() // Empty = all tables
+      const change = createChange('users')
+
+      const delivered = await coordinator.pushChange(change)
+
+      expect(delivered).toBe(1)
+    })
+
+    it('should deliver to multiple consumers', async () => {
+      const consumer1 = coordinator.registerConsumer(['users'])
+      const consumer2 = coordinator.registerConsumer(['users'])
+      const change = createChange('users')
+
+      const delivered = await coordinator.pushChange(change)
+
+      expect(delivered).toBe(2)
+    })
+
+    it('should handle batch changes', async () => {
+      const consumerId = coordinator.registerConsumer(['users'])
+      const changes = [
+        createChange('users', 'INSERT', { id: 1 }),
+        createChange('users', 'INSERT', { id: 2 }),
+        createChange('users', 'INSERT', { id: 3 }),
+      ]
+
+      const delivered = await coordinator.pushChanges(changes)
+
+      expect(delivered).toBe(3)
+    })
+  })
+
+  describe('Backpressure Triggering', () => {
+    it('should trigger backpressure when high water mark exceeded', async () => {
+      const backpressureEvents: CDCBackpressureEvent[] = []
+      coordinator.updateConfig({
+        onBackpressure: (event) => backpressureEvents.push(event),
+      })
+
+      const consumerId = coordinator.registerConsumer(['users'])
+
+      // Push more than high water mark without consuming
+      for (let i = 0; i < 15; i++) {
+        await coordinator.pushChange(createChange('users', 'INSERT', { id: i }))
+      }
+
+      // Should have triggered backpressure
+      expect(backpressureEvents.length).toBeGreaterThan(0)
+      expect(backpressureEvents[0].type).toBe('triggered')
+      expect(backpressureEvents[0].consumerId).toBe(consumerId)
+    })
+
+    it('should drop changes for paused consumers', async () => {
+      const consumerId = coordinator.registerConsumer(['users'])
+
+      // Push more than high water mark
+      for (let i = 0; i < 15; i++) {
+        await coordinator.pushChange(createChange('users', 'INSERT', { id: i }))
+      }
+
+      const metrics = coordinator.getMetrics()
+      expect(metrics.changesDropped).toBeGreaterThan(0)
+    })
+
+    it('should relieve backpressure when buffer drains', async () => {
+      const reliefEvents: CDCBackpressureEvent[] = []
+      coordinator.updateConfig({
+        onRelief: (event) => reliefEvents.push(event),
+      })
+
+      const consumerId = coordinator.registerConsumer(['users'])
+
+      // Push to trigger backpressure
+      for (let i = 0; i < 15; i++) {
+        await coordinator.pushChange(createChange('users', 'INSERT', { id: i }))
+      }
+
+      // Consume items to drain buffer
+      const iterator = coordinator.getConsumerIterator(consumerId)
+      await consumeAll(iterator, 10, 50)
+
+      // Continue consuming to reach low water mark
+      // The relief should be triggered when buffer drops below lowWaterMark
+      // This test verifies the mechanism is in place
+      const stats = coordinator.getConsumerStats(consumerId)
+      expect(stats).not.toBeNull()
+    })
+
+    it('should respect per-table water marks', async () => {
+      coordinator.setTableWaterMarks('users', {
+        highWaterMark: 3,
+        lowWaterMark: 1,
+      })
+
+      const consumerId = coordinator.registerConsumer(['users'])
+
+      // Push just above the table-specific high water mark
+      for (let i = 0; i < 5; i++) {
+        await coordinator.pushChange(createChange('users', 'INSERT', { id: i }))
+      }
+
+      const metrics = coordinator.getMetrics()
+      // Should have dropped some due to table-specific low threshold
+      expect(metrics.tableMetrics['users']).toBeDefined()
+    })
+
+    it('should manually pause and resume consumers', async () => {
+      const consumerId = coordinator.registerConsumer(['users'])
+
+      expect(coordinator.isConsumerPaused(consumerId)).toBe(false)
+
+      coordinator.pauseConsumer(consumerId)
+      expect(coordinator.isConsumerPaused(consumerId)).toBe(true)
+
+      coordinator.resumeConsumer(consumerId)
+      expect(coordinator.isConsumerPaused(consumerId)).toBe(false)
+    })
+  })
+
+  describe('Metrics', () => {
+    it('should track changes processed', async () => {
+      coordinator.registerConsumer(['users'])
+
+      await coordinator.pushChange(createChange('users'))
+      await coordinator.pushChange(createChange('users'))
+      await coordinator.pushChange(createChange('users'))
+
+      const metrics = coordinator.getMetrics()
+      expect(metrics.changesProcessed).toBe(3)
+    })
+
+    it('should track active consumers', async () => {
+      coordinator.registerConsumer(['users'])
+      coordinator.registerConsumer(['orders'])
+
+      const metrics = coordinator.getMetrics()
+      expect(metrics.activeConsumers).toBe(2)
+    })
+
+    it('should track per-table metrics', async () => {
+      coordinator.registerConsumer()
+
+      await coordinator.pushChange(createChange('users'))
+      await coordinator.pushChange(createChange('users'))
+      await coordinator.pushChange(createChange('orders'))
+
+      const metrics = coordinator.getMetrics()
+      expect(metrics.tableMetrics['users'].changesProcessed).toBe(2)
+      expect(metrics.tableMetrics['orders'].changesProcessed).toBe(1)
+    })
+
+    it('should track backpressure events', async () => {
+      coordinator.registerConsumer(['users'])
+
+      // Push more than high water mark
+      for (let i = 0; i < 20; i++) {
+        await coordinator.pushChange(createChange('users', 'INSERT', { id: i }))
+      }
+
+      const metrics = coordinator.getMetrics()
+      expect(metrics.backpressureTriggered).toBeGreaterThan(0)
+    })
+
+    it('should reset metrics', async () => {
+      coordinator.registerConsumer(['users'])
+
+      await coordinator.pushChange(createChange('users'))
+
+      coordinator.resetMetrics()
+
+      const metrics = coordinator.getMetrics()
+      expect(metrics.changesProcessed).toBe(0)
+      expect(metrics.changesDropped).toBe(0)
+    })
+  })
+
+  describe('Configuration', () => {
+    it('should check if enabled', () => {
+      expect(coordinator.isEnabled()).toBe(true)
+    })
+
+    it('should disable and enable', () => {
+      coordinator.disable()
+      expect(coordinator.isEnabled()).toBe(false)
+
+      coordinator.enable()
+      expect(coordinator.isEnabled()).toBe(true)
+    })
+
+    it('should not process changes when disabled', async () => {
+      coordinator.disable()
+      coordinator.registerConsumer(['users'])
+
+      const delivered = await coordinator.pushChange(createChange('users'))
+
+      expect(delivered).toBe(0)
+    })
+
+    it('should update configuration', () => {
+      coordinator.updateConfig({
+        highWaterMark: 50,
+        lowWaterMark: 25,
+      })
+
+      const config = coordinator.getConfig()
+      expect(config.highWaterMark).toBe(50)
+      expect(config.lowWaterMark).toBe(25)
+    })
+
+    it('should set table water marks', () => {
+      coordinator.setTableWaterMarks('users', {
+        highWaterMark: 100,
+        lowWaterMark: 50,
+      })
+
+      const config = coordinator.getConfig()
+      expect(config.tableWaterMarks?.['users']).toEqual({
+        highWaterMark: 100,
+        lowWaterMark: 50,
+      })
+    })
+  })
+
+  describe('Cleanup', () => {
+    it('should shutdown cleanly', () => {
+      coordinator.registerConsumer(['users'])
+      coordinator.registerConsumer(['orders'])
+
+      coordinator.shutdown()
+
+      expect(coordinator.getConsumerCount()).toBe(0)
+    })
+
+    it('should abort all consumers with error', () => {
+      coordinator.registerConsumer(['users'])
+      coordinator.registerConsumer(['orders'])
+
+      coordinator.abort(new Error('Test abort'))
+
+      expect(coordinator.getConsumerCount()).toBe(0)
+    })
+  })
+})
+
+// ============================================================================
+// Load Testing
+// ============================================================================
+
+describe('High-Throughput Load Tests', () => {
+  it('should handle burst of changes', async () => {
+    const coordinator = createCDCBackpressureCoordinator({
+      highWaterMark: 1000,
+      lowWaterMark: 500,
+      maxBufferSize: 5000,
+    })
+
+    try {
+      const consumerId = coordinator.registerConsumer(['users'])
+
+      // Push a burst of 500 changes
+      const changes = Array.from({ length: 500 }, (_, i) =>
+        createChange('users', 'INSERT', { id: i })
+      )
+
+      const delivered = await coordinator.pushChanges(changes)
+
+      expect(delivered).toBe(500)
+
+      const metrics = coordinator.getMetrics()
+      expect(metrics.changesProcessed).toBe(500)
+      expect(metrics.changesDropped).toBe(0)
+    } finally {
+      coordinator.shutdown()
+    }
+  })
+
+  it('should handle multiple tables under load', async () => {
+    const coordinator = createCDCBackpressureCoordinator({
+      highWaterMark: 100,
+      lowWaterMark: 50,
+    })
+
+    try {
+      // Register consumers for different tables
+      coordinator.registerConsumer(['users'])
+      coordinator.registerConsumer(['orders'])
+      coordinator.registerConsumer() // All tables
+
+      // Push changes to multiple tables
+      const tables = ['users', 'orders', 'products', 'logs']
+      for (let i = 0; i < 100; i++) {
+        const table = tables[i % tables.length]!
+        await coordinator.pushChange(createChange(table, 'INSERT', { id: i }))
+      }
+
+      const metrics = coordinator.getMetrics()
+      expect(metrics.changesProcessed).toBeGreaterThan(0)
+      expect(Object.keys(metrics.tableMetrics).length).toBe(4)
+    } finally {
+      coordinator.shutdown()
+    }
+  })
+
+  it('should handle concurrent consumers', async () => {
+    const coordinator = createCDCBackpressureCoordinator({
+      highWaterMark: 50,
+      lowWaterMark: 25,
+    })
+
+    try {
+      // Register multiple consumers
+      const consumerIds = Array.from({ length: 10 }, () =>
+        coordinator.registerConsumer(['users'])
+      )
+
+      expect(coordinator.getConsumerCount()).toBe(10)
+
+      // Push changes concurrently
+      const pushPromises = Array.from({ length: 30 }, (_, i) =>
+        coordinator.pushChange(createChange('users', 'INSERT', { id: i }))
+      )
+
+      await Promise.all(pushPromises)
+
+      const metrics = coordinator.getMetrics()
+      expect(metrics.changesProcessed).toBeGreaterThan(0)
+      expect(metrics.activeConsumers).toBe(10)
+    } finally {
+      coordinator.shutdown()
+    }
+  })
+
+  it('should track backpressure ratio under sustained load', async () => {
+    const coordinator = createCDCBackpressureCoordinator({
+      highWaterMark: 5,
+      lowWaterMark: 2,
+      metricsSampleRate: 1,
+    })
+
+    try {
+      coordinator.registerConsumer(['users'])
+
+      // Push more than buffer can handle
+      for (let i = 0; i < 50; i++) {
+        await coordinator.pushChange(createChange('users', 'INSERT', { id: i }))
+      }
+
+      const metrics = coordinator.getMetrics()
+      expect(metrics.backpressureTriggered).toBeGreaterThan(0)
+      expect(metrics.changesDropped).toBeGreaterThan(0)
+      // Backpressure ratio should be positive
+      expect(metrics.peakBufferSize).toBeGreaterThan(0)
+    } finally {
+      coordinator.shutdown()
+    }
+  })
+})
+
+// ============================================================================
+// WAL Event Conversion Tests
+// ============================================================================
+
+describe('WAL Event Conversion', () => {
+  it('should convert INSERT WAL event to ChangePayload', () => {
+    const event = createWALEvent('INSERT', 'users', { id: 1, name: 'Alice' })
+    const change = walEventToChangePayload(event)
+
+    expect(change).not.toBeNull()
+    expect(change!.table).toBe('users')
+    expect(change!.operation).toBe('INSERT')
+    expect(change!.newRow).toEqual({ id: 1, name: 'Alice' })
+    expect(change!.oldRow).toBeUndefined()
+    expect(change!.lsn).toBe(event.lsn)
+  })
+
+  it('should convert UPDATE WAL event to ChangePayload', () => {
+    const event = createWALEvent('UPDATE', 'users', { id: 1, name: 'Alicia' })
+    const change = walEventToChangePayload(event)
+
+    expect(change).not.toBeNull()
+    expect(change!.operation).toBe('UPDATE')
+    expect(change!.newRow).toEqual({ id: 1, name: 'Alicia' })
+    expect(change!.oldRow).toEqual({ id: 1, name: 'Alicia' })
+  })
+
+  it('should convert DELETE WAL event to ChangePayload', () => {
+    const event = createWALEvent('DELETE', 'users', { id: 1 })
+    const change = walEventToChangePayload(event)
+
+    expect(change).not.toBeNull()
+    expect(change!.operation).toBe('DELETE')
+    expect(change!.newRow).toBeUndefined()
+    expect(change!.oldRow).toEqual({ id: 1 })
+  })
+
+  it('should return null for non-data WAL events', () => {
+    const beginEvent: WALEvent = {
+      type: 'BEGIN',
+      lsn: '123/1',
+      xid: 1,
+      timestamp: Date.now(),
+    }
+    expect(walEventToChangePayload(beginEvent)).toBeNull()
+
+    const commitEvent: WALEvent = {
+      type: 'COMMIT',
+      lsn: '123/2',
+      xid: 1,
+      timestamp: Date.now(),
+    }
+    expect(walEventToChangePayload(commitEvent)).toBeNull()
+  })
+
+  it('should return null for WAL events without table', () => {
+    const event: WALEvent = {
+      type: 'INSERT',
+      lsn: '123/1',
+      timestamp: Date.now(),
+    }
+    expect(walEventToChangePayload(event)).toBeNull()
+  })
+})
+
+// ============================================================================
+// Integration Helpers Tests
+// ============================================================================
+
+describe('Integration Helpers', () => {
+  describe('createBackpressureAwareBroadcast', () => {
+    it('should create a wrapped broadcast function', async () => {
+      const coordinator = createCDCBackpressureCoordinator()
+      const originalCalls: ChangePayload[] = []
+      const originalBroadcast = (change: ChangePayload) => {
+        originalCalls.push(change)
+      }
+
+      const wrappedBroadcast = createBackpressureAwareBroadcast(
+        coordinator,
+        originalBroadcast
+      )
+
+      coordinator.registerConsumer(['users'])
+
+      const change = createChange('users')
+      await wrappedBroadcast(change)
+
+      // Should call both coordinator and original
+      expect(coordinator.getMetrics().changesProcessed).toBe(1)
+      expect(originalCalls).toHaveLength(1)
+      expect(originalCalls[0]).toBe(change)
+
+      coordinator.shutdown()
+    })
+  })
+
+  describe('consumeWALStream', () => {
+    it('should consume WAL events and push to coordinator', async () => {
+      const coordinator = createCDCBackpressureCoordinator()
+      coordinator.registerConsumer()
+
+      async function* generateWALEvents(): AsyncGenerator<WALEvent> {
+        yield createWALEvent('INSERT', 'users', { id: 1 })
+        yield createWALEvent('UPDATE', 'users', { id: 1, name: 'Updated' })
+        yield createWALEvent('DELETE', 'users', { id: 1 })
+      }
+
+      await consumeWALStream(coordinator, generateWALEvents())
+
+      const metrics = coordinator.getMetrics()
+      expect(metrics.changesProcessed).toBe(3)
+
+      coordinator.shutdown()
+    })
+
+    it('should skip non-data WAL events', async () => {
+      const coordinator = createCDCBackpressureCoordinator()
+      coordinator.registerConsumer()
+
+      async function* generateWALEvents(): AsyncGenerator<WALEvent> {
+        yield { type: 'BEGIN', lsn: '1/1', xid: 1, timestamp: Date.now() }
+        yield createWALEvent('INSERT', 'users', { id: 1 })
+        yield { type: 'COMMIT', lsn: '1/2', xid: 1, timestamp: Date.now() }
+      }
+
+      await consumeWALStream(coordinator, generateWALEvents())
+
+      const metrics = coordinator.getMetrics()
+      expect(metrics.changesProcessed).toBe(1)
+
+      coordinator.shutdown()
+    })
+  })
+})
+
+// ============================================================================
+// Factory Function Tests
+// ============================================================================
+
+describe('createCDCBackpressureCoordinator', () => {
+  it('should create a coordinator with default config', () => {
+    const coordinator = createCDCBackpressureCoordinator()
+
+    expect(coordinator.isEnabled()).toBe(true)
+    expect(coordinator.getConsumerCount()).toBe(0)
+
+    coordinator.shutdown()
+  })
+
+  it('should create a coordinator with custom config', () => {
+    const onBackpressure = vi.fn()
+    const coordinator = createCDCBackpressureCoordinator({
+      highWaterMark: 50,
+      lowWaterMark: 25,
+      onBackpressure,
+    })
+
+    const config = coordinator.getConfig()
+    expect(config.highWaterMark).toBe(50)
+    expect(config.lowWaterMark).toBe(25)
+    expect(config.onBackpressure).toBe(onBackpressure)
+
+    coordinator.shutdown()
+  })
+})