@gravito/stream 2.0.1 → 2.1.0

package/dist/drivers/kafka/ErrorRecoveryManager.d.ts

@@ -0,0 +1,100 @@
+import { EventEmitter } from 'node:events';
+import type { ErrorCategory, ErrorRecoveryConfig, ErrorRecoveryState } from './types';
+/**
+ * 管理 Kafka 操作的錯誤恢復。
+ *
+ * 結合電路斷路器模式與指數退避，
+ * 在持續失敗時保護系統，並在恢復後自動復原。
+ *
+ * 電路狀態機:
+ * - CLOSED (正常) → OPEN (超過失敗閾值)
+ * - OPEN → HALF_OPEN (重置逾時後)
+ * - HALF_OPEN → CLOSED (探測成功)
+ * - HALF_OPEN → OPEN (探測失敗)
+ *
+ * 事件:
+ * - 'circuit:open' - 電路打開（失敗太多）
+ * - 'circuit:half-open' - 允許探測
+ * - 'circuit:closed' - 電路恢復
+ * - 'recovery:backoff' - 進入退避期
+ * - 'recovery:success' - 成功恢復
+ *
+ * @public
+ */
+export declare class ErrorRecoveryManager extends EventEmitter {
+    private readonly failureThreshold;
+    private readonly resetTimeoutMs;
+    private readonly halfOpenMaxRequests;
+    private readonly initialBackoffMs;
+    private readonly maxBackoffMs;
+    private readonly backoffMultiplier;
+    private readonly jitter;
+    private readonly maxRetries;
+    private circuitState;
+    private consecutiveFailures;
+    private lastFailureTime;
+    private totalRecoveries;
+    private halfOpenRequests;
+    private resetTimer;
+    constructor(config?: ErrorRecoveryConfig);
+    /**
+     * 記錄操作成功。
+     *
+     * 重置連續失敗計數，如果在 HALF_OPEN 狀態則轉換到 CLOSED。
+     */
+    recordSuccess(): void;
+    /**
+     * 記錄操作失敗。
+     *
+     * 增加失敗計數，在 CLOSED 狀態超過閾值時打開電路，
+     * 在 HALF_OPEN 狀態失敗時重新打開電路。
+     *
+     * @param error - 失敗的錯誤物件
+     * @param category - 錯誤分類（可選）。如果提供且為非 transient 類別，
+     *                   則不影響電路斷路器狀態
+     */
+    recordFailure(error: Error, category?: ErrorCategory): void;
+    /**
+     * 檢查是否可以繼續操作。
+     *
+     * - CLOSED: 總是允許
+     * - OPEN: 不允許
+     * - HALF_OPEN: 限制探測請求數量
+     */
+    canProceed(): boolean;
+    /**
+     * 計算當前退避延遲。
+     *
+     * 使用指數退避: delay = min(initial * multiplier^attempt, maxBackoff)
+     * 抖動: delay * (0.5 + random * 0.5)
+     */
+    getBackoffDelay(): number;
+    /**
+     * 等待退避期間。
+     */
+    waitForBackoff(): Promise<void>;
+    /**
+     * 返回當前錯誤恢復狀態快照（不可變）。
+     */
+    getState(): ErrorRecoveryState;
+    /**
+     * 強制重置為 CLOSED 狀態。
+     */
+    reset(): void;
+    /**
+     * 清理所有計時器。
+     */
+    destroy(): void;
+    /**
+     * 檢查是否已達最大重試次數。
+     */
+    hasExceededMaxRetries(): boolean;
+    /**
+     * 內部：執行狀態轉換並發射事件。
+     */
+    private transitionTo;
+    /**
+     * 內部：排程從 OPEN 到 HALF_OPEN 的轉換。
+     */
+    private scheduleHalfOpen;
+}

package/dist/drivers/kafka/HeartbeatManager.d.ts

