@gravito/ripple 3.1.0 → 4.0.1

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

@@ -0,0 +1,215 @@
+/**
+ * @gravito/core - Event System Backpressure Management
+ *
+ * Implements a backpressure management system to prevent high-priority events
+ * from starving low-priority events when the queue is under resource constraints.
+ *
+ * 背壓管理器：在資源受限時進行智慧型流量控制，防止優先級飢餓。
+ *
+ * FS-103 增強：
+ * - 多優先級隊列深度監控
+ * - 背壓反饋迴路支持
+ * - 智能 DLQ 路由決策
+ */
+import type { DeadLetterDecision, MultiPriorityQueueDepth } from './types';
+/**
+ * 背壓狀態枚舉。
+ *
+ * 狀態轉換：Normal → Warning → Critical → Overflow
+ * 恢復方向：遲滯設計（需降至觸發閾值的 80%）
+ *
+ * @public
+ */
+export declare enum BackpressureState {
+    /** 正常運作，無背壓 */
+    NORMAL = "NORMAL",
+    /** 警告狀態，開始限制低優先級事件 */
+    WARNING = "WARNING",
+    /** 危急狀態，僅允許高優先級事件 */
+    CRITICAL = "CRITICAL",
+    /** 溢位狀態，全部拒絕 */
+    OVERFLOW = "OVERFLOW"
+}
+/**
+ * 背壓配置選項。
+ *
+ * @public
+ */
+export interface BackpressureConfig {
+    /** 是否啟用背壓管理器（預設 true） */
+    enabled?: boolean;
+    /** 總隊列深度限制（預設無限） */
+    maxQueueSize?: number;
+    /** 分優先級隊列深度限制 */
+    maxSizeByPriority?: {
+        critical?: number;
+        high?: number;
+        normal?: number;
+        low?: number;
+    };
+    /** 每秒最大入隊速率（events/sec，預設無限） */
+    maxEnqueueRate?: number;
+    /** 速率限制滑動視窗大小（ms，預設 1000） */
+    rateLimitWindowMs?: number;
+    /** 背壓狀態閾值（佔 maxQueueSize 的百分比） */
+    thresholds?: {
+        /** WARNING 觸發百分比（預設 0.6 = 60%） */
+        warning?: number;
+        /** CRITICAL 觸發百分比（預設 0.85 = 85%） */
+        critical?: number;
+        /** OVERFLOW 觸發百分比（預設 1.0 = 100%） */
+        overflow?: number;
+    };
+    /** 被拒絕事件的處理策略（預設 'drop-with-callback'） */
+    rejectionPolicy?: 'throw' | 'drop-silent' | 'drop-with-callback';
+    /** 當 rejectionPolicy 為 'drop-with-callback' 時的回呼 */
+    onRejected?: (eventName: string, priority: string, reason: string) => void;
+    /** 背壓狀態變更回呼 */
+    onStateChange?: (from: BackpressureState, to: BackpressureState) => void;
+    /** 低優先級事件在 WARNING 狀態下的延遲入隊時間（ms，預設 100） */
+    lowPriorityDelayMs?: number;
+    /** 是否啟用優先級反轉防護（預設 true） */
+    enableStarvationProtection?: boolean;
+    /** 低優先級事件最大等待時間，超過則提升優先級（ms，預設 5000） */
+    starvationTimeoutMs?: number;
+    /** 當進入 OVERFLOW 狀態時，是否將被拒絕事件路由到 DLQ（預設 false） */
+    dlqOnOverflow?: boolean;
+    /** OVERFLOW 時的重試策略（預設 'dlq-only'） */
+    overflowRetryStrategy?: 'immediate' | 'delayed' | 'dlq-only';
+    /** OVERFLOW 延遲重試的基礎延遲時間（ms，預設 5000） */
+    overflowRetryDelayMs?: number;
+}
+/**
+ * 背壓決策結果。
+ *
+ * @public
+ */
+export interface BackpressureDecision {
+    /** 是否允許入隊 */
+    allowed: boolean;
+    /** 拒絕原因（若不允許） */
+    reason?: string;
+    /** 是否需要延遲入隊 */
+    delayed?: boolean;
+    /** 延遲時間（ms） */
+    delayMs?: number;
+    /** 建議降級後的優先級（若降級） */
+    degradedPriority?: 'high' | 'normal' | 'low';
+    /** 是否是由於 OVERFLOW 狀態被拒絕 */
+    isOverflow?: boolean;
+    /** OVERFLOW 時的重試策略建議（'immediate'、'delayed'、'dlq-only'） */
+    retryStrategy?: 'immediate' | 'delayed' | 'dlq-only';
+}
+/**
+ * 背壓指標快照。
+ *
+ * @public
+ */
+export interface BackpressureMetricsSnapshot {
+    state: BackpressureState;
+    totalDepth: number;
+    depthByPriority: {
+        critical: number;
+        high: number;
+        normal: number;
+        low: number;
+    };
+    enqueueRate: number;
+    rejectedCount: number;
+    degradedCount: number;
+    stateTransitions: number;
+    dlqRouteCount?: number;
+    windowAdjustmentCount?: number;
+}
+/**
+ * 背壓管理器。
+ *
+ * 根據隊列深度、速率、優先級等因素，決定是否允許新事件入隊，
+ * 以及是否需要降級優先級或延遲入隊。
+ *
+ * @public
+ */
+export declare class BackpressureManager {
+    private enabled;
+    private config;
+    private onRejected?;
+    private onStateChange?;
+    private state;
+    private rejectedCount;
+    private degradedCount;
+    private stateTransitions;
+    private rateCounter;
+    private depthByPriority;
+    private windowAdjustmentHistory;
+    private dlqRouteCount;
+    constructor(config?: BackpressureConfig);
+    /**
+     * 評估是否允許新事件入隊。
+     *
+     * @param eventName 事件名稱
+     * @param priority 事件優先級
+     * @param queueDepth 當前隊列深度
+     * @param depthByPriority 分優先級隊列深度
+     * @returns 背壓決策結果
+     */
+    evaluate(eventName: string, priority: 'critical' | 'high' | 'normal' | 'low', queueDepth: number, depthByPriority: {
+        critical: number;
+        high: number;
+        normal: number;
+        low: number;
+    }): BackpressureDecision;
+    /**
+     * 獲取當前背壓狀態。
+     */
+    getState(): BackpressureState;
+    /**
+     * 獲取背壓指標快照。
+     */
+    getMetrics(): BackpressureMetricsSnapshot;
+    /**
+     * 重置背壓管理器狀態。
+     */
+    reset(): void;
+    /**
+     * 同步隊列深度（由 EventPriorityQueue 調用）。
+     * FS-103：多優先級隊列深度監控
+     */
+    updateQueueDepth(depths: MultiPriorityQueueDepth): void;
+    /**
+     * 獲取各優先級的隊列深度。
+     * FS-103：提供實時隊列深度快照
+     */
+    getQueueDepthByPriority(): MultiPriorityQueueDepth;
+    /**
+     * 獲取總隊列深度。
+     */
+    getTotalQueueDepth(): number;
+    /**
+     * 接收來自 AggregationWindow 的窗口調整通知。
+     * FS-103：背壓反饋迴路
+     */
+    notifyWindowAdjustment(oldWindowMs: number, newWindowMs: number): void;
+    /**
+     * 檢查是否可以從 CRITICAL 或更高級別降級。
+     * FS-103：自動狀態恢復機制
+     */
+    private checkStateRecovery;
+    /**
+     * 決定是否應該將事件路由到死信隊列。
+     * FS-103：智能 DLQ 路由決策
+     */
+    makeDeadLetterDecision(_eventName: string, priority: 'critical' | 'high' | 'normal' | 'low'): DeadLetterDecision;
+    /**
+     * 更新背壓狀態。
+     * 使用遲滯設計（80% 回復比例）避免邊界震盪。
+     */
+    private updateState;
+    /**
+     * 執行狀態轉換。
+     */
+    private transitionTo;
+    /**
+     * 建立決策結果並記錄拒絕。
+     */
+    private createDecision;
+}

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

