@gravito/core 1.6.0 → 2.0.0

package/dist/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/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>;
+    };
+}

package/dist/events/RetryScheduler.d.ts

@@ -0,0 +1,104 @@
+/**
+ * @gravito/core - Retry Scheduler
+ *
+ * 分佈式重試排程器，使用 Bull Queue 進行異步延遲重試。
+ * 支援指數回退、Redis 持久化、重試失敗回呼。
+ *
+ * Distributed retry scheduler using Bull Queue for async delayed retries.
+ * Supports exponential backoff, Redis persistence, and failure callbacks.
+ */
+import type { EventOptions } from './EventOptions';
+/**
+ * 重試排程器配置介面
+ */
+export interface RetrySchedulerConfig {
+    /** 是否啟用 Bull Queue 重試（預設 true） */
+    enabled?: boolean;
+    /** Redis 連接配置（可選，使用全域 Redis） */
+    redisUrl?: string;
+    /** 預設最大重試次數（預設 5） */
+    maxRetries?: number;
+    /** 初始延遲時間（ms，預設 1000） */
+    initialDelayMs?: number;
+    /** 指數回退倍數（預設 2.0） */
+    backoffMultiplier?: number;
+    /** 最大延遲時間（ms，預設 1h） */
+    maxDelayMs?: number;
+    /** 重試失敗回呼 */
+    onRetryFailed?: (eventName: string, error: Error, retryCount: number) => void;
+}
+/**
+ * 隊列統計資訊
+ */
+export interface QueueStats {
+    name: string;
+    jobCounts: {
+        waiting: number;
+        active: number;
+        delayed: number;
+        failed: number;
+    };
+    completedCount: number;
+    failedCount: number;
+}
+/**
+ * 重試排程器
+ *
+ * 提供異步分佈式重試機制，利用 Bull Queue 進行延遲重試。
+ * 支援指數回退、Redis 持久化、隊列統計。
+ */
+export declare class RetryScheduler {
+    private enabled;
+    private config;
+    private queues;
+    private bullmqModule;
+    private bullmqLoadError;
+    constructor(config?: RetrySchedulerConfig);
+    /**
+     * 動態加載 bullmq 模組
+     */
+    private loadBullmq;
+    /**
+     * 檢查排程器是否啟用
+     */
+    isEnabled(): boolean;
+    /**
+     * 計算指數回退延遲時間
+     *
+     * @param retryCount 當前重試次數（從 0 開始）
+     * @returns 延遲時間（毫秒）
+     */
+    private calculateDelay;
+    /**
+     * 獲取或創建隊列
+     *
+     * @param eventName 事件名稱
+     * @returns Queue 實例
+     */
+    private getOrCreateQueue;
+    /**
+     * 排程重試任務
+     *
+     * @param eventName 事件名稱
+     * @param payload 事件負載
+     * @param options 事件選項
+     * @param error 原始錯誤
+     * @param retryCount 當前重試次數
+     */
+    scheduleRetry(eventName: string, payload: unknown, _options: EventOptions, error: Error, retryCount: number): Promise<void>;
+    /**
+     * 獲取特定事件的隊列
+     *
+     * @param eventName 事件名稱
+     * @returns Queue 實例或 undefined
+     */
+    getQueue(eventName: string): unknown;
+    /**
+     * 取得所有隊列統計
+     */
+    getStats(): Map<string, QueueStats>;
+    /**
+     * 關閉所有隊列並清理資源
+     */
+    shutdown(): Promise<void>;
+}

package/dist/events/WorkerPool.d.ts

