@dotdo/postgres 0.1.0

package/src/cdc/transport/sse.ts

@@ -0,0 +1,723 @@
+/**
+ * SSE (Server-Sent Events) CDC Transport
+ * Task: postgres-lp00 - CDC/Change Data Capture streaming
+ *
+ * Implements CDC streaming over Server-Sent Events with:
+ * - Standard EventSource API support
+ * - Fetch-based fallback for restricted environments
+ * - Automatic reconnection with Last-Event-ID
+ * - Resume from token on reconnection
+ */
+
+import type {
+  CDCTransport,
+  CDCTransportOptions,
+  SSETransportOptions,
+  ChangeEvent,
+  SubscriptionConfig,
+  ResumeToken,
+} from '../types'
+import { parseResumeToken, serializeResumeToken } from '../resume-token'
+import { createLogger, LogLevel, type ILogger } from '@dotdo/postgres-shared'
+
+// Module-level logger for SSE transport errors
+const sseLogger: ILogger = createLogger({
+  level: LogLevel.ERROR,
+  prefix: '[SSE-Transport]',
+})
+
+// ============================================================================
+// Types
+// ============================================================================
+
+/**
+ * SSE event types sent by the server
+ */
+type SSEEventType =
+  | 'connected'
+  | 'change'
+  | 'batch'
+  | 'error'
+  | 'heartbeat'
+  | 'close'
+
+/**
+ * Connection state for the SSE transport
+ */
+type ConnectionState =
+  | 'disconnected'
+  | 'connecting'
+  | 'connected'
+  | 'reconnecting'
+  | 'closed'
+
+// ============================================================================
+// Constants
+// ============================================================================
+
+/** Default reconnection configuration */
+const DEFAULT_RECONNECT_CONFIG = {
+  enabled: true,
+  maxAttempts: 10,
+  initialDelay: 1000,
+  maxDelay: 30000,
+  backoffMultiplier: 2,
+}
+
+/** Default connection timeout in milliseconds */
+const DEFAULT_CONNECT_TIMEOUT = 10000
+
+/**
+ * SSE protocol field prefixes
+ * @see https://html.spec.whatwg.org/multipage/server-sent-events.html#parsing-an-event-stream
+ */
+const SSE_FIELD = {
+  EVENT: 'event:',
+  DATA: 'data:',
+  ID: 'id:',
+  RETRY: 'retry:',
+} as const
+
+/** Length of SSE field prefixes for parsing */
+const SSE_FIELD_LENGTH = {
+  EVENT: SSE_FIELD.EVENT.length,
+  DATA: SSE_FIELD.DATA.length,
+  ID: SSE_FIELD.ID.length,
+  RETRY: SSE_FIELD.RETRY.length,
+} as const
+
+// ============================================================================
+// SSE Transport Implementation
+// ============================================================================
+
+/**
+ * SSE CDC Transport
+ *
+ * Provides CDC streaming over Server-Sent Events with:
+ * - EventSource API for standard browsers
+ * - Fetch-based streaming for Cloudflare Workers and other environments
+ * - Automatic reconnection with resume support
+ */
+export class SSECDCTransport implements CDCTransport {
+  private options: SSETransportOptions
+  private eventSource: EventSource | null = null
+  private fetchController: AbortController | null = null
+  private state: ConnectionState = 'disconnected'
+  private reconnectAttempt = 0
+  private reconnectTimer: ReturnType<typeof setTimeout> | null = null
+
+  // Subscriptions
+  private subscriptions = new Map<string, SubscriptionConfig>()
+
+  // Event handlers
+  private changeHandlers = new Set<(event: ChangeEvent) => void>()
+  private errorHandlers = new Set<(error: Error) => void>()
+  private closeHandlers = new Set<() => void>()
+  private reconnectHandlers = new Set<() => void>()
+
+  // Resume state
+  private lastResumeToken: ResumeToken | null = null
+  private lastEventId: string | null = null
+  private lastLsn: string | null = null
+
+  constructor(options: SSETransportOptions) {
+    this.options = {
+      ...options,
+      reconnect: { ...DEFAULT_RECONNECT_CONFIG, ...options.reconnect },
+      connectTimeout: options.connectTimeout ?? DEFAULT_CONNECT_TIMEOUT,
+      useFetch: options.useFetch ?? typeof EventSource === 'undefined',
+    }
+  }
+
+  // ============================================================================
+  // CDCTransport Interface
+  // ============================================================================
+
+  async connect(options?: CDCTransportOptions): Promise<void> {
+    if (this.state === 'connected' || this.state === 'connecting') {
+      return
+    }
+
+    // Merge options
+    if (options) {
+      this.options = { ...this.options, ...options }
+    }
+
+    // Set resume token if provided
+    if (options?.resumeToken) {
+      this.lastResumeToken = options.resumeToken
+      const parsed = parseResumeToken(options.resumeToken)
+      if (parsed) {
+        this.lastLsn = parsed.lsn
+      }
+    }
+
+    this.state = 'connecting'
+
+    try {
+      if (this.options.useFetch) {
+        await this.connectWithFetch()
+      } else {
+        await this.connectWithEventSource()
+      }
+    } catch (error) {
+      this.state = 'disconnected'
+      throw error
+    }
+  }
+
+  async disconnect(): Promise<void> {
+    this.state = 'closed'
+    this.stopReconnectTimer()
+
+    if (this.eventSource) {
+      this.eventSource.close()
+      this.eventSource = null
+    }
+
+    if (this.fetchController) {
+      this.fetchController.abort()
+      this.fetchController = null
+    }
+  }
+
+  async subscribe(config: SubscriptionConfig): Promise<void> {
+    this.subscriptions.set(config.id, config)
+
+    // SSE subscriptions are established through query parameters on connect
+    // If already connected, we need to reconnect with new subscriptions
+    if (this.state === 'connected') {
+      await this.disconnect()
+      this.state = 'disconnected'
+      await this.connect()
+    }
+  }
+
+  async unsubscribe(subscriptionId: string): Promise<void> {
+    this.subscriptions.delete(subscriptionId)
+
+    // Reconnect without this subscription
+    if (this.state === 'connected') {
+      await this.disconnect()
+      this.state = 'disconnected'
+      await this.connect()
+    }
+  }
+
+  async ack(lsn: string): Promise<void> {
+    // SSE is one-directional, acks happen through reconnection with Last-Event-ID
+    this.lastLsn = lsn
+  }
+
+  isConnected(): boolean {
+    return this.state === 'connected'
+  }
+
+  on(event: 'change', handler: (event: ChangeEvent) => void): void
+  on(event: 'error', handler: (error: Error) => void): void
+  on(event: 'close', handler: () => void): void
+  on(event: 'reconnect', handler: () => void): void
+  on(
+    event: 'change' | 'error' | 'close' | 'reconnect',
+    handler: ((event: ChangeEvent) => void) | ((error: Error) => void) | (() => void)
+  ): void {
+    switch (event) {
+      case 'change':
+        this.changeHandlers.add(handler as (event: ChangeEvent) => void)
+        break
+      case 'error':
+        this.errorHandlers.add(handler as (error: Error) => void)
+        break
+      case 'close':
+        this.closeHandlers.add(handler as () => void)
+        break
+      case 'reconnect':
+        this.reconnectHandlers.add(handler as () => void)
+        break
+    }
+  }
+
+  off(event: string, handler: (...args: unknown[]) => void): void {
+    switch (event) {
+      case 'change':
+        this.changeHandlers.delete(handler as (event: ChangeEvent) => void)
+        break
+      case 'error':
+        this.errorHandlers.delete(handler as (error: Error) => void)
+        break
+      case 'close':
+        this.closeHandlers.delete(handler as () => void)
+        break
+      case 'reconnect':
+        this.reconnectHandlers.delete(handler as () => void)
+        break
+    }
+  }
+
+  // ============================================================================
+  // EventSource Implementation
+  // ============================================================================
+
+  /**
+   * Connect using the native EventSource API
+   * Used in browser environments with standard EventSource support
+   */
+  private async connectWithEventSource(): Promise<void> {
+    return new Promise((resolve, reject) => {
+      const url = this.buildUrl()
+
+      const timeout = setTimeout(() => {
+        reject(new Error(`Connection timeout after ${this.options.connectTimeout}ms`))
+        this.eventSource?.close()
+      }, this.options.connectTimeout)
+
+      this.eventSource = new EventSource(url)
+
+      this.eventSource.onopen = () => {
+        clearTimeout(timeout)
+        this.state = 'connected'
+        this.reconnectAttempt = 0
+        resolve()
+      }
+
+      this.eventSource.onerror = () => {
+        clearTimeout(timeout)
+
+        if (this.state === 'connecting') {
+          reject(new Error('Failed to connect to SSE endpoint'))
+          return
+        }
+
+        if (this.state === 'closed') {
+          return
+        }
+
+        // EventSource will automatically try to reconnect
+        // But we want to control the backoff
+        this.eventSource?.close()
+        this.state = 'disconnected'
+
+        if (this.options.reconnect?.enabled) {
+          this.scheduleReconnect()
+        } else {
+          this.emitClose()
+        }
+      }
+
+      // Handle change events
+      this.eventSource.addEventListener('change', ((event: MessageEvent) => {
+        this.handleSSEMessage('change', event.data, event.lastEventId)
+      }) as EventListener)
+
+      // Handle batch events
+      this.eventSource.addEventListener('batch', ((event: MessageEvent) => {
+        this.handleSSEMessage('batch', event.data, event.lastEventId)
+      }) as EventListener)
+
+      // Handle heartbeat events
+      this.eventSource.addEventListener('heartbeat', ((event: MessageEvent) => {
+        // Just update last event ID for reconnection
+        if (event.lastEventId) {
+          this.lastEventId = event.lastEventId
+        }
+      }) as EventListener)
+
+      // Handle error events (custom error event, not the onerror handler)
+      this.eventSource.addEventListener('server-error', ((event: MessageEvent) => {
+        const data = JSON.parse(event.data) as { message: string }
+        this.emitError(new Error(data.message))
+      }) as EventListener)
+
+      // Handle 'error' event type (distinct from onerror - this is a named SSE event)
+      this.eventSource.addEventListener('error', ((event: MessageEvent) => {
+        // Only handle if this is a MessageEvent with data (named event), not the native onerror
+        if (event instanceof MessageEvent && event.data) {
+          this.handleSSEMessage('error', event.data, event.lastEventId)
+        }
+      }) as EventListener)
+
+      // Handle close events
+      this.eventSource.addEventListener('close', () => {
+        this.eventSource?.close()
+        this.state = 'closed'
+        this.emitClose()
+      })
+
+      // Handle default message events
+      this.eventSource.onmessage = (event: MessageEvent) => {
+        this.handleSSEMessage('change', event.data, event.lastEventId)
+      }
+    })
+  }
+
+  // ============================================================================
+  // Fetch-based Implementation
+  // ============================================================================
+
+  /**
+   * Connect using the Fetch API with streaming
+   * Used in Cloudflare Workers and other environments without EventSource
+   */
+  private async connectWithFetch(): Promise<void> {
+    const url = this.buildUrl()
+    this.fetchController = new AbortController()
+
+    const headers: Record<string, string> = {
+      'Accept': 'text/event-stream',
+      'Cache-Control': 'no-cache',
+      ...this.options.headers,
+    }
+
+    if (this.options.apiKey) {
+      headers['Authorization'] = `Bearer ${this.options.apiKey}`
+    }
+
+    if (this.lastEventId) {
+      headers['Last-Event-ID'] = this.lastEventId
+    }
+
+    const response = await fetch(url, {
+      method: 'GET',
+      headers,
+      signal: this.fetchController.signal,
+    })
+
+    if (!response.ok) {
+      throw new Error(`SSE connection failed: ${response.status} ${response.statusText}`)
+    }
+
+    if (!response.body) {
+      throw new Error('SSE response has no body')
+    }
+
+    this.state = 'connected'
+    this.reconnectAttempt = 0
+
+    // Process the stream
+    this.processStream(response.body)
+  }
+
+  /**
+   * Process incoming SSE stream data
+   * Parses SSE format: event/data/id/retry fields, dispatches on empty line
+   */
+  private async processStream(body: ReadableStream<Uint8Array>): Promise<void> {
+    const reader = body.getReader()
+    const decoder = new TextDecoder()
+    let buffer = ''
+    let currentEventType = 'message'
+    let currentEventId: string | null = null
+    let currentData: string[] = []
+
+    try {
+      while (true) {
+        const { done, value } = await reader.read()
+
+        if (done) {
+          break
+        }
+
+        buffer += decoder.decode(value, { stream: true })
+        const lines = buffer.split('\n')
+        buffer = lines.pop() ?? ''
+
+        for (const line of lines) {
+          if (line === '') {
+            // Empty line = dispatch event per SSE spec
+            if (currentData.length > 0) {
+              const data = currentData.join('\n')
+              this.handleSSEMessage(
+                currentEventType as SSEEventType,
+                data,
+                currentEventId ?? undefined
+              )
+            }
+            currentEventType = 'message'
+            currentEventId = null
+            currentData = []
+          } else if (line.startsWith(SSE_FIELD.EVENT)) {
+            currentEventType = line.slice(SSE_FIELD_LENGTH.EVENT).trim()
+          } else if (line.startsWith(SSE_FIELD.DATA)) {
+            currentData.push(line.slice(SSE_FIELD_LENGTH.DATA).trim())
+          } else if (line.startsWith(SSE_FIELD.ID)) {
+            currentEventId = line.slice(SSE_FIELD_LENGTH.ID).trim()
+          } else if (line.startsWith(SSE_FIELD.RETRY)) {
+            // Server-sent retry interval per SSE spec
+            const retry = parseInt(line.slice(SSE_FIELD_LENGTH.RETRY).trim(), 10)
+            if (!isNaN(retry) && this.options.reconnect) {
+              this.options.reconnect.initialDelay = retry
+            }
+          }
+        }
+      }
+    } catch (error) {
+      if (this.state === 'closed') {
+        return
+      }
+
+      if (error instanceof Error && error.name === 'AbortError') {
+        return
+      }
+
+      this.emitError(error instanceof Error ? error : new Error(String(error)))
+    } finally {
+      reader.releaseLock()
+
+      if (this.state !== 'closed') {
+        this.state = 'disconnected'
+
+        if (this.options.reconnect?.enabled) {
+          this.scheduleReconnect()
+        } else {
+          this.emitClose()
+        }
+      }
+    }
+  }
+
+  // ============================================================================
+  // Message Handling
+  // ============================================================================
+
+  /**
+   * Handle an incoming SSE message by type
+   * Routes to appropriate handler based on event type
+   */
+  private handleSSEMessage(type: SSEEventType | string, data: string, eventId?: string): void {
+    if (eventId) {
+      this.lastEventId = eventId
+    }
+
+    try {
+      const parsed = JSON.parse(data)
+
+      switch (type) {
+        case 'change':
+        case 'message':
+          this.handleChangeEvent(parsed as ChangeEvent)
+          break
+
+        case 'batch':
+          const batch = parsed as { events: ChangeEvent[] }
+          for (const event of batch.events) {
+            this.handleChangeEvent(event)
+          }
+          break
+
+        case 'error':
+          this.emitError(new Error((parsed as { message: string }).message))
+          break
+
+        case 'heartbeat':
+          // Already handled event ID
+          break
+
+        case 'close':
+          this.disconnect()
+          break
+      }
+    } catch (err) {
+      this.emitError(err instanceof Error ? err : new Error(String(err)))
+    }
+  }
+
+  /**
+   * Process a change event and emit to handlers
+   * Updates resume token state for reconnection support
+   */
+  private handleChangeEvent(event: ChangeEvent): void {
+    // Update resume token
+    this.lastResumeToken = event.resumeToken
+    const parsed = parseResumeToken(event.resumeToken)
+    if (parsed) {
+      this.lastLsn = parsed.lsn
+    }
+
+    // Emit to handlers
+    for (const handler of this.changeHandlers) {
+      try {
+        handler(event)
+      } catch (err) {
+        sseLogger.error('Error in change handler', { error: err instanceof Error ? err.message : String(err) })
+      }
+    }
+  }
+
+  // ============================================================================
+  // URL Building
+  // ============================================================================
+
+  /**
+   * Build the SSE endpoint URL with query parameters
+   * Includes authentication, database, resume position, and subscriptions
+   */
+  private buildUrl(): string {
+    const url = new URL(this.options.url)
+
+    // Add API key
+    if (this.options.apiKey) {
+      url.searchParams.set('apiKey', this.options.apiKey)
+    }
+
+    // Add database
+    if (this.options.database) {
+      url.searchParams.set('database', this.options.database)
+    }
+
+    // Add resume position
+    if (this.lastEventId) {
+      url.searchParams.set('lastEventId', this.lastEventId)
+    } else if (this.lastResumeToken) {
+      // Include both resumeToken (full context) and resumeAfterLsn (for servers that prefer LSN)
+      url.searchParams.set('resumeToken', serializeResumeToken(this.lastResumeToken))
+      const parsed = parseResumeToken(this.lastResumeToken)
+      if (parsed) {
+        url.searchParams.set('resumeAfterLsn', parsed.lsn)
+      }
+    } else if (this.lastLsn) {
+      url.searchParams.set('resumeAfterLsn', this.lastLsn)
+    }
+
+    // Add subscriptions
+    const tables: string[] = []
+    for (const config of this.subscriptions.values()) {
+      tables.push(...config.tables)
+    }
+    if (tables.length > 0) {
+      url.searchParams.set('tables', tables.join(','))
+    }
+
+    return url.toString()
+  }
+
+  // ============================================================================
+  // Event Emission
+  // ============================================================================
+
+  private emitError(error: Error): void {
+    for (const handler of this.errorHandlers) {
+      try {
+        handler(error)
+      } catch (err) {
+        sseLogger.error('Error in error handler', { error: err instanceof Error ? err.message : String(err) })
+      }
+    }
+  }
+
+  private emitClose(): void {
+    for (const handler of this.closeHandlers) {
+      try {
+        handler()
+      } catch (err) {
+        sseLogger.error('Error in close handler', { error: err instanceof Error ? err.message : String(err) })
+      }
+    }
+  }
+
+  private emitReconnect(): void {
+    for (const handler of this.reconnectHandlers) {
+      try {
+        handler()
+      } catch (err) {
+        sseLogger.error('Error in reconnect handler', { error: err instanceof Error ? err.message : String(err) })
+      }
+    }
+  }
+
+  // ============================================================================
+  // Reconnection Logic
+  // ============================================================================
+
+  /**
+   * Schedule a reconnection attempt with exponential backoff
+   * Respects maxAttempts and maxDelay configuration
+   */
+  private scheduleReconnect(): void {
+    if (this.state === 'closed') {
+      return
+    }
+
+    this.state = 'reconnecting'
+    this.reconnectAttempt++
+
+    const config = this.options.reconnect!
+    const delay = Math.min(
+      config.initialDelay! * Math.pow(config.backoffMultiplier!, this.reconnectAttempt - 1),
+      config.maxDelay!
+    )
+
+    this.reconnectTimer = setTimeout(async () => {
+      if (this.reconnectAttempt > (config.maxAttempts ?? 10)) {
+        this.emitClose()
+        return
+      }
+
+      try {
+        await this.connect()
+        this.emitReconnect()
+      } catch {
+        // Will retry
+        this.scheduleReconnect()
+      }
+    }, delay)
+  }
+
+  /**
+   * Cancel any pending reconnection timer
+   */
+  private stopReconnectTimer(): void {
+    if (this.reconnectTimer) {
+      clearTimeout(this.reconnectTimer)
+      this.reconnectTimer = null
+    }
+  }
+
+  // ============================================================================
+  // Utility Methods
+  // ============================================================================
+
+  /**
+   * Get current connection state
+   */
+  getState(): ConnectionState {
+    return this.state
+  }
+
+  /**
+   * Get last resume token
+   */
+  getResumeToken(): ResumeToken | null {
+    return this.lastResumeToken
+  }
+
+  /**
+   * Get last event ID (for SSE resume)
+   */
+  getLastEventId(): string | null {
+    return this.lastEventId
+  }
+
+  /**
+   * Get connection statistics
+   */
+  getStats(): {
+    state: ConnectionState
+    reconnectAttempts: number
+    subscriptionCount: number
+    lastEventId: string | null
+  } {
+    return {
+      state: this.state,
+      reconnectAttempts: this.reconnectAttempt,
+      subscriptionCount: this.subscriptions.size,
+      lastEventId: this.lastEventId,
+    }
+  }
+}
+
+/**
+ * Create an SSE CDC transport
+ */
+export function createSSETransport(options: SSETransportOptions): SSECDCTransport {
+  return new SSECDCTransport(options)
+}