@gravito/ripple 4.0.0 → 4.0.1

package/dist/core/src/events/EventOptions.d.ts

@@ -10,12 +10,50 @@ export interface EventOptions {
     async?: boolean;
     /**
      * Priority level for event processing.
-     * - 'high': Critical events (e.g., order:created, payment:succeeded)
-     * - 'normal': Standard events (e.g., order:confirmed)
-     * - 'low': Non-critical events (e.g., analytics, logging)
+     * - 'critical': Immediate processing, bypass queue (< 1ms)
+     * - 'high': High priority events (< 50ms)
+     * - 'normal': Standard events (< 200ms)
+     * - 'low': Non-critical events (< 500ms)
      * @default 'normal'
      */
-    priority?: 'high' | 'normal' | 'low';
+    priority?: 'critical' | 'high' | 'normal' | 'low';
+    /**
+     * Automatic priority escalation configuration.
+     * Events can be automatically upgraded to higher priority based on wait time.
+     */
+    escalation?: {
+        /**
+         * Whether to enable automatic priority escalation.
+         * @default true
+         */
+        enabled?: boolean;
+        /**
+         * Escalation thresholds in milliseconds.
+         * Events exceeding these wait times are promoted.
+         */
+        thresholds?: {
+            /**
+             * Wait time before LOW events are promoted to NORMAL.
+             * @default 200
+             */
+            lowToNormal?: number;
+            /**
+             * Wait time before NORMAL events are promoted to HIGH.
+             * @default 100
+             */
+            normalToHigh?: number;
+            /**
+             * Wait time before HIGH events are promoted to CRITICAL.
+             * @default 50
+             */
+            highToCritical?: number;
+        };
+        /**
+         * Maximum wait time before forcing CRITICAL priority.
+         * @default 500
+         */
+        maxWaitTimeMs?: number;
+    };
     /**
      * Execution timeout in milliseconds.
      * If a listener exceeds this timeout, it will be terminated.
@@ -101,6 +139,63 @@ export interface EventOptions {
          */
         halfOpenRequests?: number;
     };
