@dotdo/postgres 0.1.0

package/src/worker/cdc-websocket.ts

@@ -0,0 +1,1229 @@
+/**
+ * CDC WebSocket Handler
+ * Task: postgres-0n39 - WebSocket Protocol for CDC Streaming
+ * Refactor: postgres-ib23 - Improve CDC WebSocket transport reliability
+ *
+ * Provides a complete WebSocket endpoint for Change Data Capture (CDC) streaming.
+ * Features:
+ * - Subscribe/unsubscribe to table changes
+ * - Event filtering by table and operation type
+ * - Heartbeat mechanism for connection health
+ * - Reconnection support with subscription restoration
+ * - Improved connection state management
+ * - Centralized timer management
+ * - Comprehensive metrics tracking
+ */
+import type {
+  WSMessage,
+  CDCEventType,
+  SubscribePayload,
+  UnsubscribePayload,
+  ErrorPayload,
+  HeartbeatPayload,
+  WelcomePayload,
+  ReconnectPayload,
+  SubscribedPayload,
+  UnsubscribedPayload,
+  CDCWebSocketConfig,
+  QueryParam,
+} from './types'
+
+// Re-export for external use
+export type { WSMessageType, ChangePayload, QueryResultRow } from './types'
+import { parseWSMessage, serializeWSMessage, type QueryExecutor } from './websocket'
+import { CDCManager, type Subscription, type SubscribeOptions, type ChangeEvent, type Broadcaster } from './cdc'
+import { createLogger, LogLevel, type ILogger } from '@dotdo/postgres-shared'
+
+// ============================================================================
+// Constants
+// ============================================================================
+
+/**
+ * WebSocket ready state constants (matching W3C spec)
+ */
+const WS_OPEN = 1
+
+/**
+ * Default CDC WebSocket configuration
+ */
+const DEFAULT_CDC_CONFIG: Required<CDCWebSocketConfig> = {
+  heartbeatInterval: 30000,
+  heartbeatTimeout: 10000,
+  maxReconnectAttempts: 5,
+  reconnectDelay: 1000,
+  maxSubscriptions: 100,
+  bufferChanges: true,
+  maxBufferedChanges: 1000,
+}
+
+/**
+ * Error codes for CDC WebSocket operations
+ */
+export const CDCErrorCodes = {
+  /** Invalid or missing request payload */
+  INVALID_REQUEST: 'INVALID_REQUEST',
+  /** WebSocket connection not registered */
+  NO_CONNECTION: 'NO_CONNECTION',
+  /** Subscription limit reached */
+  LIMIT_EXCEEDED: 'LIMIT_EXCEEDED',
+  /** Subscription not found */
+  NOT_FOUND: 'NOT_FOUND',
+  /** Unknown message type received */
+  UNKNOWN_TYPE: 'UNKNOWN_TYPE',
+  /** Failed to parse message */
+  PARSE_ERROR: 'PARSE_ERROR',
+  /** Query execution failed */
+  QUERY_ERROR: 'QUERY_ERROR',
+  /** Internal server error */
+  INTERNAL_ERROR: 'INTERNAL_ERROR',
+} as const
+
+export type CDCErrorCode = typeof CDCErrorCodes[keyof typeof CDCErrorCodes]
+
+// ============================================================================
+// Connection State Management
+// ============================================================================
+
+/**
+ * Connection lifecycle states
+ * Provides clear state transitions for connection management
+ */
+export enum ConnectionLifecycle {
+  /** Connection is being established */
+  CONNECTING = 'connecting',
+  /** Connection is active and ready */
+  ACTIVE = 'active',
+  /** Connection is in process of reconnecting */
+  RECONNECTING = 'reconnecting',
+  /** Connection is closing */
+  CLOSING = 'closing',
+  /** Connection is closed */
+  CLOSED = 'closed',
+}
+
+/**
+ * Connection state for a WebSocket
+ */
+interface ConnectionState {
+  /** Unique connection ID for reconnection */
+  connectionId: string
+  /** WebSocket instance */
+  ws: WebSocket
+  /** Current lifecycle state */
+  lifecycle: ConnectionLifecycle
+  /** Last heartbeat received timestamp */
+  lastHeartbeat: number
+  /** Heartbeat sequence number */
+  heartbeatSeq: number
+  /** Active subscriptions for this connection */
+  subscriptions: Set<string>
+  /** Buffered changes during reconnection */
+  bufferedChanges: WSMessage[]
+  /** Count of active message processing operations (prevents heartbeat timeout during processing) */
+  activeOperations: number
+  /** Connection creation timestamp */
+  createdAt: number
+  /** Total messages received */
+  messagesReceived: number
+  /** Total messages sent */
+  messagesSent: number
+  /** Last error encountered */
+  lastError?: string
+}
+
+// ============================================================================
+// Timer Management
+// ============================================================================
+
+/**
+ * Centralized timer management for connection-related timers
+ * Ensures proper cleanup and prevents timer leaks
+ */
+class TimerManager {
+  private heartbeatTimers: Map<string, ReturnType<typeof setInterval>> = new Map()
+  private cleanupTimers: Map<string, ReturnType<typeof setTimeout>> = new Map()
+  private logger: ILogger
+
+  constructor(logger: ILogger) {
+    this.logger = logger.child({ component: 'TimerManager' })
+  }
+
+  /**
+   * Start a heartbeat timer for a connection
+   */
+  startHeartbeat(connectionId: string, interval: number, callback: () => void): void {
+    // Clear any existing timer first
+    this.stopHeartbeat(connectionId)
+
+    const timer = setInterval(callback, interval)
+    this.heartbeatTimers.set(connectionId, timer)
+    this.logger.debug('Started heartbeat timer', { connectionId, interval })
+  }
+
+  /**
+   * Stop heartbeat timer for a connection
+   */
+  stopHeartbeat(connectionId: string): boolean {
+    const timer = this.heartbeatTimers.get(connectionId)
+    if (timer) {
+      clearInterval(timer)
+      this.heartbeatTimers.delete(connectionId)
+      this.logger.debug('Stopped heartbeat timer', { connectionId })
+      return true
+    }
+    return false
+  }
+
+  /**
+   * Start a cleanup timer (for pending reconnect state cleanup)
+   */
+  startCleanupTimer(connectionId: string, delay: number, callback: () => void): void {
+    // Clear any existing timer first
+    this.stopCleanupTimer(connectionId)
+
+    const timer = setTimeout(callback, delay)
+    this.cleanupTimers.set(connectionId, timer)
+    this.logger.debug('Started cleanup timer', { connectionId, delay })
+  }
+
+  /**
+   * Stop cleanup timer for a connection
+   */
+  stopCleanupTimer(connectionId: string): boolean {
+    const timer = this.cleanupTimers.get(connectionId)
+    if (timer) {
+      clearTimeout(timer)
+      this.cleanupTimers.delete(connectionId)
+      this.logger.debug('Stopped cleanup timer', { connectionId })
+      return true
+    }
+    return false
+  }
+
+  /**
+   * Clear all timers for a connection
+   */
+  clearAllForConnection(connectionId: string): void {
+    this.stopHeartbeat(connectionId)
+    this.stopCleanupTimer(connectionId)
+  }
+
+  /**
+   * Clear all timers (for shutdown)
+   */
+  clearAll(): void {
+    for (const [connectionId] of this.heartbeatTimers) {
+      this.stopHeartbeat(connectionId)
+    }
+    for (const [connectionId] of this.cleanupTimers) {
+      this.stopCleanupTimer(connectionId)
+    }
+    this.logger.debug('Cleared all timers')
+  }
+
+  /**
+   * Get timer counts for metrics
+   */
+  getTimerCounts(): { heartbeat: number; cleanup: number } {
+    return {
+      heartbeat: this.heartbeatTimers.size,
+      cleanup: this.cleanupTimers.size,
+    }
+  }
+}
+
+// ============================================================================
+// Metrics
+// ============================================================================
+
+/**
+ * Metrics for CDC WebSocket operations
+ */
+export interface CDCWebSocketMetrics {
+  /** Total connections established */
+  connectionsTotal: number
+  /** Currently active connections */
+  connectionsActive: number
+  /** Total messages received */
+  messagesReceived: number
+  /** Total messages sent */
+  messagesSent: number
+  /** Total subscription operations */
+  subscriptionsCreated: number
+  /** Total unsubscription operations */
+  subscriptionsRemoved: number
+  /** Total errors encountered */
+  errorsTotal: number
+  /** Errors by code */
+  errorsByCode: Record<string, number>
+  /** Total heartbeat timeouts */
+  heartbeatTimeouts: number
+  /** Total reconnection attempts */
+  reconnectAttempts: number
+  /** Successful reconnections */
+  reconnectSuccesses: number
+}
+
+// ============================================================================
+// Utilities
+// ============================================================================
+
+/**
+ * Generate a unique ID
+ */
+function generateId(prefix: string): string {
+  return `${prefix}-${Date.now()}-${Math.random().toString(36).substr(2, 9)}`
+}
+
+/**
+ * Filter function for matching change events
+ */
+export type ChangeFilter = (change: ChangeEvent, subscription: Subscription) => boolean
+
+/**
+ * Event filter configuration
+ */
+export interface EventFilterConfig {
+  /** Tables to include (if empty, all tables) */
+  tables?: string[]
+  /** Operations to include (if empty, all operations) */
+  operations?: CDCEventType[]
+  /** Custom filter function */
+  filter?: ChangeFilter
+}
+
+/**
+ * Pending reconnect state
+ */
+interface PendingReconnectState {
+  /** Buffered changes during disconnection */
+  bufferedChanges: WSMessage[]
+  /** Subscription IDs that were active */
+  subscriptions: Set<string>
+}
+
+/**
+ * CDC WebSocket Handler
+ *
+ * Manages WebSocket connections for CDC streaming with support for:
+ * - Multiple subscriptions per connection
+ * - Heartbeat-based health monitoring
+ * - Reconnection with subscription restoration
+ * - Event filtering by table and operation
+ * - Comprehensive metrics tracking
+ * - Improved error handling and recovery
+ */
+export class CDCWebSocketHandler {
+  private state: DurableObjectState
+  private executor: QueryExecutor
+  private cdcManager: CDCManager
+  private config: Required<CDCWebSocketConfig>
+  private connections: Map<string, ConnectionState> = new Map()
+  private wsToConnection: Map<WebSocket, string> = new Map()
+  private timerManager: TimerManager
+  /** Pending reconnection state - kept separate from active connections */
+  private pendingReconnect: Map<string, PendingReconnectState> = new Map()
+  private version: string = '1.0.0'
+  private logger: ILogger
+  private metrics: CDCWebSocketMetrics
+
+  constructor(
+    state: DurableObjectState,
+    executor: QueryExecutor,
+    cdcManager?: CDCManager,
+    config?: CDCWebSocketConfig,
+    logger?: ILogger
+  ) {
+    this.state = state
+    this.executor = executor
+    this.config = { ...DEFAULT_CDC_CONFIG, ...config }
+
+    // Initialize logger
+    this.logger = (logger ?? createLogger({ level: LogLevel.INFO })).child({ component: 'CDCWebSocketHandler' })
+
+    // Initialize timer manager
+    this.timerManager = new TimerManager(this.logger)
+
+    // Initialize metrics
+    this.metrics = {
+      connectionsTotal: 0,
+      connectionsActive: 0,
+      messagesReceived: 0,
+      messagesSent: 0,
+      subscriptionsCreated: 0,
+      subscriptionsRemoved: 0,
+      errorsTotal: 0,
+      errorsByCode: {},
+      heartbeatTimeouts: 0,
+      reconnectAttempts: 0,
+      reconnectSuccesses: 0,
+    }
+
+    // Create a broadcaster that sends to specific connections
+    const broadcaster: Broadcaster = {
+      broadcast: (message: WSMessage, filter?: (ws: WebSocket) => boolean) => {
+        for (const connState of this.connections.values()) {
+          if (connState.ws.readyState !== WS_OPEN) continue
+          if (filter && !filter(connState.ws)) continue
+          this.sendMessage(connState.ws, message)
+        }
+      },
+    }
+
+    this.cdcManager = cdcManager ?? new CDCManager(broadcaster)
+
+    this.logger.debug('CDCWebSocketHandler initialized', {
+      heartbeatInterval: this.config.heartbeatInterval,
+      heartbeatTimeout: this.config.heartbeatTimeout,
+      maxSubscriptions: this.config.maxSubscriptions,
+    })
+  }
+
+  /**
+   * Handle WebSocket upgrade request
+   */
+  handleUpgrade(request: Request, webSocketPair: { 0: WebSocket; 1: WebSocket } | null): Response {
+    const upgradeHeader = request.headers.get('Upgrade')
+
+    if (upgradeHeader !== 'websocket' || !webSocketPair) {
+      this.logger.warn('Invalid WebSocket upgrade request', {
+        upgradeHeader,
+        hasPair: webSocketPair !== null,
+      })
+      return new Response('Expected WebSocket upgrade', { status: 400 })
+    }
+
+    const client = webSocketPair[0]
+    const server = webSocketPair[1]
+
+    // Accept the WebSocket with hibernation
+    this.state.acceptWebSocket(server)
+
+    // Create connection state
+    const connectionId = generateId('conn')
+    const now = Date.now()
+    const connState: ConnectionState = {
+      connectionId,
+      ws: server,
+      lifecycle: ConnectionLifecycle.CONNECTING,
+      lastHeartbeat: now,
+      heartbeatSeq: 0,
+      subscriptions: new Set(),
+      bufferedChanges: [],
+      activeOperations: 0,
+      createdAt: now,
+      messagesReceived: 0,
+      messagesSent: 0,
+    }
+
+    this.connections.set(connectionId, connState)
+    this.wsToConnection.set(server, connectionId)
+
+    // Update metrics
+    this.metrics.connectionsTotal++
+    this.metrics.connectionsActive++
+
+    // Start heartbeat for this connection
+    this.startHeartbeat(connectionId)
+
+    // Transition to active state
+    connState.lifecycle = ConnectionLifecycle.ACTIVE
+
+    // Send welcome message
+    this.sendMessage(server, {
+      type: 'welcome',
+      id: generateId('msg'),
+      payload: {
+        connectionId,
+        timestamp: now,
+        heartbeatInterval: this.config.heartbeatInterval,
+        version: this.version,
+      } as WelcomePayload,
+    })
+
+    this.logger.info('WebSocket connection established', { connectionId })
+
+    return new Response(null, {
+      status: 101,
+      webSocket: client,
+    })
+  }
+
+  /**
+   * Handle incoming WebSocket message
+   */
+  async handleMessage(ws: WebSocket, rawMessage: string | ArrayBuffer): Promise<void> {
+    const messageStr = typeof rawMessage === 'string'
+      ? rawMessage
+      : new TextDecoder().decode(rawMessage)
+
+    // Update last activity timestamp for heartbeat tracking
+    // Any message activity keeps the connection alive
+    const connectionId = this.wsToConnection.get(ws)
+    const connState = connectionId ? this.connections.get(connectionId) : undefined
+
+    if (connState) {
+      connState.lastHeartbeat = Date.now()
+      connState.messagesReceived++
+      // Track that we're processing a message (prevents heartbeat timeout during long operations)
+      connState.activeOperations++
+    }
+
+    // Update global metrics
+    this.metrics.messagesReceived++
+
+    try {
+      const message = parseWSMessage(messageStr)
+
+      this.logger.debug('Message received', {
+        connectionId,
+        type: message.type,
+        id: message.id,
+      })
+
+      switch (message.type) {
+        case 'ping':
+          this.sendMessage(ws, {
+            type: 'pong',
+            id: message.id,
+          })
+          break
+
+        case 'heartbeat':
+          this.handleHeartbeat(ws, message)
+          break
+
+        case 'query':
+          await this.handleQuery(ws, message)
+          break
+
+        case 'subscribe':
+          await this.handleSubscribe(ws, message)
+          break
+
+        case 'unsubscribe':
+          await this.handleUnsubscribe(ws, message)
+          break
+
+        case 'reconnect':
+          await this.handleReconnect(ws, message)
+          break
+
+        default:
+          this.sendError(ws, message.id, CDCErrorCodes.UNKNOWN_TYPE, `Unknown message type: ${message.type}`)
+      }
+    } catch (error) {
+      const errorMessage = error instanceof Error ? error.message : 'Unknown error'
+      this.logger.error('Failed to process message', {
+        connectionId,
+        error: errorMessage,
+      })
+      this.sendError(ws, 'unknown', CDCErrorCodes.PARSE_ERROR, errorMessage)
+    } finally {
+      // Decrement active operations count when done processing
+      if (connState) {
+        connState.activeOperations--
+        // Update heartbeat timestamp after operation completes
+        connState.lastHeartbeat = Date.now()
+      }
+    }
+  }
+
+  /**
+   * Handle heartbeat message
+   */
+  private handleHeartbeat(ws: WebSocket, message: WSMessage): void {
+    const connectionId = this.wsToConnection.get(ws)
+    if (!connectionId) {
+      this.logger.warn('Heartbeat received for unregistered WebSocket')
+      return
+    }
+
+    const connState = this.connections.get(connectionId)
+    if (!connState) {
+      this.logger.warn('Heartbeat received for missing connection state', { connectionId })
+      return
+    }
+
+    // Update last heartbeat time
+    const now = Date.now()
+    connState.lastHeartbeat = now
+    connState.heartbeatSeq++
+
+    // Send heartbeat acknowledgment
+    this.sendMessage(ws, {
+      type: 'heartbeat_ack',
+      id: message.id,
+      payload: {
+        timestamp: now,
+        seq: connState.heartbeatSeq,
+      } as HeartbeatPayload,
+    })
+
+    this.logger.debug('Heartbeat acknowledged', {
+      connectionId,
+      seq: connState.heartbeatSeq,
+    })
+  }
+
+  /**
+   * Handle query message
+   */
+  private async handleQuery(ws: WebSocket, message: WSMessage): Promise<void> {
+    const connectionId = this.wsToConnection.get(ws)
+
+    try {
+      const payload = message.payload as { sql?: string; params?: unknown[] }
+
+      if (!payload?.sql) {
+        this.sendError(ws, message.id, CDCErrorCodes.INVALID_REQUEST, 'Missing sql in payload')
+        return
+      }
+
+      this.logger.debug('Executing query', {
+        connectionId,
+        messageId: message.id,
+        sqlLength: payload.sql.length,
+      })
+
+      const result = await this.executor.executeQuery({
+        sql: payload.sql,
+        params: payload.params as QueryParam[] | undefined,
+      })
+
+      this.sendMessage(ws, {
+        type: 'result',
+        id: message.id,
+        payload: result,
+      })
+
+      this.logger.debug('Query completed', {
+        connectionId,
+        messageId: message.id,
+        rowCount: result.rowCount,
+        durationMs: result.durationMs,
+      })
+    } catch (error) {
+      const errorMessage = error instanceof Error ? error.message : 'Query failed'
+      this.logger.error('Query execution failed', {
+        connectionId,
+        messageId: message.id,
+        error: errorMessage,
+      })
+      this.sendError(ws, message.id, CDCErrorCodes.QUERY_ERROR, errorMessage)
+    }
+  }
+
+  /**
+   * Handle subscribe message
+   */
+  private async handleSubscribe(ws: WebSocket, message: WSMessage): Promise<void> {
+    const connectionId = this.wsToConnection.get(ws)
+    if (!connectionId) {
+      this.sendError(ws, message.id, CDCErrorCodes.NO_CONNECTION, 'WebSocket not registered')
+      return
+    }
+
+    const connState = this.connections.get(connectionId)
+    if (!connState) {
+      this.sendError(ws, message.id, CDCErrorCodes.NO_CONNECTION, 'Connection state not found')
+      return
+    }
+
+    const payload = message.payload as SubscribePayload
+
+    if (!payload?.table) {
+      this.sendError(ws, message.id, CDCErrorCodes.INVALID_REQUEST, 'Missing table in payload')
+      return
+    }
+
+    // Check max subscriptions limit
+    if (connState.subscriptions.size >= this.config.maxSubscriptions) {
+      this.logger.warn('Subscription limit reached', {
+        connectionId,
+        currentCount: connState.subscriptions.size,
+        maxSubscriptions: this.config.maxSubscriptions,
+      })
+      this.sendError(ws, message.id, CDCErrorCodes.LIMIT_EXCEEDED, `Max subscriptions (${this.config.maxSubscriptions}) reached`)
+      return
+    }
+
+    // Create subscription
+    const options: SubscribeOptions = {
+      table: payload.table,
+      events: payload.events,
+      filter: payload.filter,
+    }
+
+    const subscription = this.cdcManager.subscribe(ws, options)
+    connState.subscriptions.add(subscription.id)
+
+    // Update metrics
+    this.metrics.subscriptionsCreated++
+
+    // Send confirmation
+    this.sendMessage(ws, {
+      type: 'subscribed',
+      id: message.id,
+      payload: {
+        subscriptionId: subscription.id,
+        table: subscription.table,
+        events: subscription.events,
+        filter: subscription.filter,
+      } as SubscribedPayload,
+    })
+
+    this.logger.info('Subscription created', {
+      connectionId,
+      subscriptionId: subscription.id,
+      table: subscription.table,
+      events: subscription.events,
+    })
+  }
+
+  /**
+   * Handle unsubscribe message
+   */
+  private async handleUnsubscribe(ws: WebSocket, message: WSMessage): Promise<void> {
+    const connectionId = this.wsToConnection.get(ws)
+    if (!connectionId) {
+      this.sendError(ws, message.id, CDCErrorCodes.NO_CONNECTION, 'WebSocket not registered')
+      return
+    }
+
+    const connState = this.connections.get(connectionId)
+    if (!connState) {
+      this.sendError(ws, message.id, CDCErrorCodes.NO_CONNECTION, 'Connection state not found')
+      return
+    }
+
+    const payload = message.payload as UnsubscribePayload
+
+    if (!payload?.subscriptionId) {
+      this.sendError(ws, message.id, CDCErrorCodes.INVALID_REQUEST, 'Missing subscriptionId in payload')
+      return
+    }
+
+    // Check if this connection owns the subscription
+    if (!connState.subscriptions.has(payload.subscriptionId)) {
+      this.logger.warn('Unsubscribe attempted for unknown subscription', {
+        connectionId,
+        subscriptionId: payload.subscriptionId,
+      })
+      this.sendError(ws, message.id, CDCErrorCodes.NOT_FOUND, 'Subscription not found for this connection')
+      return
+    }
+
+    // Remove subscription
+    const removed = this.cdcManager.unsubscribe(payload.subscriptionId)
+    if (removed) {
+      connState.subscriptions.delete(payload.subscriptionId)
+      this.metrics.subscriptionsRemoved++
+    }
+
+    // Send confirmation
+    this.sendMessage(ws, {
+      type: 'unsubscribed',
+      id: message.id,
+      payload: {
+        subscriptionId: payload.subscriptionId,
+      } as UnsubscribedPayload,
+    })
+
+    this.logger.info('Subscription removed', {
+      connectionId,
+      subscriptionId: payload.subscriptionId,
+    })
+  }
+
+  /**
+   * Handle reconnect message
+   */
+  private async handleReconnect(ws: WebSocket, message: WSMessage): Promise<void> {
+    const payload = message.payload as ReconnectPayload
+
+    if (!payload?.connectionId) {
+      this.sendError(ws, message.id, CDCErrorCodes.INVALID_REQUEST, 'Missing connectionId in payload')
+      return
+    }
+
+    const newConnectionId = this.wsToConnection.get(ws)
+    if (!newConnectionId) {
+      this.sendError(ws, message.id, CDCErrorCodes.NO_CONNECTION, 'WebSocket not registered')
+      return
+    }
+
+    const newConnState = this.connections.get(newConnectionId)
+    if (!newConnState) {
+      this.sendError(ws, message.id, CDCErrorCodes.NO_CONNECTION, 'Connection state not found')
+      return
+    }
+
+    // Update metrics
+    this.metrics.reconnectAttempts++
+
+    this.logger.info('Reconnection attempt', {
+      newConnectionId,
+      oldConnectionId: payload.connectionId,
+      subscriptionCount: payload.subscriptionIds?.length ?? 0,
+    })
+
+    // Check if old connection has pending reconnect state (buffered changes)
+    const pendingState = this.pendingReconnect.get(payload.connectionId)
+
+    // Mark as reconnecting
+    newConnState.lifecycle = ConnectionLifecycle.RECONNECTING
+
+    // Restore subscriptions if provided
+    const restoredSubscriptions: string[] = []
+    if (payload.subscriptionIds && payload.subscriptionIds.length > 0) {
+      for (const subId of payload.subscriptionIds) {
+        const subscription = this.cdcManager.getSubscription(subId)
+        if (subscription) {
+          // Re-subscribe with same settings
+          const newSub = this.cdcManager.subscribe(ws, {
+            table: subscription.table,
+            events: subscription.events,
+            filter: subscription.filter,
+          })
+          newConnState.subscriptions.add(newSub.id)
+          restoredSubscriptions.push(newSub.id)
+          this.metrics.subscriptionsCreated++
+        }
+      }
+    }
+
+    // Send any buffered changes from pending reconnect state
+    if (pendingState && pendingState.bufferedChanges.length > 0) {
+      this.logger.debug('Delivering buffered changes', {
+        connectionId: newConnectionId,
+        bufferedCount: pendingState.bufferedChanges.length,
+      })
+      for (const bufferedMessage of pendingState.bufferedChanges) {
+        this.sendMessage(ws, bufferedMessage)
+      }
+      pendingState.bufferedChanges = []
+    }
+
+    // Clean up the pending reconnect state if it exists
+    if (pendingState) {
+      this.timerManager.stopCleanupTimer(payload.connectionId)
+      this.pendingReconnect.delete(payload.connectionId)
+    }
+
+    // Transition to active state
+    newConnState.lifecycle = ConnectionLifecycle.ACTIVE
+
+    // Update metrics for successful reconnection
+    this.metrics.reconnectSuccesses++
+
+    // Send welcome with restored info
+    this.sendMessage(ws, {
+      type: 'welcome',
+      id: message.id,
+      payload: {
+        connectionId: newConnectionId,
+        timestamp: Date.now(),
+        heartbeatInterval: this.config.heartbeatInterval,
+        version: this.version,
+        restoredSubscriptions,
+      } as WelcomePayload & { restoredSubscriptions: string[] },
+    })
+
+    this.logger.info('Reconnection successful', {
+      connectionId: newConnectionId,
+      restoredSubscriptions: restoredSubscriptions.length,
+    })
+  }
+
+  /**
+   * Handle WebSocket close
+   */
+  handleClose(ws: WebSocket, code: number, reason: string): void {
+    const connectionId = this.wsToConnection.get(ws)
+    if (!connectionId) return
+
+    const connState = this.connections.get(connectionId)
+    if (connState) {
+      // Transition to closing state
+      connState.lifecycle = ConnectionLifecycle.CLOSING
+
+      // Stop heartbeat timer FIRST to prevent any further timer callbacks
+      this.timerManager.stopHeartbeat(connectionId)
+
+      // Track subscription count before cleanup for metrics
+      const subscriptionCount = connState.subscriptions.size
+
+      // Clean up subscriptions from CDCManager
+      this.cdcManager.unsubscribeAll(ws)
+
+      // Clear the connection's subscription set
+      connState.subscriptions.clear()
+
+      // Update metrics
+      this.metrics.subscriptionsRemoved += subscriptionCount
+      this.metrics.connectionsActive--
+
+      // Store state for potential reconnection (buffered changes and subscription info)
+      // This is kept separate from active connections
+      this.pendingReconnect.set(connectionId, {
+        bufferedChanges: connState.bufferedChanges,
+        subscriptions: new Set(), // Already cleared, but could store subscription metadata here
+      })
+
+      // Start cleanup timer for pending reconnect state
+      const cleanupDelay = this.config.reconnectDelay * this.config.maxReconnectAttempts
+      this.timerManager.startCleanupTimer(connectionId, cleanupDelay, () => {
+        this.pendingReconnect.delete(connectionId)
+        this.logger.debug('Pending reconnect state cleaned up', { connectionId })
+      })
+
+      // Transition to closed state
+      connState.lifecycle = ConnectionLifecycle.CLOSED
+
+      // Remove from active connections immediately
+      this.connections.delete(connectionId)
+    }
+
+    this.wsToConnection.delete(ws)
+    this.logger.info('WebSocket closed', { connectionId, code, reason })
+  }
+
+  /**
+   * Handle WebSocket error
+   */
+  handleError(ws: WebSocket, error: Error): void {
+    const connectionId = this.wsToConnection.get(ws)
+
+    this.logger.error('WebSocket error', {
+      connectionId,
+      error: error.message,
+      stack: error.stack,
+    })
+
+    // Update metrics
+    this.metrics.errorsTotal++
+    this.metrics.errorsByCode[CDCErrorCodes.INTERNAL_ERROR] =
+      (this.metrics.errorsByCode[CDCErrorCodes.INTERNAL_ERROR] || 0) + 1
+
+    // Update connection state
+    const connState = connectionId ? this.connections.get(connectionId) : undefined
+    if (connState) {
+      connState.lastError = error.message
+    }
+
+    if (connectionId) {
+      this.timerManager.stopHeartbeat(connectionId)
+    }
+
+    try {
+      ws.close(1011, 'Internal error')
+    } catch {
+      // WebSocket might already be closed
+    }
+  }
+
+  /**
+   * Broadcast a change event to all matching subscribers
+   */
+  broadcastChange(change: ChangeEvent): void {
+    this.cdcManager.broadcastChange(change)
+  }
+
+  /**
+   * Broadcast a change event with filtering
+   */
+  broadcastChangeWithFilter(change: ChangeEvent, filterConfig?: EventFilterConfig): void {
+    // Check table filter
+    if (filterConfig?.tables && filterConfig.tables.length > 0) {
+      if (!filterConfig.tables.includes(change.table)) {
+        return
+      }
+    }
+
+    // Check operation filter
+    if (filterConfig?.operations && filterConfig.operations.length > 0) {
+      if (!filterConfig.operations.includes(change.operation)) {
+        return
+      }
+    }
+
+    this.cdcManager.broadcastChange(change)
+  }
+
+  /**
+   * Get connected WebSocket count
+   */
+  getConnectedCount(): number {
+    return this.connections.size
+  }
+
+  /**
+   * Get total subscription count
+   */
+  getSubscriptionCount(): number {
+    return this.cdcManager.getSubscriptionCount()
+  }
+
+  /**
+   * Get subscription count for a table
+   */
+  getTableSubscriberCount(table: string): number {
+    return this.cdcManager.getTableSubscriberCount(table)
+  }
+
+  /**
+   * Get subscriptions for a connection
+   */
+  getConnectionSubscriptions(connectionId: string): Subscription[] {
+    const connState = this.connections.get(connectionId)
+    if (!connState) return []
+
+    return Array.from(connState.subscriptions)
+      .map(id => this.cdcManager.getSubscription(id))
+      .filter((s): s is Subscription => s !== undefined)
+  }
+
+  /**
+   * Get connection info
+   */
+  getConnectionInfo(connectionId: string): { subscriptionCount: number; lastHeartbeat: number } | null {
+    const connState = this.connections.get(connectionId)
+    if (!connState) return null
+
+    return {
+      subscriptionCount: connState.subscriptions.size,
+      lastHeartbeat: connState.lastHeartbeat,
+    }
+  }
+
+  /**
+   * Start heartbeat timer for a connection
+   */
+  private startHeartbeat(connectionId: string): void {
+    this.timerManager.startHeartbeat(connectionId, this.config.heartbeatInterval, () => {
+      const connState = this.connections.get(connectionId)
+      if (!connState || connState.ws.readyState !== WS_OPEN) {
+        this.timerManager.stopHeartbeat(connectionId)
+        return
+      }
+
+      // Skip heartbeat timeout check if there are active operations in progress
+      // This prevents closing the connection during long-running queries
+      if (connState.activeOperations > 0) {
+        // Still send heartbeat but don't check timeout
+        connState.heartbeatSeq++
+        this.sendMessage(connState.ws, {
+          type: 'heartbeat',
+          id: generateId('hb'),
+          payload: {
+            timestamp: Date.now(),
+            seq: connState.heartbeatSeq,
+          } as HeartbeatPayload,
+        })
+        this.logger.debug('Heartbeat sent (skipped timeout check due to active operations)', {
+          connectionId,
+          activeOperations: connState.activeOperations,
+        })
+        return
+      }
+
+      // Check if last heartbeat was too long ago
+      const timeSinceLastHeartbeat = Date.now() - connState.lastHeartbeat
+      if (timeSinceLastHeartbeat > this.config.heartbeatInterval + this.config.heartbeatTimeout) {
+        this.logger.warn('Connection heartbeat timeout', {
+          connectionId,
+          timeSinceLastHeartbeat,
+          threshold: this.config.heartbeatInterval + this.config.heartbeatTimeout,
+        })
+
+        // Update metrics
+        this.metrics.heartbeatTimeouts++
+
+        try {
+          connState.ws.close(1000, 'Heartbeat timeout')
+        } catch {
+          // Ignore errors on close
+        }
+        this.timerManager.stopHeartbeat(connectionId)
+        return
+      }
+
+      // Send heartbeat
+      connState.heartbeatSeq++
+      this.sendMessage(connState.ws, {
+        type: 'heartbeat',
+        id: generateId('hb'),
+        payload: {
+          timestamp: Date.now(),
+          seq: connState.heartbeatSeq,
+        } as HeartbeatPayload,
+      })
+    })
+  }
+
+  /**
+   * Send a message to a WebSocket
+   */
+  private sendMessage(ws: WebSocket, message: WSMessage): void {
+    if (ws.readyState !== WS_OPEN) return
+
+    try {
+      ws.send(serializeWSMessage(message))
+
+      // Update metrics
+      this.metrics.messagesSent++
+
+      // Update connection-specific metrics
+      const connectionId = this.wsToConnection.get(ws)
+      if (connectionId) {
+        const connState = this.connections.get(connectionId)
+        if (connState) {
+          connState.messagesSent++
+        }
+      }
+    } catch (error) {
+      const errorMessage = error instanceof Error ? error.message : 'Unknown error'
+      this.logger.error('Failed to send message', {
+        messageType: message.type,
+        error: errorMessage,
+      })
+
+      // Update error metrics
+      this.metrics.errorsTotal++
+    }
+  }
+
+  /**
+   * Send an error message
+   */
+  private sendError(ws: WebSocket, id: string, code: string, message: string): void {
+    // Update error metrics
+    this.metrics.errorsTotal++
+    this.metrics.errorsByCode[code] = (this.metrics.errorsByCode[code] || 0) + 1
+
+    this.sendMessage(ws, {
+      type: 'error',
+      id,
+      payload: {
+        code,
+        message,
+      } as ErrorPayload,
+    })
+
+    this.logger.warn('Error sent to client', { id, code, message })
+  }
+
+  /**
+   * Get the CDC manager instance
+   */
+  getCDCManager(): CDCManager {
+    return this.cdcManager
+  }
+
+  /**
+   * Get configuration
+   */
+  getConfig(): Required<CDCWebSocketConfig> {
+    return { ...this.config }
+  }
+
+  /**
+   * Get current metrics
+   */
+  getMetrics(): CDCWebSocketMetrics {
+    return { ...this.metrics }
+  }
+
+  /**
+   * Get detailed connection info with metrics
+   */
+  getDetailedConnectionInfo(connectionId: string): {
+    lifecycle: ConnectionLifecycle
+    subscriptionCount: number
+    lastHeartbeat: number
+    createdAt: number
+    messagesReceived: number
+    messagesSent: number
+    lastError?: string
+  } | null {
+    const connState = this.connections.get(connectionId)
+    if (!connState) return null
+
+    // Build result object conditionally to avoid undefined values
+    const result: {
+      lifecycle: ConnectionLifecycle
+      subscriptionCount: number
+      lastHeartbeat: number
+      createdAt: number
+      messagesReceived: number
+      messagesSent: number
+      lastError?: string
+    } = {
+      lifecycle: connState.lifecycle,
+      subscriptionCount: connState.subscriptions.size,
+      lastHeartbeat: connState.lastHeartbeat,
+      createdAt: connState.createdAt,
+      messagesReceived: connState.messagesReceived,
+      messagesSent: connState.messagesSent,
+    }
+    if (connState.lastError !== undefined) {
+      result.lastError = connState.lastError
+    }
+    return result
+  }
+
+  /**
+   * Get all connection IDs
+   */
+  getConnectionIds(): string[] {
+    return Array.from(this.connections.keys())
+  }
+
+  /**
+   * Get timer statistics
+   */
+  getTimerStats(): { heartbeat: number; cleanup: number } {
+    return this.timerManager.getTimerCounts()
+  }
+
+  /**
+   * Clean up all resources (for graceful shutdown)
+   */
+  shutdown(): void {
+    this.logger.info('Shutting down CDCWebSocketHandler', {
+      activeConnections: this.connections.size,
+    })
+
+    // Clear all timers
+    this.timerManager.clearAll()
+
+    // Close all connections
+    for (const connState of this.connections.values()) {
+      try {
+        connState.ws.close(1001, 'Server shutting down')
+      } catch {
+        // Ignore errors
+      }
+    }
+
+    this.connections.clear()
+    this.wsToConnection.clear()
+    this.pendingReconnect.clear()
+
+    this.logger.info('CDCWebSocketHandler shutdown complete')
+  }
+}
+
+/**
+ * Factory function to create a CDCWebSocketHandler
+ */
+export function createCDCWebSocketHandler(
+  state: DurableObjectState,
+  executor: QueryExecutor,
+  cdcManager?: CDCManager,
+  config?: CDCWebSocketConfig,
+  logger?: ILogger
+): CDCWebSocketHandler {
+  return new CDCWebSocketHandler(state, executor, cdcManager, config, logger)
+}