@gravito/echo 3.1.1 → 3.1.2

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

@@ -1,301 +0,0 @@
-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 { 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:
- * - 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;
-    private processing;
-    private taskIdCounter;
-    private dlq?;
-    private persistentDLQHandler?;
-    private config;
-    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.
-     *
-     * @param dlq - Dead Letter Queue instance
-     */
-    setDeadLetterQueue(dlq: DeadLetterQueue): void;
-    /**
-     * Set the persistent DLQ handler for failed events.
-     *
-     * @param handler - Async handler function for persistent DLQ
-     */
-    setPersistentDLQHandler(handler: (hook: string, args: unknown, options: EventOptions, error: Error, retryCount: number, firstFailedAt: number) => Promise<void>): void;
-    /**
-     * Set the EventMetrics instance for recording circuit breaker metrics.
-     *
-     * @param metrics - EventMetrics instance
-     * @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.
-     *
-     * @param tracing - EventTracing instance
-     * @internal
-     */
-    setEventTracing(tracing: EventTracing): void;
-    /**
-     * Set the current dispatch span for creating child spans.
-     *
-     * @param span - Parent dispatch span
-     * @internal
-     */
-    setCurrentDispatchSpan(span: Span | undefined): void;
-    /**
-     * Get the current dispatch span.
-     *
-     * @returns Current dispatch span or undefined
-     * @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.
-     *
-     * @param hook - Event hook name
-     * @param config - Circuit breaker configuration
-     * @returns Circuit breaker instance or undefined if not configured
-     * @internal
-     */
-    private getOrCreateEventCircuitBreaker;
-    /**
-     * Enqueue an event task for processing.
-     *
-     * @param hook - Event hook name
-     * @param args - Event arguments
-     * @param callbacks - Callbacks to execute
-     * @param options - Event options
-     * @returns Task ID
-     */
-    enqueue(task: EventTask): string;
-    enqueue(hook: string, args: unknown, callbacks: ActionCallback[], options: EventOptions): string;
-    /**
-     * Handle backpressure when queue is full.
-     * @returns True if space was made, false if event should be dropped
-     */
-    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
-     */
-    private dequeue;
-    /**
-     * Dequeue a task from a priority queue, respecting partition ordering.
-     *
-     * @param queue - Priority queue to dequeue from
-     * @returns Next task to process, or undefined if all tasks are blocked by partition locks
-     * @internal
-     */
-    private dequeueFromPriority;
-    /**
-     * Execute an event task by running all its callbacks.
-     * Implements circuit breaker protection, retry logic with exponential backoff, and DLQ integration.
-     * Also handles partition ordering by acquiring and releasing partition locks.
-     *
-     * @param task - Event task to execute
-     * @internal
-     */
-    private executeTask;
-    /**
-     * Calculate retry delay based on backoff strategy.
-     *
-     * @param retryCount - Current retry attempt number
-     * @param backoff - Backoff strategy
-     * @param initialDelay - Initial delay in ms
-     * @param maxDelay - Maximum delay in ms
-     * @returns Delay in milliseconds
-     * @internal
-     */
-    private calculateRetryDelay;
-    /**
-     * Re-enqueue a task for retry.
-     *
-     * @param task - Task to retry
-     * @internal
-     */
-    private enqueueRetry;
-    /**
-     * Execute a callback with timeout.
-     *
-     * @param callback - Callback to execute
-     * @param args - Arguments to pass to callback
-     * @param timeoutMs - Timeout in milliseconds
-     * @internal
-     */
-    private executeWithTimeout;
-    /**
-     * Get the current depth of the queue.
-     *
-     * @returns Total number of tasks in the queue
-     */
-    getDepth(): number;
-    /**
-     * Get the depth of a specific priority queue.
-     *
-     * @param priority - Priority level
-     * @returns Number of tasks in the specified priority queue
-     */
-    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.
-     */
-    clear(): void;
-    /**
-     * Get circuit breaker for an event hook.
-     *
-     * @param hook - Event hook name
-     * @returns Circuit breaker instance or undefined
-     * @internal
-     */
-    getCircuitBreaker(hook: string): CircuitBreaker | undefined;
-    /**
-     * Get all circuit breakers.
-     *
-     * @returns Map of circuit breakers keyed by hook name
-     * @internal
-     */
-    getCircuitBreakers(): Map<string, CircuitBreaker>;
-    /**
-     * Reset a circuit breaker for an event hook.
-     *
-     * @param hook - Event hook name
-     * @returns True if reset, false if circuit breaker not found
-     * @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

@@ -1,109 +0,0 @@
-/**
- * @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/IdempotencyCache.d.ts

@@ -1,60 +0,0 @@
-/**
- * Idempotency cache for deduplicating events.
- * Prevents duplicate events from being processed within a configurable TTL window.
- * @internal
- */
-export declare class IdempotencyCache {
-    private cache;
-    private cleanupInterval;
-    private readonly defaultCleanupIntervalMs;
-    constructor();
-    /**
-     * Check if an event with the given idempotency key is a duplicate.
-     * @param key - Idempotency key
-     * @param ttlMs - Time-to-live in milliseconds
-     * @returns True if this is a duplicate, false if it's a new event
-     */
-    isDuplicate(key: string, ttlMs: number): boolean;
-    /**
-     * Record an event in the cache.
-     * @param key - Idempotency key
-     */
-    recordEvent(key: string): void;
-    /**
-     * Remove an entry from the cache.
-     * @param key - Idempotency key
-     * @returns True if entry was removed, false if not found
-     */
-    remove(key: string): boolean;
-    /**
-     * Clear all entries from the cache.
-     */
-    clear(): void;
-    /**
-     * Get the current cache size.
-     * @returns Number of entries in cache
-     */
-    getSize(): number;
-    /**
-     * Start periodic cleanup of expired entries.
-     * @internal
-     */
-    private startCleanup;
-    /**
-     * Stop the periodic cleanup.
-     * @internal
-     */
-    stopCleanup(): void;
-    /**
-     * Clean up expired entries from the cache.
-     * This is called periodically and doesn't use strict TTL checking,
-     * so entries older than a reasonable default (24 hours) are removed.
-     * @internal
-     */
-    private cleanup;
-    /**
-     * Destructor to clean up resources.
-     * @internal
-     */
-    destroy(): void;
-}

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

@@ -1,184 +0,0 @@
-/**
- * @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;
-}