@gravito/stream 2.0.2 → 2.1.2

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

@@ -0,0 +1,65 @@
+/**
+ * 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;
+    /** topic -> partition -> 統計資訊 */
+    private readonly stats;
+    /**
+     * 標記一個 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;
+}

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

@@ -0,0 +1,52 @@
+/**
+ * Sliding window rate limiter for per-queue message throughput control.
+ *
+ * Implements token depletion: allows max N messages within a rolling duration window.
+ * Uses a sliding window counter algorithm for memory efficiency.
+ *
+ * @public
+ */
+export declare class RateLimiter {
+    private windowStates;
+    private hitCount;
+    /**
+     * Check if a message should be allowed based on rate limit config.
+     * @returns true if allowed, false if exceeds limit
+     */
+    check(queue: string, config: {
+        max: number;
+        duration: number;
+    }): boolean;
+    /**
+     * Get current rate limit state for a queue.
+     */
+    getState(queue: string): {
+        queue: string;
+        allowed: number;
+        remaining: number;
+        resetAt: number;
+        windowStart: number;
+    };
+    /**
+     * Get rate limit hit statistics for a queue.
+     */
+    getStats(queue: string): {
+        allowed: number;
+        denied: number;
+    };
+    /**
+     * Get statistics for all queues.
+     */
+    getAllStats(): Record<string, {
+        allowed: number;
+        denied: number;
+    }>;
+    /**
+     * Reset rate limiter for a specific queue or all queues.
+     */
+    reset(queue?: string): void;
+    /**
+     * Internal: Record rate limit hit/deny.
+     */
+    private recordHit;
+}

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

@@ -0,0 +1,104 @@
+import { EventEmitter } from 'node:events';
+import type { PartitionAssignment, RebalanceConfig, RebalanceEvent, RebalanceStatus } from './types';
+/**
+ * 回調介面：RebalanceHandler 在撤銷/分配時通知外部元件。
+ */
+export interface RebalanceCallbacks {
+    /** 在分區撤銷前提交 offset */
+    commitOffsets: () => Promise<void>;
+    /** 清除指定分區的緩衝訊息 */
+    clearPartitionBuffers: (partitions: PartitionAssignment[]) => void;
+    /** 清除指定分區的 offset 追蹤 */
+    clearPartitionTracking: (partitions: PartitionAssignment[]) => void;
+}
+/**
+ * 管理 Kafka 消費者群組的重新平衡事件。
+ *
+ * 協調 MessageBuffer、OffsetTracker 和 ConsumerLifecycleManager
+ * 在分區撤銷與分配期間的狀態一致性。
+ *
+ * 狀態機:
+ * - stable → revoking → assigning → stable
+ * - any → error
+ *
+ * 事件:
+ * - 'rebalance' - 每次狀態變更時發出 RebalanceEvent
+ * - 'partitionsRevoked' - 分區被撤銷
+ * - 'partitionsAssigned' - 分區被分配
+ *
+ * @public
+ */
+export declare class RebalanceHandler extends EventEmitter {
+    private readonly revocationTimeoutMs;
+    private readonly commitOnRevoke;
+    private readonly clearBufferOnRevoke;
+    private readonly maxConcurrentRebalances;
+    private currentState;
+    private previousState;
+    private assignedPartitions;
+    private totalRebalances;
+    private lastRebalanceTimestamp;
+    private activeRebalances;
+    private callbacks;
+    constructor(config?: RebalanceConfig);
+    /**
+     * 註冊重新平衡回調。
+     *
+     * 外部元件（KafkaDriver）透過此方法提供
+     * offset 提交和緩衝清除能力。
+     */
+    registerCallbacks(callbacks: RebalanceCallbacks): void;
+    /**
+     * 處理分區撤銷事件。
+     *
+     * 執行順序:
+     * 1. 轉換到 'revoking' 狀態
+     * 2. 提交已追蹤的 offset（如果啟用）
+     * 3. 清除被撤銷分區的緩衝（如果啟用）
+     * 4. 清除被撤銷分區的追蹤資料
+     * 5. 發出事件通知
+     */
+    handlePartitionsRevoked(partitions: PartitionAssignment[]): Promise<void>;
+    /**
+     * 處理分區分配事件。
+     *
+     * 更新已分配分區列表並發出事件。
+     */
+    handlePartitionsAssigned(partitions: PartitionAssignment[]): Promise<void>;
+    /**
+     * 執行完整的重新平衡流程（撤銷 + 分配）。
+     */
+    handleRebalance(revokedPartitions: PartitionAssignment[], assignedPartitions: PartitionAssignment[]): Promise<void>;
+    /**
+     * 返回當前重新平衡狀態快照（不可變）。
+     */
+    getStatus(): RebalanceStatus;
+    /**
+     * 檢查是否正在重新平衡中。
+     */
+    isRebalancing(): boolean;
+    /**
+     * 取得當前已分配的分區列表（不可變）。
+     */
+    getAssignedPartitions(): PartitionAssignment[];
+    /**
+     * 註冊重新平衡狀態變更監聽器。
+     */
+    onRebalance(listener: (event: RebalanceEvent) => void): void;
+    /**
+     * 重置為初始狀態。
+     */
+    reset(): void;
+    /**
+     * 清理資源。
+     */
+    destroy(): void;
+    /**
+     * 內部：執行狀態轉換並發出事件。
+     */
+    private transitionTo;
+    /**
+     * 內部：使用逾時保護執行非同步操作。
+     */
+    private withTimeout;
+}

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