@@ -0,0 +1,57 @@
+import { EventEmitter } from 'node:events';
+import type { HeartbeatConfig, HeartbeatStatus } from './types';
+/**
+ * 管理 Kafka 消費者的心跳偵測。
+ *
+ * 定期檢查消費者是否活躍，如果連續遺漏心跳達到閾值，
+ * 則發出 'stale' 事件通知上層元件。
+ *
+ * 事件:
+ * - 'heartbeat': 每次心跳檢查時發出
+ * - 'stale': 當遺漏計數達到 maxMissed 時發出
+ *
+ * @public
+ */
+export declare class HeartbeatManager extends EventEmitter {
+    private readonly interval;
+    private readonly sessionTimeout;
+    private readonly maxMissed;
+    private consumerId;
+    private queues;
+    private lastHeartbeat;
+    private missedCount;
+    private startTime;
+    private running;
+    private checkTimer;
+    constructor(config?: HeartbeatConfig);
+    /**
+     * 開始心跳迴圈。
+     *
+     * 冪等操作：如果已經在執行中，不會重複啟動。
+     */
+    start(consumerId: string, queues: string[]): Promise<void>;
+    /**
+     * 停止心跳迴圈並清理計時器。
+     *
+     * 冪等操作：重複呼叫不會出錯。
+     */
+    stop(): Promise<void>;
+    /**
+     * 手動心跳（重置遺漏計數）。
+     *
+     * 由外部元件在成功處理訊息後呼叫。
+     */
+    beat(): void;
+    /**
+     * 返回當前心跳狀態快照。
+     */
+    getStatus(): HeartbeatStatus;
+    /**
+     * 註冊心跳狀態變更監聽器。
+     */
+    onStateChange(listener: (status: HeartbeatStatus) => void): void;
+    /**
+     * 內部：定期檢查心跳狀態。
+     */
+    private check;
+}

package/dist/drivers/kafka/KafkaDriver.d.ts

