@gravito/stream 2.0.1 → 2.1.0

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';