@@ -0,0 +1,98 @@
+/**
+ * Worker Pool for concurrent event task processing.
+ *
+ * Manages a pool of workers for executing event tasks concurrently.
+ * Supports auto-scaling, health checks, and OpenTelemetry metrics integration.
+ *
+ * @internal
+ */
+import type { Meter } from '@opentelemetry/api';
+import type { EventTask } from './types';
+import type { WorkerPoolConfig, WorkerPoolStats, WorkerStats } from './WorkerPoolConfig';
+/**
+ * Worker Pool for managing concurrent task execution
+ */
+export declare class WorkerPool {
+    private workers;
+    private taskQueue;
+    private config;
+    private metrics?;
+    private healthCheckTimer?;
+    private metricsTimer?;
+    private isRunning;
+    private scaleDownCounter;
+    constructor(config?: WorkerPoolConfig, meter?: Meter);
+    /**
+     * Start the worker pool
+     */
+    start(): Promise<void>;
+    /**
+     * Stop the worker pool
+     */
+    stop(): Promise<void>;
+    /**
+     * Submit a task to the worker pool
+     */
+    submitTask(task: EventTask): Promise<void>;
+    /**
+     * Process next task in queue
+     */
+    private processQueue;
+    /**
+     * Execute task on a worker
+     */
+    private executeTask;
+    /**
+     * Execute task callbacks
+     */
+    private executeTaskCallbacks;
+    /**
+     * Create a timeout promise
+     */
+    private createTimeout;
+    /**
+     * Create a new worker
+     */
+    private createWorker;
+    /**
+     * Remove a worker
+     */
+    private removeWorker;
+    /**
+     * Perform health check and cleanup
+     */
+    private performHealthCheck;
+    /**
+     * Perform auto-scaling based on load
+     */
+    private performAutoScaling;
+    /**
+     * Collect metrics
+     */
+    private collectMetrics;
+    /**
+     * Get number of active workers (not terminated)
+     */
+    private getActiveWorkerCount;
+    /**
+     * Get worker utilization (0-1)
+     */
+    private getUtilization;
+    /**
+     * Get queue depth
+     */
+    getQueueDepth(): number;
+    /**
+     * Get worker utilization
+     */
+    getWorkerUtilization(): number;
+    /**
+     * Get worker statistics
+     */
+    getWorkerStats(): WorkerStats[];
+    /**
+     * Get pool statistics
+     */
+    getPoolStats(): WorkerPoolStats;
+}
+export type { WorkerPoolConfig, WorkerStats, WorkerPoolStats };

package/dist/events/WorkerPoolConfig.d.ts