@@ -0,0 +1,138 @@
+import type { JobPushOptions, QueueStats, SerializedJob, TopicOptions } from '../../types';
+import type { QueueDriver } from '../QueueDriver';
+import type { KafkaDriverFullConfig, KafkaDriverMetrics, PerformanceSnapshot, SerializationErrorRecord, SubscribeOptions } from './types';
+/**
+ * Kafka-native queue driver implementing the QueueDriver interface.
+ *
+ * Bridges Kafka's push model with QueueDriver's pull model using:
+ * - MessageBuffer (FIFO buffering from Kafka consumer)
+ * - OffsetTracker (at-least-once semantic with continuous-ack)
+ * - KafkaNotifier (ReactiveStrategy integration)
+ *
+ * @public
+ */
+export declare class KafkaDriver implements QueueDriver {
+    private producer;
+    private consumer;
+    private admin;
+    private readonly buffer;
+    private readonly offsetTracker;
+    private readonly notifier;
+    private readonly lifecycleManager;
+    private readonly backpressure;
+    private readonly heartbeatManager;
+    private readonly metrics;
+    private readonly errorRecovery;
+    private readonly rebalanceHandler;
+    private readonly batchProcessor;
+    private readonly performanceMonitor;
+    private readonly errorCategorizer;
+    private readonly subscribedTopics;
+    private readonly knownQueues;
+    private readonly dlqBuffer;
+    private readonly messageIdToMeta;
+    private consumerRunning;
+    private offsetCommitTimer;
+    private subscriptionCallbacks;
+    private readonly topicToMessageIds;
+    private readonly serializationCache;
+    private readonly serializationDlq;
+    private readonly partitionSerializationErrors;
+    private readonly callbackFailureCounts;
+    private dlqRetryTimer;
+    private readonly config;
+    constructor(config: KafkaDriverFullConfig);
+    private ensureProducer;
+    push(queue: string, job: SerializedJob, options?: JobPushOptions): Promise<void>;
+    /**
+     * Serialize a job with WeakMap caching.
+     * Avoids re-serializing the same object reference (e.g. retries).
+     */
+    private serializeJob;
+    pushMany(queue: string, jobs: SerializedJob[]): Promise<void>;
+    private handleIncomingMessage;
+    private ensureConsumer;
+    private ensureConsumerForTopic;
+    private restartConsumer;
+    private startConsumerLoop;
+    pop(queue: string): Promise<SerializedJob | null>;
+    popBlocking(queues: string | string[], timeout: number): Promise<SerializedJob | null>;
+    popMany(queue: string, count: number): Promise<SerializedJob[]>;
+    subscribe(queue: string, callback: (job: SerializedJob) => Promise<void>, options?: SubscribeOptions): Promise<void>;
+    /**
+     * Internal method to run the subscription message processing loop.
+     */
+    private runSubscription;
+    complete(_queue: string, job: SerializedJob): Promise<void>;
+    acknowledge(messageId: string): Promise<void>;
+    fail(queue: string, job: SerializedJob): Promise<void>;
+    private startOffsetCommitLoop;
+    private commitOffsets;
+    private ensureAdmin;
+    createTopic(topic: string, options?: TopicOptions): Promise<void>;
+    deleteTopic(topic: string): Promise<void>;
+    getQueues(): Promise<string[]>;
+    size(queue: string): Promise<number>;
+    stats(queue: string): Promise<QueueStats>;
+    /**
+     * Get full driver metrics snapshot.
+     */
+    getMetrics(): KafkaDriverMetrics;
+    /**
+     * Get aggregated performance snapshot.
+     */
+    getPerformanceSnapshot(): PerformanceSnapshot;
+    /**
+     * Get performance history.
+     */
+    getPerformanceHistory(count?: number): PerformanceSnapshot[];
+    /**
+     * Generate a performance report string.
+     */
+    getPerformanceReport(): string;
+    /**
+     * 取得序列化錯誤 DLQ 緩衝區的不可變副本。
+     */
+    getSerializationDlq(): readonly SerializationErrorRecord[];
+    /**
+     * 取得每個分區的序列化錯誤計數。
+     */
+    getPartitionSerializationErrors(): ReadonlyMap<string, number>;
+    /**
+     * 取得每個佇列的回呼連續失敗計數。
+     */
+    getCallbackFailureCounts(): ReadonlyMap<string, number>;
+    /**
+     * 取得 DLQ 緩衝區統計資訊。
+     */
+    getDlqStats(): {
+        totalBuffered: number;
+        perTopic: Record<string, number>;
+        retryEnabled: boolean;
+        retryIntervalMs: number;
+    };
+    /**
+     * 啟動 DLQ 重試迴圈，定期嘗試將緩衝區中的失敗訊息重新發送至 Kafka。
+     */
+    startDlqRetryLoop(): void;
+    /**
+     * 嘗試將所有緩衝的 DLQ 訊息重新發送至 Kafka。
+     * 成功發送的訊息會從緩衝區中移除。
+     */
+    flushDlqBuffer(): Promise<{
+        flushed: number;
+        remaining: number;
+    }>;
+    clear(queue: string): Promise<void>;
+    /**
+     * Remove message tracking from both primary and reverse indexes.
+     */
+    private removeMessageTracking;
+    enableNotifications(): Promise<void>;
+    disableNotifications(): Promise<void>;
+    onNotify(queues: string | string[], callback: (queue: string) => Promise<void>): Promise<void>;
+    getFailed(queue: string, start?: number, end?: number): Promise<SerializedJob[]>;
+    clearFailed(queue: string): Promise<void>;
+    retryFailed(queue: string, count?: number): Promise<number>;
+    disconnect(): Promise<void>;
+}

package/dist/drivers/kafka/KafkaMetrics.d.ts