@@ -0,0 +1,229 @@
+/**
+ * Circuit Breaker state enum.
+ * @public
+ */
+export declare enum CircuitBreakerState {
+    CLOSED = "CLOSED",
+    OPEN = "OPEN",
+    HALF_OPEN = "HALF_OPEN"
+}
+/**
+ * Circuit Breaker metrics snapshot.
+ * @public
+ */
+export interface CircuitBreakerMetrics {
+    /**
+     * Current state of the circuit breaker
+     */
+    state: CircuitBreakerState;
+    /**
+     * Number of failures in the current window
+     */
+    failures: number;
+    /**
+     * Number of successes in the current window
+     */
+    successes: number;
+    /**
+     * Timestamp of the last failure
+     */
+    lastFailureAt?: Date;
+    /**
+     * Timestamp of the last success
+     */
+    lastSuccessAt?: Date;
+    /**
+     * Timestamp when the circuit was opened
+     */
+    openedAt?: Date;
+    /**
+     * Total requests processed
+     */
+    totalRequests: number;
+    /**
+     * Total failures recorded
+     */
+    totalFailures: number;
+    /**
+     * Total successes recorded
+     */
+    totalSuccesses: number;
+}
+/**
+ * Circuit Breaker metrics recorder interface.
+ * @public
+ */
+export interface CircuitBreakerMetricsRecorder {
+    /**
+     * Record current state of the circuit breaker.
+     * @param eventName - Name of the event
+     * @param state - State as number (0=CLOSED, 1=HALF_OPEN, 2=OPEN)
+     */
+    recordState: (eventName: string, state: number) => void;
+    /**
+     * Record state transition.
+     */
+    recordTransition: (eventName: string, fromState: string, toState: string) => void;
+    /**
+     * Record a failure.
+     */
+    recordFailure: (eventName: string) => void;
+    /**
+     * Record a success.
+     */
+    recordSuccess: (eventName: string) => void;
+    /**
+     * Record OPEN state duration.
+     */
+    recordOpenDuration: (eventName: string, seconds: number) => void;
+}
+/**
+ * Circuit Breaker configuration options.
+ * @public
+ */
+export interface CircuitBreakerOptions {
+    /**
+     * Number of consecutive failures before opening the circuit.
+     * @default 5
+     */
+    failureThreshold?: number;
+    /**
+     * Time in milliseconds to wait before attempting to close the circuit (move to HALF_OPEN).
+     * @default 30000
+     */
+    resetTimeout?: number;
+    /**
+     * Number of test requests to allow given the circuit is in HALF_OPEN state.
+     * If these succeed, the circuit closes. If any fail, it opens again.
+     * @default 3
+     */
+    halfOpenRequests?: number;
+    /**
+     * Number of successes required in HALF_OPEN state to close the circuit.
+     * @default 2
+     */
+    successThreshold?: number;
+    /**
+     * Time in milliseconds for the sliding window to track failures.
+     * Failures outside this window are not counted.
+     * @default 60000
+     */
+    windowSize?: number;
+    /**
+     * Enable or disable the circuit breaker.
+     * @default true
+     */
+    enabled?: boolean;
+    /**
+     * Callback when circuit opens.
+     */
+    onOpen?: (name?: string) => void;
+    /**
+     * Callback when circuit moves to half-open.
+     */
+    onHalfOpen?: (name?: string) => void;
+    /**
+     * Callback when circuit closes.
+     */
+    onClose?: (name?: string) => void;
+    /**
+     * Metrics recorder for recording circuit breaker events.
+     * Optional - if not provided, metrics will not be recorded.
+     */
+    metricsRecorder?: CircuitBreakerMetricsRecorder | undefined;
+}
+/**
+ * Required Circuit Breaker configuration (with defaults applied).
+ * @internal
+ */
+export interface RequiredCircuitBreakerOptions extends Required<Omit<CircuitBreakerOptions, 'metricsRecorder'>> {
+    metricsRecorder?: CircuitBreakerMetricsRecorder;
+}
+/**
+ * Circuit Breaker implementation for fault tolerance.
+ *
+ * Prevents cascading failures by stopping execution of a failing operation
+ * for a specified period after a threshold of failures is reached.
+ *
+ * Supports sliding window algorithm, enabling/disabling, and detailed metrics.
+ *
+ * @public
+ */
+export declare class CircuitBreaker {
+    private state;
+    private failureCount;
+    private successCount;
+    private name;
+    private config;
+    private metricsRecorder?;
+    private lastFailureAt?;
+    private lastSuccessAt?;
+    private openedAt?;
+    private totalRequests;
+    private totalFailures;
+    private totalSuccesses;
+    private halfOpenAttempts;
+    /**
+     * Create a new Circuit Breaker.
+     *
+     * Supports two signatures for backward compatibility:
+     * - CircuitBreaker(options?: CircuitBreakerOptions) - anonymous breaker
+     * - CircuitBreaker(name: string, options?: CircuitBreakerOptions) - named breaker
+     *
+     * @param nameOrOptions - Circuit breaker name or options
+     * @param maybeOptions - Options (used when first param is a string)
+     */
+    constructor(nameOrOptions?: string | CircuitBreakerOptions, maybeOptions?: CircuitBreakerOptions);
+    /**
+     * Execute an operation through the circuit breaker.
+     *
+     * @param operation - Async operation to execute
+     * @returns Operation result
+     * @throws Error if circuit is open or operation fails
+     */
+    execute<T>(operation: () => Promise<T>): Promise<T>;
+    /**
+     * Check if the circuit breaker is currently OPEN.
+     */
+    isOpen(): boolean;
+    /**
+     * Check if the circuit breaker is currently HALF_OPEN.
+     */
+    isHalfOpen(): boolean;
+    /**
+     * Check if the circuit breaker is currently CLOSED.
+     */
+    isClosed(): boolean;
+    /**
+     * Get current state of the circuit breaker.
+     */
+    getState(): CircuitBreakerState;
+    /**
+     * Get failure count (deprecated, use getMetrics for complete information).
+     */
+    getFailureCount(): number;
+    /**
+     * Get the name of this circuit breaker.
+     */
+    getName(): string;
+    /**
+     * Get detailed metrics snapshot of the circuit breaker.
+     */
+    getMetrics(): CircuitBreakerMetrics;
+    /**
+     * Manually reset the circuit breaker to CLOSED state.
+     */
+    reset(): void;
+    /**
+     * Forcefully reset the circuit breaker (alias for reset).
+     */
+    manualReset(): void;
+    /**
+     * Check for automatic state transitions based on time and sliding window.
+     */
+    checkStateTransition(): void;
+    private onSuccess;
+    private onFailure;
+    private transitionTo;
+    private stateToNumber;
+}

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

