/** * Connection Health Monitor for CDC * * Monitors connection health with: * - Latency tracking with percentile calculations * - Connection state monitoring * - Automatic health checks * - Health score calculation * - Metrics collection */ import { CDCLogger, defaultLogger } from './logger' /** * Health status levels */ export enum HealthStatus { HEALTHY = 'HEALTHY', DEGRADED = 'DEGRADED', UNHEALTHY = 'UNHEALTHY', UNKNOWN = 'UNKNOWN', } /** * Latency sample */ interface LatencySample { timestamp: number latencyMs: number } /** * Health check result */ export interface HealthCheckResult { /** Overall health status */ status: HealthStatus /** Health score from 0-100 */ score: number /** Whether connection is active */ connected: boolean /** Latency metrics */ latency: { /** Current latency (last sample) */ current: number /** Average latency */ average: number /** P50 latency */ p50: number /** P95 latency */ p95: number /** P99 latency */ p99: number /** Minimum latency */ min: number /** Maximum latency */ max: number } /** Connection metrics */ connection: { /** Uptime in milliseconds */ uptimeMs: number /** Number of reconnections */ reconnections: number /** Last event received timestamp */ lastEventAt?: Date | undefined /** Time since last event in ms */ timeSinceLastEventMs?: number | undefined } /** Throughput metrics */ throughput: { /** Events per second (recent) */ eventsPerSecond: number /** Total events received */ totalEvents: number /** Bytes received */ bytesReceived: number } /** Timestamp of this check */ timestamp: Date } /** * Health monitor configuration */ export interface HealthMonitorConfig { /** Interval for health checks (ms) (default: 5000) */ checkIntervalMs?: number /** Window size for latency samples (default: 100) */ sampleWindowSize?: number /** Threshold for degraded status (ms) (default: 500) */ degradedLatencyThresholdMs?: number /** Threshold for unhealthy status (ms) (default: 2000) */ unhealthyLatencyThresholdMs?: number /** Timeout for considering connection stale (ms) (default: 30000) */ staleConnectionThresholdMs?: number /** Callback when health status changes */ onHealthChange?: (result: HealthCheckResult) => void /** Logger instance */ logger?: CDCLogger } /** * Sorted array insert for latency percentile calculation */ function insertSorted(arr: number[], value: number): void { let left = 0 let right = arr.length while (left < right) { const mid = (left + right) >>> 1 if (arr[mid]! < value) { left = mid + 1 } else { right = mid } } arr.splice(left, 0, value) } /** * Connection Health Monitor */ export class HealthMonitor { private connected = false private connectedAt?: Date | undefined private lastEventAt?: Date | undefined private reconnections = 0 private totalEvents = 0 private bytesReceived = 0 private latencySamples: LatencySample[] = [] private sortedLatencies: number[] = [] private eventTimestamps: number[] = [] private checkTimer?: ReturnType | undefined private lastStatus: HealthStatus = HealthStatus.UNKNOWN private lastPingTime?: number | undefined private readonly config: Required> & { onHealthChange?: HealthMonitorConfig['onHealthChange'] logger: CDCLogger } constructor(config: HealthMonitorConfig = {}) { this.config = { checkIntervalMs: config.checkIntervalMs ?? 5000, sampleWindowSize: config.sampleWindowSize ?? 100, degradedLatencyThresholdMs: config.degradedLatencyThresholdMs ?? 500, unhealthyLatencyThresholdMs: config.unhealthyLatencyThresholdMs ?? 2000, staleConnectionThresholdMs: config.staleConnectionThresholdMs ?? 30000, onHealthChange: config.onHealthChange, logger: config.logger ?? defaultLogger, } } /** * Start health monitoring */ start(): void { this.stop() this.checkTimer = setInterval(() => { const result = this.getHealth() if (result.status !== this.lastStatus) { this.lastStatus = result.status this.config.onHealthChange?.(result) } }, this.config.checkIntervalMs) } /** * Stop health monitoring */ stop(): void { if (this.checkTimer) { clearInterval(this.checkTimer) this.checkTimer = undefined } } /** * Record connection established */ recordConnected(): void { this.connected = true this.connectedAt = new Date() this.config.logger.debug('Health monitor: connection established') } /** * Record connection lost */ recordDisconnected(): void { this.connected = false this.config.logger.debug('Health monitor: connection lost') } /** * Record reconnection */ recordReconnection(): void { this.reconnections++ this.connectedAt = new Date() this.config.logger.debug('Health monitor: reconnection', { data: { totalReconnections: this.reconnections }, }) } /** * Record event received */ recordEvent(bytesSize?: number): void { const now = Date.now() this.lastEventAt = new Date() this.totalEvents++ if (bytesSize) { this.bytesReceived += bytesSize } // Track for throughput calculation this.eventTimestamps.push(now) // Keep last 60 seconds of timestamps const cutoff = now - 60000 this.eventTimestamps = this.eventTimestamps.filter((t) => t > cutoff) } /** * Record latency sample (e.g., from ping/pong) */ recordLatency(latencyMs: number): void { const now = Date.now() // Add to samples this.latencySamples.push({ timestamp: now, latencyMs }) insertSorted(this.sortedLatencies, latencyMs) // Prune old samples if (this.latencySamples.length > this.config.sampleWindowSize) { const removed = this.latencySamples.shift() if (removed) { // Remove from sorted array const idx = this.sortedLatencies.indexOf(removed.latencyMs) if (idx !== -1) { this.sortedLatencies.splice(idx, 1) } } } this.config.logger.debug('Health monitor: latency recorded', { data: { latencyMs, samples: this.latencySamples.length }, }) } /** * Start a ping timer (call pongReceived when response comes back) */ pingStarted(): void { this.lastPingTime = Date.now() } /** * Record pong received and calculate latency */ pongReceived(): void { if (this.lastPingTime) { const latency = Date.now() - this.lastPingTime this.recordLatency(latency) this.lastPingTime = undefined } } /** * Get current health status */ getHealth(): HealthCheckResult { const now = Date.now() const latencyMetrics = this.calculateLatencyMetrics() const throughput = this.calculateThroughput() const timeSinceLastEvent = this.lastEventAt ? now - this.lastEventAt.getTime() : undefined // Calculate health score (0-100) let score = 100 // Deduct for latency issues if (latencyMetrics.average > this.config.unhealthyLatencyThresholdMs) { score -= 50 } else if (latencyMetrics.average > this.config.degradedLatencyThresholdMs) { score -= 25 } // Deduct for stale connection if (timeSinceLastEvent && timeSinceLastEvent > this.config.staleConnectionThresholdMs) { score -= 30 } // Deduct for disconnection if (!this.connected) { score -= 40 } // Deduct for high reconnection rate (more than 5 in last hour would be concerning) if (this.reconnections > 5) { score -= Math.min(20, this.reconnections * 2) } score = Math.max(0, score) // Determine status based on score thresholds // UNHEALTHY: score <= 50 OR disconnected // DEGRADED: score > 50 AND score < 80 // HEALTHY: score >= 80 let status: HealthStatus if (!this.connected) { status = HealthStatus.UNHEALTHY } else if (score >= 80) { status = HealthStatus.HEALTHY } else if (score > 50) { status = HealthStatus.DEGRADED } else { status = HealthStatus.UNHEALTHY } return { status, score, connected: this.connected, latency: latencyMetrics, connection: { uptimeMs: this.connectedAt ? now - this.connectedAt.getTime() : 0, reconnections: this.reconnections, lastEventAt: this.lastEventAt, timeSinceLastEventMs: timeSinceLastEvent, }, throughput, timestamp: new Date(), } } /** * Calculate latency metrics */ private calculateLatencyMetrics(): HealthCheckResult['latency'] { if (this.sortedLatencies.length === 0) { return { current: 0, average: 0, p50: 0, p95: 0, p99: 0, min: 0, max: 0, } } const sorted = this.sortedLatencies const sum = sorted.reduce((a, b) => a + b, 0) return { current: this.latencySamples[this.latencySamples.length - 1]?.latencyMs ?? 0, average: Math.round(sum / sorted.length), p50: this.getPercentile(sorted, 0.5), p95: this.getPercentile(sorted, 0.95), p99: this.getPercentile(sorted, 0.99), min: sorted[0] ?? 0, max: sorted[sorted.length - 1] ?? 0, } } /** * Calculate percentile value from sorted array * Uses floor index for P50 and ceiling index for high percentiles with small samples */ private getPercentile(sorted: number[], percentile: number): number { if (sorted.length === 0) return 0 if (sorted.length === 1) return sorted[0]! const n = sorted.length if (percentile === 0.5) { // P50: floor index for median const index = Math.floor((n - 1) * percentile) return sorted[index] ?? 0 } else { // P95/P99: floor for large samples, ceil for small samples const rawIndex = (n - 1) * percentile const index = n <= 10 ? Math.ceil(rawIndex) : Math.floor(rawIndex) return sorted[Math.min(index, n - 1)] ?? 0 } } /** * Calculate throughput metrics */ private calculateThroughput(): HealthCheckResult['throughput'] { const now = Date.now() // Use >= to include events exactly at the boundary const recentEvents = this.eventTimestamps.filter((t) => t >= now - 10000) const eventsPerSecond = recentEvents.length / 10 return { eventsPerSecond: Math.round(eventsPerSecond * 100) / 100, totalEvents: this.totalEvents, bytesReceived: this.bytesReceived, } } /** * Reset all metrics */ reset(): void { this.latencySamples = [] this.sortedLatencies = [] this.eventTimestamps = [] this.totalEvents = 0 this.bytesReceived = 0 this.reconnections = 0 this.lastEventAt = undefined this.connectedAt = undefined this.lastStatus = HealthStatus.UNKNOWN } /** * Cleanup */ destroy(): void { this.stop() } } /** * Create a health monitor instance */ export function createHealthMonitor(config?: HealthMonitorConfig): HealthMonitor { return new HealthMonitor(config) }