@@ -0,0 +1,88 @@
+import type { KafkaDriverMetrics, MetricsConfig } from './types';
+/**
+ * Kafka driver metrics collector.
+ *
+ * Tracks throughput, latency, errors, buffer utilization, and rate limit statistics.
+ * Uses a circular buffer for latency histogram to prevent unbounded memory growth.
+ *
+ * Performance optimizations (Phase 6E-2):
+ * - Bucket counter throughput: O(buckets) snapshot instead of O(messages) timestamp filter
+ * - No per-message timestamp storage: constant memory for throughput tracking
+ * - recordMessage() hot path: O(1) bucket increment + circular buffer write
+ *
+ * @public
+ */
+export declare class KafkaMetrics {
+    private readonly enabled;
+    private readonly histogramSize;
+    private readonly latencyBuffer;
+    private latencyIndex;
+    private latencyCount;
+    private readonly queueBuckets;
+    private readonly queueCounts;
+    private readonly errorCounts;
+    private readonly rateLimitCounts;
+    private rateLimitTotalAllowed;
+    private rateLimitTotalDenied;
+    private readonly bufferSizes;
+    private bufferCapacity;
+    private totalProcessed;
+    private totalFailed;
+    private inFlight;
+    private readonly lagMap;
+    constructor(config?: MetricsConfig);
+    /**
+     * 記錄已處理訊息（含延遲）。
+     * Hot path: O(1) 桶遞增 + 圓形緩衝區寫入。
+     */
+    recordMessage(queue: string, latencyMs: number): void;
+    /**
+     * 記錄錯誤（按類型追蹤）。
+     */
+    recordError(type: 'serialization' | 'callback' | 'connection' | 'timeout'): void;
+    /**
+     * 記錄速率限制決定。
+     */
+    recordRateLimitHit(queue: string, allowed: boolean): void;
+    /**
+     * 更新緩衝區大小（由外部呼叫以追蹤利用率）。
+     */
+    updateBufferSize(queue: string, size: number, capacity: number): void;
+    /**
+     * 更新 consumer lag。
+     */
+    updateLag(topicPartition: string, lag: number): void;
+    /**
+     * 更新 in-flight 計數。
+     */
+    setInFlight(count: number): void;
+    /**
+     * 計算並返回當前指標快照（不可變）。
+     * 吞吐量計算: O(queues * BUCKET_COUNT) 取代 O(total_messages)。
+     */
+    getSnapshot(): KafkaDriverMetrics;
+    /**
+     * 清除所有計數器。
+     */
+    reset(): void;
+    /**
+     * 從圓形緩衝區取出有效延遲資料。
+     */
+    private getLatencyData;
+    /**
+     * 計算百分位數（輸入必須已排序）。
+     */
+    private calculatePercentile;
+    /**
+     * 遞增當前時間桶的計數。O(1) 操作。
+     *
+     * 桶結構: 固定 BUCKET_COUNT 個桶，每桶代表 BUCKET_DURATION_MS 的時間段。
+     * 當時間推進到新桶時，清零已過期的桶。
+     */
+    private incrementBucket;
+    /**
+     * 計算每佇列吞吐量（messages/second）。
+     * O(queues * BUCKET_COUNT) - 固定成本，不隨訊息數增長。
+     */
+    private calculateThroughput;
+}

package/dist/drivers/kafka/KafkaNotifier.d.ts

@@ -0,0 +1,54 @@
+import { EventEmitter } from 'node:events';
+/**
+ * Kafka 通知橋接器。
+ *
+ * 將 Kafka Consumer 的訊息到達事件轉換為
+ * QueueDriver.onNotify() 需要的通知回呼。
+ * 用於整合 ReactiveStrategy。
+ *
+ * @public
+ */
+export declare class KafkaNotifier extends EventEmitter {
+    private readonly callbacks;
+    private enabled;
+    /**
+     * 啟用通知。
+     *
+     * 允許 notify() 呼叫觸發已註冊的回呼。
+     */
+    enable(): void;
+    /**
+     * 停用通知。
+     *
+     * 呼叫 notify() 時將不觸發任何回呼。
+     */
+    disable(): void;
+    /**
+     * 是否已啟用。
+     *
+     * @returns 是否已啟用
+     */
+    isEnabled(): boolean;
+    /**
+     * 註冊通知回呼。
+     *
+     * @param queues 佇列名稱陣列
+     * @param callback 當訊息到達時呼叫的回呼函式
+     */
+    registerCallback(queues: string[], callback: (queue: string) => Promise<void>): void;
+    /**
+     * 觸發通知（由 Consumer 的 eachMessage 呼叫）。
+     *
+     * 執行已註冊的所有回呼，並發出 'notify' 事件。
+     * 如果回呼拋出錯誤，不會中斷其他回呼的執行。
+     *
+     * @param queue 佇列名稱
+     */
+    notify(queue: string): void;
+    /**
+     * 清除所有已註冊的回呼。
+     *
+     * 用於優雅關閉時調用。
+     */
+    clearCallbacks(): void;
+}