@@ -0,0 +1,63 @@
+/**
+ * 固定容量環形緩衝區，提供 O(1) push 和 shift 操作。
+ *
+ * 取代 Array.shift() 的 O(n) 瓶頸，用於高吞吐量訊息處理場景。
+ *
+ * 內部使用固定長度陣列 + head/tail 指標實現 FIFO 語義，
+ * 避免重新索引開銷。
+ *
+ * @public
+ */
+export declare class RingBuffer<T> {
+    private readonly items;
+    private readonly capacity;
+    private head;
+    private tail;
+    private count;
+    constructor(capacity: number);
+    /**
+     * 推入元素到緩衝區尾端。
+     * @returns true 如果成功推入，false 如果緩衝區已滿
+     */
+    push(item: T): boolean;
+    /**
+     * 從緩衝區頭部取出元素（FIFO）。
+     * @returns 元素，或 undefined 如果緩衝區為空
+     */
+    shift(): T | undefined;
+    /**
+     * 查看頭部元素但不移除。
+     * @returns 元素，或 undefined 如果緩衝區為空
+     */
+    peek(): T | undefined;
+    /**
+     * 從頭部批次取出多個元素。
+     * @param count 要取出的最大數量
+     * @returns 取出的元素陣列
+     */
+    shiftMany(count: number): T[];
+    /**
+     * 當前緩衝區中的元素數量。
+     */
+    get length(): number;
+    /**
+     * 緩衝區是否為空。
+     */
+    get isEmpty(): boolean;
+    /**
+     * 緩衝區是否已滿。
+     */
+    get isFull(): boolean;
+    /**
+     * 緩衝區的最大容量。
+     */
+    getCapacity(): number;
+    /**
+     * 清空緩衝區中所有元素。
+     */
+    clear(): void;
+    /**
+     * 將緩衝區中的元素轉換為陣列（從頭到尾順序，不移除元素）。
+     */
+    toArray(): T[];
+}

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

@@ -0,0 +1,22 @@
+/**
+ * @gravito/stream Kafka Driver 模組。
+ *
+ * 提供生產級的 Kafka Queue 驅動程式實作，
+ * 整合 ReactiveStrategy 和完整的 QueueDriver 介面。
+ *
+ * @public
+ */
+export { BackpressureController } from './BackpressureController';
+export { BatchProcessor } from './BatchProcessor';
+export { ConsumerLifecycleManager } from './ConsumerLifecycleManager';
+export { ErrorCategorizer } from './ErrorCategorizer';
+export { ErrorRecoveryManager } from './ErrorRecoveryManager';
+export { HeartbeatManager } from './HeartbeatManager';
+export { KafkaDriver } from './KafkaDriver';
+export { KafkaMetrics } from './KafkaMetrics';
+export { KafkaNotifier } from './KafkaNotifier';
+export { MessageBuffer } from './MessageBuffer';
+export { OffsetTracker } from './OffsetTracker';
+export { PerformanceMonitor } from './PerformanceMonitor';
+export { RebalanceHandler } from './RebalanceHandler';
+export type { BufferedMessage, ConsumerLifecycleState, DlqStats, ErrorCategory, ErrorRecoveryConfig, ErrorRecoveryState, HeartbeatConfig, HeartbeatStatus, KafkaAdminClient, KafkaClientFactory, KafkaConsumerClient, KafkaDriverFullConfig, KafkaMessage, KafkaProducerClient, LifecycleEvent, MetricsConfig, PartitionAssignment, PerformanceConfig, PerformanceSnapshot, RebalanceConfig, RebalanceEvent, RebalanceState, RebalanceStatus, SerializationErrorRecord, SubscribeOptions, } from './types';