@gravito/stream 2.0.2 → 2.1.2

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

@@ -0,0 +1,80 @@
+import { EventEmitter } from 'node:events';
+import type { ConsumerLifecycleState, LifecycleEvent } from './types';
+/**
+ * Manages consumer lifecycle state transitions and events.
+ *
+ * State transitions:
+ * - idle → starting → running → stopping → stopped
+ * - running → restarting → running
+ * - any state → error
+ *
+ * Emits lifecycle events on state changes for coordination with other components.
+ *
+ * @public
+ */
+export declare class ConsumerLifecycleManager extends EventEmitter {
+    private currentState;
+    private previousState;
+    private lastTransitionTime;
+    private stateHistory;
+    /**
+     * Register a listener for lifecycle events.
+     * Event data: { state, previousState, timestamp, error? }
+     */
+    onStateChange(listener: (event: LifecycleEvent) => void): void;
+    /**
+     * Start the consumer (transition idle → starting → running).
+     */
+    start(): Promise<void>;
+    /**
+     * Restart the consumer (running → restarting → running).
+     */
+    restart(): Promise<void>;
+    /**
+     * Stop the consumer (running/starting → stopping → stopped).
+     */
+    stop(): Promise<void>;
+    /**
+     * Reset to idle state (for testing/reuse).
+     */
+    reset(): void;
+    /**
+     * Get current lifecycle state.
+     */
+    getState(): ConsumerLifecycleState;
+    /**
+     * Get previous lifecycle state.
+     */
+    getPreviousState(): ConsumerLifecycleState;
+    /**
+     * Get last state transition timestamp.
+     */
+    getLastTransitionTime(): number;
+    /**
+     * Get state transition history.
+     */
+    getStateHistory(): Array<{
+        state: ConsumerLifecycleState;
+        timestamp: number;
+    }>;
+    /**
+     * Check if consumer is in running state.
+     */
+    isRunning(): boolean;
+    /**
+     * Check if consumer is in error state.
+     */
+    isError(): boolean;
+    /**
+     * Check if consumer is stopped.
+     */
+    isStopped(): boolean;
+    /**
+     * Internal: transition to new state and emit event.
+     */
+    private transition;
+    /**
+     * Internal: transition to error state with error details.
+     */
+    private transitionError;
+}

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

@@ -0,0 +1,39 @@
+import type { ErrorCategory } from './types';
+/**
+ * 根據錯誤訊息與型別分類 Kafka 操作錯誤。
+ *
+ * 錯誤分類：
+ * - `transient`（影響電路斷路器）：連線失敗、逾時、網路錯誤
+ * - `serialization`（不影響電路）：JSON parse 失敗、序列化錯誤
+ * - `business_logic`（不影響電路）：回調拋出的一般錯誤
+ * - `permanent`（不影響電路）：其他永久性失敗
+ *
+ * 使用者應根據錯誤分類決定是否影響電路斷路器狀態。
+ * 只有 `transient` 錯誤才應遞增電路的失敗計數。
+ *
+ * @public
+ */
+export declare class ErrorCategorizer {
+    /**
+     * 將錯誤分類為標準分類之一。
+     *
+     * 分類規則（優先順序）：
+     * 1. `transient` - ECONNREFUSED, ETIMEDOUT, ECONNRESET, 網路相關
+     * 2. `serialization` - SyntaxError, JSON.parse 相關
+     * 3. `business_logic` - 回調拋出的一般 Error（isBusinessLogic 為 true）
+     * 4. `permanent` - 其他所有錯誤
+     */
+    categorize(error: Error, isBusinessLogic?: boolean): ErrorCategory;
+    /**
+     * 檢查某個分類的錯誤是否應影響電路斷路器。
+     *
+     * 只有 `transient` 分類應遞增電路的失敗計數。
+     * 其他分類（`serialization`, `business_logic`, `permanent`）
+     * 應直接跳過電路斷路器邏輯。
+     */
+    shouldAffectCircuit(category: ErrorCategory): boolean;
+    /**
+     * 根據錯誤直接判斷是否應影響電路（便利方法）。
+     */
+    shouldRecordInCircuit(error: Error, isBusinessLogic?: boolean): boolean;
+}

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,70 @@
+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;
+    /**
+     * 註冊訊息到達事件監聽器。
+     *
+     * @param callback 當訊息到達時呼叫的回呼函式
+     */
+    onMessageArrived(callback: (event: {
+        queue: string;
+        count: number;
+    }) => void): void;
+    /**
+     * 觸發通知（由 Consumer 的 eachMessage 呼叫）。
+     *
+     * 執行已註冊的所有回呼，並發出 'notify' 事件。
+     * 如果回呼拋出錯誤，不會中斷其他回呼的執行。
+     *
+     * @param queue 佇列名稱
+     */
+    notify(queue: string): void;
+    /**
+     * 觸發帶有數量的通知。
+     *
+     * @param queue 佇列名稱
+     * @param count 訊息數量
+     */
+    notifyWithCount(queue: string, count: number): 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;
+}