package/dist/drivers/kafka/MessageBuffer.d.ts

@@ -0,0 +1,71 @@
+import type { BufferedMessage } from './types';
+/**
+ * Kafka 訊息緩衝區。
+ *
+ * 橋接 Kafka 的 push 模型與 QueueDriver 的 pull（pop）模型。
+ * 每個 topic 維護獨立的 FIFO 緩衝區，支援容量限制和超時等待。
+ *
+ * @public
+ */
+export declare class MessageBuffer {
+    private readonly maxSize;
+    private readonly buffers;
+    private readonly waiters;
+    constructor(maxSize?: number);
+    /**
+     * 推入一條訊息到指定 topic 的緩衝區。
+     *
+     * @param topic 主題名稱
+     * @param message 要推入的訊息
+     * @returns 是否成功推入（false 表示緩衝區已滿）
+     */
+    enqueue(topic: string, message: BufferedMessage): boolean;
+    /**
+     * 從指定 topic 取出一條訊息（FIFO），立即返回或 null。
+     *
+     * @param topic 主題名稱
+     * @returns 取出的訊息或 null
+     */
+    dequeue(topic: string): BufferedMessage | null;
+    /**
+     * 等待直到有訊息或超時。
+     *
+     * @param topic 主題名稱
+     * @param timeoutMs 超時時間（毫秒）
+     * @returns 取出的訊息或 null
+     */
+    dequeueBlocking(topic: string, timeoutMs: number): Promise<BufferedMessage | null>;
+    /**
+     * 批次取出。
+     *
+     * @param topic 主題名稱
+     * @param count 最多取出的訊息數
+     * @returns 取出的訊息陣列（不足時回傳可用數量）
+     */
+    dequeueMany(topic: string, count: number): BufferedMessage[];
+    /**
+     * 取得指定 topic 的緩衝數量。
+     *
+     * @param topic 主題名稱
+     * @returns 緩衝區中的訊息數
+     */
+    size(topic: string): number;
+    /**
+     * 清空指定 topic 的緩衝區。
+     *
+     * @param topic 主題名稱
+     */
+    clear(topic: string): void;
+    /**
+     * 清空所有緩衝區並取消所有等待者。
+     *
+     * 用於優雅關閉時調用。
+     */
+    destroy(): void;
+    /**
+     * 喚醒指定 topic 的第一個等待者。
+     *
+     * @private
+     */
+    private notifyWaiters;
+}

package/dist/drivers/kafka/OffsetTracker.d.ts

@@ -0,0 +1,63 @@
+/**
+ * Kafka Offset 追蹤器。
+ *
+ * 追蹤每個 topic-partition 的已處理 offset，
+ * 支援手動 commit 和 at-least-once 語意。
+ *
+ * 使用「連續確認」演算法：
+ * - 只有當 offset 0, 1, 2 都已 resolve 時才 commit offset 3
+ * - 確保未來 consumer 重啟時不會跳過未處理的訊息
+ *
+ * @public
+ */
+export declare class OffsetTracker {
+    /** topic -> partition -> 最高已確認 offset */
+    private readonly committed;
+    /** topic -> partition -> 待確認 offset 集合 */
+    private readonly pending;
+    /**
+     * 標記一個 offset 為待處理。
+     *
+     * @param topic 主題名稱
+     * @param partition 分區編號
+     * @param offset Offset 值
+     */
+    track(topic: string, partition: number, offset: string): void;
+    /**
+     * 標記一個 offset 為已完成。
+     *
+     * @param topic 主題名稱
+     * @param partition 分區編號
+     * @param offset Offset 值
+     */
+    resolve(topic: string, partition: number, offset: string): void;
+    /**
+     * 取得可安全 commit 的 offset（連續已完成的最高值）。
+     *
+     * 使用連續確認演算法：
+     * 只回傳連續完成的 offset（即從 0 開始的連續序列）。
+     *
+     * @returns 可提交的 offset 陣列
+     */
+    getCommittableOffsets(): Array<{
+        topic: string;
+        partition: number;
+        offset: string;
+    }>;
+    /**
+     * 清除指定 topic 的追蹤資料。
+     *
+     * @param topic 主題名稱
+     */
+    clear(topic: string): void;
+    /**
+     * 取得統計資訊。
+     *
+     * @returns 統計物件
+     */
+    getStats(): {
+        tracked: number;
+        committed: number;
+        pending: number;
+    };
+}