@@ -0,0 +1,153 @@
+/**
+ * Worker Pool Configuration and Types
+ *
+ * Defines configuration interfaces and data types for worker pool management.
+ *
+ * @internal
+ */
+import type { EventTask } from './types';
+/**
+ * Task source interface for fetching and acknowledging tasks.
+ * Supports integration with external task systems like Bull Queue.
+ */
+export interface TaskSource {
+    /**
+     * Fetch the next task from the source.
+     * Returns null if no tasks available.
+     */
+    fetchTask(): Promise<EventTask | null>;
+    /**
+     * Acknowledge successful task completion.
+     */
+    acknowledgeCompletion(taskId: string): Promise<void>;
+    /**
+     * Acknowledge task failure.
+     */
+    acknowledgeFailure(taskId: string, error: Error): Promise<void>;
+}
+/**
+ * Worker Pool Configuration
+ */
+export interface WorkerPoolConfig {
+    /**
+     * Maximum number of concurrent tasks being processed.
+     * @default 4
+     */
+    concurrency?: number;
+    /**
+     * Number of worker threads to maintain.
+     * @default Number of CPU cores
+     */
+    workerThreads?: number;
+    /**
+     * Task execution timeout in milliseconds.
+     * @default 30000
+     */
+    taskTimeout?: number;
+    /**
+     * Maximum number of retries for failed tasks.
+     * @default 3
+     */
+    maxRetries?: number;
+    /**
+     * Enable automatic scaling based on load.
+     * @default true
+     */
+    enableAutoScaling?: boolean;
+    /**
+     * Minimum number of workers for auto-scaling.
+     * @default 1
+     */
+    minWorkers?: number;
+    /**
+     * Maximum number of workers for auto-scaling.
+     * @default 2 * CPU cores
+     */
+    maxWorkers?: number;
+    /**
+     * Worker utilization threshold for scaling up (0-1).
+     * @default 0.8
+     */
+    scaleUpThreshold?: number;
+    /**
+     * Worker utilization threshold for scaling down (0-1).
+     * @default 0.2
+     */
+    scaleDownThreshold?: number;
+    /**
+     * Interval for collecting metrics in milliseconds.
+     * @default 5000
+     */
+    metricsInterval?: number;
+    /**
+     * External task source (e.g., Bull Queue).
+     * When provided, workers fetch tasks from this source.
+     */
+    taskSource?: TaskSource;
+}
+/**
+ * Worker State
+ */
+export type WorkerState = 'idle' | 'busy' | 'terminated';
+/**
+ * Worker Statistics
+ */
+export interface WorkerStats {
+    /**
+     * Unique worker identifier.
+     */
+    id: string;
+    /**
+     * Current worker state.
+     */
+    state: WorkerState;
+    /**
+     * Total tasks processed by this worker.
+     */
+    tasksProcessed: number;
+    /**
+     * Total successful tasks.
+     */
+    tasksSuccess: number;
+    /**
+     * Total failed tasks.
+     */
+    tasksFailed: number;
+    /**
+     * Average task execution duration in milliseconds.
+     */
+    avgDurationMs: number;
+    /**
+     * Worker uptime in milliseconds.
+     */
+    uptime: number;
+}
+/**
+ * Worker Pool Statistics
+ */
+export interface WorkerPoolStats {
+    /**
+     * Total tasks in queue.
+     */
+    queueDepth: number;
+    /**
+     * Worker utilization (0-1).
+     */
+    utilization: number;
+    /**
+     * Current number of active workers.
+     */
+    activeWorkers: number;
+    /**
+     * Total tasks processed.
+     */
+    totalTasksProcessed: number;
+    /**
+     * Total successful tasks.
+     */
+    totalSuccess: number;
+    /**
+     * Total failed tasks.
+     */
+    totalFailures: number;
+}

package/dist/events/WorkerPoolMetrics.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Worker Pool Metrics for OpenTelemetry integration.
+ *
+ * Tracks worker pool statistics and emits metrics using OpenTelemetry.
+ * Follows the Provider Callback pattern for dynamic metric collection.
+ *
+ * @internal
+ */
+import type { Meter } from '@opentelemetry/api';
+/**
+ * Worker Pool Metrics Recorder
+ */
+export declare class WorkerPoolMetrics {
+    private meter;
+    private taskDurationHistogram?;
+    private taskCounter?;
+    private autoScalingCounter?;
+    private poolSizeCallback?;
+    private utilizationCallback?;
+    private queueDepthCallback?;
+    constructor(meter: Meter);
+    /**
+     * Initialize OpenTelemetry metrics
+     */
+    private initializeMetrics;
+    /**
+     * Set provider callback for pool size metric
+     */
+    setPoolSizeProvider(callback: () => number): void;
+    /**
+     * Set provider callback for utilization metric
+     */
+    setUtilizationProvider(callback: () => number): void;
+    /**
+     * Set provider callback for queue depth metric
+     */
+    setQueueDepthProvider(callback: () => number): void;
+    /**
+     * Record task execution
+     *
+     * @param durationMs - Task execution duration in milliseconds
+     * @param priority - Task priority level
+     * @param success - Whether task succeeded
+     */
+    recordTaskExecution(durationMs: number, priority: string, success: boolean): void;
+    /**
+     * Record auto-scaling event
+     *
+     * @param action - 'scale-up' or 'scale-down'
+     * @param reason - Reason for scaling
+     */
+    recordAutoScaling(action: 'scale-up' | 'scale-down', reason: string): void;
+    /**
+     * Get the current pool size (for provider callbacks)
+     */
+    getPoolSize(): number;
+    /**
+     * Get the current utilization (for provider callbacks)
+     */
+    getUtilization(): number;
+    /**
+     * Get the current queue depth (for provider callbacks)
+     */
+    getQueueDepth(): number;
+}