@@ -0,0 +1,219 @@
+import type { EventOptions } from './EventOptions';
+/**
+ * Source of DLQ entry - reason why event entered the DLQ.
+ * @public
+ */
+export type DLQEntrySource = 'retry_exhausted' | 'circuit_breaker' | 'backpressure_overflow' | 'manual';
+/**
+ * Dead Letter Queue entry representing a failed event.
+ * @public
+ */
+export interface DLQEntry {
+    /**
+     * Unique identifier for this DLQ entry.
+     */
+    id: string;
+    /**
+     * Event hook name.
+     */
+    eventName: string;
+    /**
+     * Event payload.
+     */
+    payload: unknown;
+    /**
+     * Event options used when dispatching.
+     */
+    options: EventOptions;
+    /**
+     * Error that caused the event to fail.
+     */
+    error: {
+        message: string;
+        stack?: string;
+        code?: string;
+    };
+    /**
+     * Number of retry attempts made.
+     */
+    retryCount: number;
+    /**
+     * Timestamp when the event first failed.
+     */
+    firstFailedAt: number;
+    /**
+     * Timestamp when the event was added to DLQ.
+     */
+    failedAt: number;
+    /**
+     * Timestamp when the event was last retried (if any).
+     */
+    lastRetriedAt?: number;
+    /**
+     * Source of the DLQ entry - reason why event entered the DLQ.
+     */
+    source: DLQEntrySource;
+}
+/**
+ * Filter options for querying DLQ entries.
+ * @public
+ */
+export interface DLQFilter {
+    /**
+     * Filter by event name.
+     */
+    eventName?: string;
+    /**
+     * Filter by entries failed after this timestamp.
+     */
+    from?: number;
+    /**
+     * Filter by entries failed before this timestamp.
+     */
+    to?: number;
+    /**
+     * Maximum number of entries to return.
+     */
+    limit?: number;
+}
+/**
+ * Callback type for DLQ entry events.
+ * @public
+ */
+export type DLQEntryCallback = (entry: DLQEntry) => void;
+/**
+ * Dead Letter Queue Manager for handling failed events.
+ *
+ * The DLQ stores events that have exceeded their retry limit,
+ * allowing for manual inspection, reprocessing, or analysis.
+ *
+ * @public
+ */
+export declare class DeadLetterQueue {
+    private entries;
+    private entryIdCounter;
+    private maxEntries?;
+    private onEntryAdded?;
+    private onEntryRemoved?;
+    /**
+     * Create a new DeadLetterQueue instance.
+     *
+     * @param maxEntries - Maximum number of entries to keep (optional, no limit if not set)
+     */
+    constructor(maxEntries?: number);
+    /**
+     * Add a failed event to the Dead Letter Queue.
+     *
+     * @param eventName - Name of the failed event
+     * @param payload - Event payload
+     * @param options - Event options
+     * @param error - Error that caused the failure
+     * @param retryCount - Number of retry attempts made
+     * @param firstFailedAt - Timestamp of first failure
+     * @param source - Source of the DLQ entry (default: 'retry_exhausted')
+     * @returns DLQ entry ID
+     */
+    add(eventName: string, payload: unknown, options: EventOptions, error: Error, retryCount: number, firstFailedAt: number, source?: DLQEntrySource): string;
+    /**
+     * Get a specific DLQ entry by ID.
+     *
+     * @param entryId - DLQ entry ID
+     * @returns DLQ entry or undefined if not found
+     */
+    get(entryId: string): DLQEntry | undefined;
+    /**
+     * List DLQ entries with optional filtering.
+     *
+     * @param filter - Filter options
+     * @returns Array of DLQ entries
+     */
+    list(filter?: DLQFilter): DLQEntry[];
+    /**
+     * Delete a DLQ entry.
+     *
+     * @param entryId - DLQ entry ID
+     * @returns True if entry was deleted, false if not found
+     */
+    delete(entryId: string): boolean;
+    /**
+     * Delete all DLQ entries matching the filter.
+     *
+     * @param filter - Filter options
+     * @returns Number of entries deleted
+     */
+    deleteAll(filter?: DLQFilter): number;
+    /**
+     * Get the total number of entries in the DLQ.
+     *
+     * @returns Total entry count
+     */
+    getCount(): number;
+    /**
+     * Get the count of entries for a specific event.
+     *
+     * @param eventName - Event name
+     * @returns Entry count for the event
+     */
+    getCountByEvent(eventName: string): number;
+    /**
+     * Clear all entries from the DLQ.
+     */
+    clear(): void;
+    /**
+     * Update the last retried timestamp for an entry.
+     *
+     * @param entryId - DLQ entry ID
+     * @internal
+     */
+    updateLastRetried(entryId: string): void;
+    /**
+     * Evict the oldest entry from the DLQ.
+     * Used when capacity limit is reached.
+     *
+     * @private
+     */
+    private evictOldest;
+    /**
+     * Get the oldest entry in the DLQ.
+     *
+     * @returns Oldest DLQ entry or undefined if empty
+     */
+    getOldestEntry(): DLQEntry | undefined;
+    /**
+     * Get the newest entry in the DLQ.
+     *
+     * @returns Newest DLQ entry or undefined if empty
+     */
+    getNewestEntry(): DLQEntry | undefined;
+    /**
+     * Get all entries grouped by source.
+     *
+     * @param source - Source to filter by
+     * @returns Array of entries matching the source
+     */
+    getEntriesBySource(source: DLQEntrySource): DLQEntry[];
+    /**
+     * Set callback for when an entry is added to the DLQ.
+     *
+     * @param callback - Callback function or undefined to clear
+     */
+    setOnEntryAdded(callback?: DLQEntryCallback): void;
+    /**
+     * Set callback for when an entry is removed from the DLQ.
+     *
+     * @param callback - Callback function or undefined to clear
+     */
+    setOnEntryRemoved(callback?: DLQEntryCallback): void;
+    /**
+     * Get the maximum number of entries allowed in the DLQ.
+     *
+     * @returns Max entries limit or undefined if no limit
+     */
+    getMaxEntries(): number | undefined;
+    /**
+     * Set the maximum number of entries allowed in the DLQ.
+     *
+     * @param maxEntries - Maximum entries or undefined to remove limit
+     */
+    setMaxEntries(maxEntries?: number): void;
+}

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

@@ -0,0 +1,12 @@
+import type { EventTask } from './types';
+/**
+ * Interface for event dispatch backends.
+ */
+export interface EventBackend {
+    /**
+     * Enqueue an event for processing.
+     * @param task - The event task to process
+     * @returns Task ID or 'dropped' if event was rejected (can be async for some backends)
+     */
+    enqueue(task: EventTask): string | Promise<void>;
+}