package/dist/drivers/kafka/PerformanceMonitor.d.ts

@@ -0,0 +1,88 @@
+import { EventEmitter } from 'node:events';
+import type { BackpressureController } from './BackpressureController';
+import type { ConsumerLifecycleManager } from './ConsumerLifecycleManager';
+import type { ErrorRecoveryManager } from './ErrorRecoveryManager';
+import type { HeartbeatManager } from './HeartbeatManager';
+import type { KafkaMetrics } from './KafkaMetrics';
+import type { PerformanceConfig, PerformanceSnapshot } from './types';
+/**
+ * 效能監控元件。
+ *
+ * 定期收集所有子系統的指標，產生聚合快照，
+ * 並維護歷史記錄以供趨勢分析。
+ *
+ * 健康判定邏輯:
+ * - healthy: 電路 CLOSED、心跳正常、無背壓
+ * - degraded: 電路 HALF_OPEN 或背壓啟動 或 錯誤率 > 5%
+ * - unhealthy: 電路 OPEN 或心跳失敗 或消費者非 running
+ *
+ * 事件:
+ * - 'snapshot': 每次快照收集時發出
+ * - 'health:changed': 健康狀態變更時發出
+ *
+ * @public
+ */
+export declare class PerformanceMonitor extends EventEmitter {
+    private readonly snapshotIntervalMs;
+    private readonly historySize;
+    private readonly enabled;
+    private readonly history;
+    private lastHealth;
+    private timer;
+    private running;
+    private metricsRef;
+    private errorRecoveryRef;
+    private heartbeatRef;
+    private backpressureRef;
+    private lifecycleRef;
+    constructor(config?: PerformanceConfig);
+    /**
+     * 綁定監控目標元件。
+     */
+    bind(components: {
+        metrics: KafkaMetrics;
+        errorRecovery: ErrorRecoveryManager;
+        heartbeat: HeartbeatManager;
+        backpressure: BackpressureController;
+        lifecycle: ConsumerLifecycleManager;
+    }): void;
+    /**
+     * 開始定期快照收集。
+     */
+    start(): void;
+    /**
+     * 停止快照收集並清理計時器。
+     */
+    stop(): void;
+    /**
+     * 手動觸發一次快照收集。
+     */
+    collectSnapshot(): PerformanceSnapshot;
+    /**
+     * 取得最近 N 筆歷史快照（不可變副本）。
+     */
+    getHistory(count?: number): PerformanceSnapshot[];
+    /**
+     * 取得最新一筆快照。
+     */
+    getLatestSnapshot(): PerformanceSnapshot | null;
+    /**
+     * 產生文字報告摘要。
+     */
+    generateReport(): string;
+    /**
+     * 是否正在執行中。
+     */
+    isRunning(): boolean;
+    /**
+     * 清除歷史記錄並停止。
+     */
+    destroy(): void;
+    /**
+     * 內部：評估整體健康狀態。
+     *
+     * 當消費者尚未啟動（idle）時，心跳未活躍是預期的，不視為 unhealthy。
+     * 只有在消費者已啟動（running/restarting）的情況下，心跳死亡才算 unhealthy。
+     */
+    private evaluateHealth;
+}