+    /**
+     * Event aggregation configuration (FS-102).
+     * Enables deduplication and micro-batching for improved throughput.
+     * @default undefined (disabled)
+     */
+    aggregation?: {
+        /**
+         * Enable event aggregation.
+         * @default false
+         */
+        enabled?: boolean;
+        /**
+         * Aggregation window size in milliseconds.
+         * Backpressure-aware adjustment: 50-500ms
+         * @default 200
+         */
+        windowMs?: number;
+        /**
+         * Batch size threshold for auto-flush.
+         * @default 50
+         */
+        batchSize?: number;
+        /**
+         * Deduplication strategy.
+         * @default 'pattern'
+         */
+        deduplication?: 'pattern' | 'idempotencyKey' | 'off';
+        /**
+         * Deduplication pattern (string or function).
+         * String: hook-based pattern
+         * Function: custom pattern from event args
+         */
+        pattern?: string | ((args: unknown) => string);
+        /**
+         * Priority merge strategy.
+         * - 'highest': keep highest priority event
+         * - 'earliest': keep earliest event
+         * - 'latest': keep latest event
+         * @default 'highest'
+         */
+        mergePriority?: 'highest' | 'earliest' | 'latest';
+        /**
+         * Enable automatic cleanup of expired entries.
+         * @default true
+         */
+        enableCleanup?: boolean;
+        /**
+         * Cleanup interval in milliseconds.
+         * @default 300000 (5 minutes)
+         */
+        cleanupIntervalMs?: number;
+        /**
+         * TTL for entries in milliseconds.
+         * @default 600000 (10 minutes)
+         */
+        ttlMs?: number;
+    };
 }
 /**
  * Default event options.

package/dist/core/src/events/EventPriorityQueue.d.ts

@@ -1,23 +1,32 @@
 import type { Span } from '@opentelemetry/api';
 import type { ActionCallback } from '../HookManager';
+import { BackpressureManager } from './BackpressureManager';
 import { CircuitBreaker } from './CircuitBreaker';
 import type { DeadLetterQueue } from './DeadLetterQueue';
 import type { EventBackend } from './EventBackend';
 import type { EventOptions } from './EventOptions';
 import type { EventMetrics } from './observability/EventMetrics';
 import type { EventTracing } from './observability/EventTracing';
-import type { BackpressureStrategy, EventQueueConfig, EventTask } from './types';
+import type { OTelEventMetrics } from './observability/OTelEventMetrics';
+import { type PriorityStatistics } from './PriorityEscalationManager';
+import type { RetryScheduler } from './RetryScheduler';
+import type { BackpressureStrategy, EventQueueConfig, EventTask, MultiPriorityQueueDepth } from './types';
+import type { WorkerPool } from './WorkerPool';
 export type { EventTask, EventQueueConfig, BackpressureStrategy };
 /**
  * Priority queue for event processing.
  * Events are processed based on their priority level:
- * - High priority events are processed first
- * - Normal priority events are processed second
- * - Low priority events are processed last
+ * - Critical priority events are processed first (< 1ms)
+ * - High priority events are processed second (< 50ms)
+ * - Normal priority events are processed third (< 200ms)
+ * - Low priority events are processed last (< 500ms)
+ *
+ * Supports automatic priority escalation based on wait time.
  *
  * @internal
  */
 export declare class EventPriorityQueue implements EventBackend {
+    private criticalPriority;
     private highPriority;
     private normalPriority;
     private lowPriority;
@@ -29,8 +38,13 @@ export declare class EventPriorityQueue implements EventBackend {
     private processingPartitions;
     private eventCircuitBreakers;
     private eventMetrics?;
+    private otelEventMetrics?;
     private eventTracing?;
     private currentDispatchSpan?;
+    private backpressureManager?;
+    private workerPool?;
+    private retryScheduler?;
+    private priorityStats?;
     constructor(config?: EventQueueConfig);
     /**
      * Set the Dead Letter Queue for failed events.
@@ -51,6 +65,27 @@ export declare class EventPriorityQueue implements EventBackend {
      * @internal
      */
     setEventMetrics(metrics: EventMetrics): void;
+    /**
+     * Set the OTelEventMetrics instance for recording DLQ and backpressure metrics.
+     *
+     * @param metrics - OTelEventMetrics instance
+     * @internal
+     */
+    setOTelEventMetrics(metrics: OTelEventMetrics): void;
+    /**
+     * Set the PriorityStatistics instance for tracking priority distribution.
+     *
+     * @param stats - PriorityStatistics instance
+     * @internal
+     */
+    setPriorityStatistics(stats: PriorityStatistics): void;
+    /**
+     * Get the PriorityStatistics instance.
+     *
+     * @returns PriorityStatistics instance or undefined
+     * @internal
+     */
+    getPriorityStatistics(): PriorityStatistics | undefined;
     /**
      * Set the EventTracing instance for distributed tracing.
      *
@@ -72,6 +107,20 @@ export declare class EventPriorityQueue implements EventBackend {
      * @internal
      */
     getCurrentDispatchSpan(): Span | undefined;
+    /**
+     * Set the RetryScheduler for async distributed retries.
+     *
+     * @param scheduler - RetryScheduler instance
+     * @internal
+     */
+    setRetryScheduler(scheduler: RetryScheduler): void;
+    /**
+     * Get the RetryScheduler instance.
+     *
+     * @returns RetryScheduler instance or undefined
+     * @internal
+     */
+    getRetryScheduler(): RetryScheduler | undefined;
     /**
      * Get or create a circuit breaker for an event hook.
      *
@@ -90,7 +139,7 @@ export declare class EventPriorityQueue implements EventBackend {
      * @param options - Event options
      * @returns Task ID
      */
-    enqueue(task: EventTask): void;
+    enqueue(task: EventTask): string;
     enqueue(hook: string, args: unknown, callbacks: ActionCallback[], options: EventOptions): string;
     /**
      * Handle backpressure when queue is full.
@@ -99,17 +148,20 @@ export declare class EventPriorityQueue implements EventBackend {
     private handleBackpressure;
     /**
      * Drop the oldest event from the queue, prioritizing low priority events.
+     * Drops in order: LOW → NORMAL → HIGH → CRITICAL
      */
     private dropOldest;
     /**
      * Process the next task in the queue.
      * Tasks are processed in priority order: high > normal > low
+     * If WorkerPool is configured, tasks are submitted to the pool for concurrent execution.
      *
      * @internal
      */
     private processNext;
     /**
      * Dequeue the next task based on priority and partition ordering.
+     * Priority order: CRITICAL > HIGH > NORMAL > LOW
      *
      * @returns Next task to process, or undefined if queue is empty
      * @internal
@@ -171,7 +223,28 @@ export declare class EventPriorityQueue implements EventBackend {
      * @param priority - Priority level
      * @returns Number of tasks in the specified priority queue
      */
-    getDepthByPriority(priority: 'high' | 'normal' | 'low'): number;
+    getDepthByPriority(priority: 'critical' | 'high' | 'normal' | 'low'): number;
+    /**
+     * Get the BackpressureManager instance if enabled.
+     *
+     * @returns BackpressureManager instance or undefined if not enabled
+     * @internal
+     */
+    getBackpressureManager(): BackpressureManager | undefined;
+    /**
+     * Set the WorkerPool for concurrent task execution.
+     *
+     * @param pool - WorkerPool instance
+     * @internal
+     */
+    setWorkerPool(pool: WorkerPool): void;
+    /**
+     * Get the WorkerPool instance if set.
+     *
+     * @returns WorkerPool instance or undefined if not set
+     * @internal
+     */
+    getWorkerPool(): WorkerPool | undefined;
     /**
      * Clear all tasks from the queue.
      */
@@ -199,4 +272,30 @@ export declare class EventPriorityQueue implements EventBackend {
      * @internal
      */
     resetCircuitBreaker(hook: string): boolean;
+    /**
+     * Batch enqueue multiple tasks (FS-102).
+     * Supports aggregation layer batch submission.
+     *
+     * @param tasks - Array of tasks to enqueue
+     * @returns Array of task IDs
+     * @internal
+     */
+    enqueueBatch(tasks: EventTask[]): string[];
+    /**
+     * Get queue depth for each priority level (FS-103).
+     * Used by BackpressureManager for multi-priority depth monitoring.
+     *
+     * @returns Queue depth snapshot with depths for each priority
+     * @internal
+     */
+    getQueueDepthByPriority(): MultiPriorityQueueDepth;
+    /**
+     * Sync queue depth to BackpressureManager (FS-103).
+     * Called whenever queue depth changes to keep BackpressureManager
+     * synchronized with real-time queue state.
+     *
+     * @private
+     * @internal
+     */
+    private syncBackpressure;
 }

package/dist/core/src/events/FlowControlStrategy.d.ts

@@ -0,0 +1,109 @@
+/**
+ * @gravito/core - Flow Control Strategies
+ *
+ * Implements various flow control strategies for backpressure management.
+ * Strategies can be composed to create flexible backpressure policies.
+ *
+ * 流控策略：支援多種組合策略進行靈活的背壓管理。
+ */
+import { type BackpressureConfig, type BackpressureDecision, BackpressureState } from './BackpressureManager';
+/**
+ * 流控評估上下文。
+ *
+ * @public
+ */
+export interface FlowControlContext {
+    /** 當前背壓狀態 */
+    state: BackpressureState;
+    /** 事件優先級 */
+    priority: 'high' | 'normal' | 'low';
+    /** 總隊列深度 */
+    totalDepth: number;
+    /** 分優先級隊列深度 */
+    depthByPriority: {
+        high: number;
+        normal: number;
+        low: number;
+    };
+    /** 當前入隊速率（events/sec） */
+    currentRate: number;
+    /** 配置 */
+    config: Omit<BackpressureConfig, 'onRejected' | 'onStateChange'>;
+}
+/**
+ * 流控策略介面。
+ *
+ * @public
+ */
+export interface FlowControlStrategy {
+    /** 策略名稱 */
+    readonly name: string;
+    /** 評估是否應該限制此事件 */
+    evaluate(context: FlowControlContext): BackpressureDecision;
+}
+/**
+ * 隊列深度策略。
+ *
+ * 根據總隊列深度和分優先級隊列深度決定是否限制事件入隊。
+ */
+export declare class QueueDepthStrategy implements FlowControlStrategy {
+    readonly name = "queue-depth";
+    evaluate(context: FlowControlContext): BackpressureDecision;
+}
+/**
+ * 速率限制策略。
+ *
+ * 根據每秒入隊速率限制事件入隊。
+ */
+export declare class RateLimitStrategy implements FlowControlStrategy {
+    readonly name = "rate-limit";
+    evaluate(context: FlowControlContext): BackpressureDecision;
+}
+/**
+ * 優先級平衡策略。
+ *
+ * 在 WARNING 和 CRITICAL 狀態下降級低優先級事件，防止高優先級飢餓。
+ */
+export declare class PriorityRebalanceStrategy implements FlowControlStrategy {
+    readonly name = "priority-rebalance";
+    evaluate(context: FlowControlContext): BackpressureDecision;
+}
+/**
+ * 反飢餓保護策略。
+ *
+ * 防止低優先級事件被長期壓制。
+ * 當事件等待超過 starvationTimeoutMs 時，自動提升其優先級。
+ */
+export declare class StarvationProtectionStrategy implements FlowControlStrategy {
+    readonly name = "starvation-protection";
+    evaluate(_context: FlowControlContext): BackpressureDecision;
+}
+/**
+ * 組合策略。
+ *
+ * 組合多個策略。評估時所有子策略必須允許，否則拒絕。
+ * 取最嚴格的決策（拒絕 > 延遲 > 允許）。
+ */
+export declare class CompositeStrategy implements FlowControlStrategy {
+    readonly name: string;
+    private strategies;
+    constructor(name: string, strategies: FlowControlStrategy[]);
+    evaluate(context: FlowControlContext): BackpressureDecision;
+    /**
+     * 新增子策略。
+     */
+    addStrategy(strategy: FlowControlStrategy): void;
+    /**
+     * 移除指定名稱的子策略。
+     */
+    removeStrategy(name: string): boolean;
+}
+/**
+ * 工廠方法：建立預設流控策略組合。
+ *
+ * @param config 背壓配置
+ * @returns 組合策略實例
+ *
+ * @public
+ */
+export declare function createDefaultStrategies(_config: Omit<BackpressureConfig, 'onRejected' | 'onStateChange'>): FlowControlStrategy[];

package/dist/core/src/events/MessageQueueBridge.d.ts

@@ -0,0 +1,184 @@
+/**
+ * @gravito/core - Message Queue Bridge
+ *
+ * 橋接層，連接 HookManager 與 Bull Queue (via StreamEventBackend)
+ * 支持分佈式事件流：HookManager → Bull Queue → Worker → 完成/DLQ
+ */
+import type { HookManager } from '../HookManager';
+import type { DeadLetterQueueManager } from '../reliability/DeadLetterQueueManager';
+import type { EventBackend } from './EventBackend';
+import type { EventTask } from './types';
+import type { WorkerPool } from './WorkerPool';
+/**
+ * 事件執行狀態
+ */
+export interface EventStatus {
+    eventId: string;
+    status: 'pending' | 'processing' | 'completed' | 'failed' | 'in_dlq';
+    attempts: number;
+    lastError?: string;
+    createdAt: number;
+    processedAt?: number;
+}
+/**
+ * MessageQueueBridge 配置
+ */
+export interface MessageQueueBridgeConfig {
+    /**
+     * HookManager 實例
+     */
+    hookManager: HookManager;
+    /**
+     * Worker 線程池（可選）
+     */
+    workerPool?: WorkerPool;
+    /**
+     * 分佈式事件後端（Bull Queue）
+     */
+    eventBackend: EventBackend;
+    /**
+     * Dead Letter Queue 管理器
+     */
+    dlqManager: DeadLetterQueueManager;
+    /**
+     * 是否啟用 CircuitBreaker 檢查
+     * @default false
+     */
+    enableCircuitBreaker?: boolean;
+}
+/**
+ * MessageQueueBridge - 連接 HookManager 與 Bull Queue 的橋接層
+ *
+ * 功能：
+ * 1. 通過 Bull Queue 分發事件（dispatchWithQueue）
+ * 2. Worker 中處理隊列事件（processQueuedEvent）
+ * 3. 失敗任務轉移至 DLQ（handleJobFailure）
+ * 4. 查詢事件執行狀態（getEventStatus）
+ *
+ * @example
+ * ```typescript
+ * const bridge = new MessageQueueBridge({
+ *   hookManager,
+ *   eventBackend: streamEventBackend,
+ *   dlqManager,
+ *   enableCircuitBreaker: true
+ * })
+ *
+ * // 分發事件至 Bull Queue
+ * const jobId = await bridge.dispatchWithQueue('order:created', { orderId: 123 })
+ *
+ * // Worker 處理事件
+ * await bridge.processQueuedEvent(jobId, task)
+ * ```
+ */
+export declare class MessageQueueBridge {
+    private config;
+    constructor(config: MessageQueueBridgeConfig);
+    /**
+     * 通過 Bull Queue 分發事件（分佈式異步處理）
+     *
+     * 流程：
+     * 1. 驗證事件 listeners 存在
+     * 2. 檢查 CircuitBreaker 狀態（如果啟用）
+     * 3. 構建 EventTask
+     * 4. 入隊到 eventBackend (Bull Queue)
+     *
+     * @param eventName - 事件名稱
+     * @param args - 事件參數
+     * @param options - 事件選項（可選）
+     * @returns Job ID
+     * @throws 如果沒有 listeners 或 CircuitBreaker 打開
+     *
+     * @example
+     * ```typescript
+     * const jobId = await bridge.dispatchWithQueue('order:created', {
+     *   orderId: 'ORD-123',
+     *   amount: 999.99
+     * })
+     * ```
+     */
+    dispatchWithQueue<TArgs = unknown>(eventName: string, args: TArgs, options?: any): Promise<string>;
+    /**
+     * 處理隊列事件（由 Bull Queue Worker 調用）
+     *
+     * 重要：使用 doActionSync() 避免遞迴
+     * - 不能使用 doActionAsync()（會導致事件再次入隊）
+     * - Worker 中直接同步執行 callbacks
+     *
+     * 流程：
+     * 1. 直接執行 callbacks（不使用 doActionSync，避免吞掉錯誤）
+     * 2. 記錄成功或失敗
+     * 3. 拋出錯誤讓 Bull Queue 處理重試
+     *
+     * @param jobId - Bull Queue Job ID
+     * @param task - 事件任務
+     * @throws 如果 callback 執行失敗，讓 Bull Queue 處理重試
+     *
+     * @example
+     * ```typescript
+     * // 在 Bull Queue Worker 中：
+     * await bridge.processQueuedEvent(jobId, task)
+     * ```
+     */
+    processQueuedEvent(jobId: string, task: EventTask): Promise<void>;
+    /**
+     * 處理 Bull Queue 任務失敗（由 onFailed callback 調用）
+     *
+     * 流程：
+     * 1. 記錄警告日誌
+     * 2. 移至 persistent DLQ（DeadLetterQueueManager）
+     * 3. 持久化到 event_dlq 表，支持延遲重試
+     *
+     * @param jobId - Bull Queue Job ID
+     * @param task - 事件任務
+     * @param error - 導致失敗的錯誤
+     * @param retryCount - 已重試次數（可選）
+     *
+     * @example
+     * ```typescript
+     * // 在 Bull Queue onFailed callback 中：
+     * await bridge.handleJobFailure(jobId, task, error, 3)
+     * ```
+     */
+    handleJobFailure(jobId: string, task: EventTask, error: Error, retryCount?: number): Promise<void>;
+    /**
+     * 查詢事件執行狀態
+     *
+     * 支持查詢：
+     * 1. 待處理事件
+     * 2. 正在處理的事件
+     * 3. 已完成事件
+     * 4. 失敗事件（在 DLQ 中）
+     *
+     * @param eventId - 事件 ID（task.id 或 jobId）
+     * @returns 事件狀態
+     *
+     * @example
+     * ```typescript
+     * const status = await bridge.getEventStatus('queue-1707000000000-abc123')
+     * console.log(status) // { eventId, status, attempts, ... }
+     * ```
+     */
+    getEventStatus(eventId: string): Promise<EventStatus>;
+    /**
+     * 獲取 EventBackend 實例（用於高級操作）
+     *
+     * @returns EventBackend 實例
+     * @internal
+     */
+    getEventBackend(): EventBackend;
+    /**
+     * 獲取 DLQ 管理器實例（用於高級操作）
+     *
+     * @returns DeadLetterQueueManager 實例
+     * @internal
+     */
+    getDLQManager(): DeadLetterQueueManager;
+    /**
+     * 獲取 HookManager 實例（用於高級操作）
+     *
+     * @returns HookManager 實例
+     * @internal
+     */
+    getHookManager(): HookManager;
+}

package/dist/core/src/events/PriorityEscalationManager.d.ts

@@ -0,0 +1,82 @@
+import type { EventOptions } from './EventOptions';
+import type { EventTask } from './types';
+/**
+ * 優先級升級管理器
+ *
+ * 根據事件等待時間動態調整優先級，實施優先級提升機制。
+ * 確保關鍵事件不會因為隊列深度而長時間等待。
+ *
+ * 升級規則（可配置）：
+ * - LOW 等待 > 200ms → NORMAL
+ * - NORMAL 等待 > 100ms → HIGH
+ * - HIGH 等待 > 50ms → CRITICAL
+ * - 超過 maxWaitTimeMs → 強制 CRITICAL
+ *
+ * @internal
+ */
+export declare class PriorityEscalationManager {
+    /**
+     * 計算事件當前應該的優先級
+     * 根據等待時間動態調整
+     */
+    static calculateCurrentPriority(task: EventTask, config?: EventOptions['escalation']): 'critical' | 'high' | 'normal' | 'low';
+    /**
+     * 比較兩個事件的優先級
+     * @returns 負數表示 task1 優先級更高，正數表示 task2 優先級更高
+     */
+    static comparePriority(task1: EventTask, task2: EventTask): number;
+    /**
+     * 判斷事件是否應該立即處理（跳過隊列）
+     */
+    static shouldProcessImmediately(task: EventTask, config?: EventOptions['escalation']): boolean;
+    /**
+     * 獲取事件當前的超期時間（毫秒）
+     * 正數表示已超期，0 表示未超期
+     */
+    static calculateOverdueTime(task: EventTask, config?: EventOptions['escalation']): number;
+}
+/**
+ * 優先級統計器
+ * 追蹤優先級分布和升級事件
+ *
+ * @internal
+ */
+export declare class PriorityStatistics {
+    private eventCounts;
+    private escalationCounts;
+    private totalEscalations;
+    /**
+     * 記錄一個優先級的事件
+     */
+    recordEvent(priority: 'critical' | 'high' | 'normal' | 'low'): void;
+    /**
+     * 記錄優先級升級
+     */
+    recordEscalation(fromPriority: 'critical' | 'high' | 'normal' | 'low', toPriority: 'critical' | 'high' | 'normal' | 'low'): void;
+    /**
+     * 獲取優先級分布
+     */
+    getDistribution(): Record<'critical' | 'high' | 'normal' | 'low', string>;
+    /**
+     * 獲取升級統計
+     */
+    getEscalationStats(): {
+        total: number;
+        byTransition: Record<string, number>;
+    };
+    /**
+     * 重置統計信息
+     */
+    reset(): void;
+    /**
+     * 獲取所有統計信息
+     */
+    getStats(): {
+        eventCounts: Record<'critical' | 'high' | 'normal' | 'low', number>;
+        escalationStats: {
+            total: number;
+            byTransition: Record<string, number>;
+        };
+        distribution: Record<'critical' | 'high' | 'normal' | 'low', string>;
+    };
+}