@gravito/echo 3.0.1 → 3.1.0

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

@@ -0,0 +1,202 @@
+import type { Span } from '@opentelemetry/api';
+import type { ActionCallback } from '../HookManager';
+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';
+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
+ *
+ * @internal
+ */
+export declare class EventPriorityQueue implements EventBackend {
+    private highPriority;
+    private normalPriority;
+    private lowPriority;
+    private processing;
+    private taskIdCounter;
+    private dlq?;
+    private persistentDLQHandler?;
+    private config;
+    private processingPartitions;
+    private eventCircuitBreakers;
+    private eventMetrics?;
+    private eventTracing?;
+    private currentDispatchSpan?;
+    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 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;
+    /**
+     * 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): void;
+    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.
+     */
+    private dropOldest;
+    /**
+     * Process the next task in the queue.
+     * Tasks are processed in priority order: high > normal > low
+     *
+     * @internal
+     */
+    private processNext;
+    /**
+     * Dequeue the next task based on priority and partition ordering.
+     *
+     * @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: 'high' | 'normal' | 'low'): number;
+    /**
+     * 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;
+}

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

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

@@ -0,0 +1,14 @@
+/**
+ * Event system exports for async event dispatch.
+ * @packageDocumentation
+ */
+export type { CircuitBreakerOptions } from './CircuitBreaker';
+export { CircuitBreaker, CircuitBreakerState } from './CircuitBreaker';
+export type { DLQEntry, DLQFilter } from './DeadLetterQueue';
+export { DeadLetterQueue } from './DeadLetterQueue';
+export * from './EventBackend';
+export type { EventOptions } from './EventOptions';
+export { DEFAULT_EVENT_OPTIONS } from './EventOptions';
+export { EventPriorityQueue } from './EventPriorityQueue';
+export * from './observability';
+export type { BackpressureStrategy, EventQueueConfig, EventTask } from './types';

package/dist/core/src/events/observability/EventMetrics.d.ts

@@ -0,0 +1,132 @@
+/**
+ * @gravito/core - Event System Metrics
+ *
+ * Manages metric collection for event dispatch and listener execution.
+ */
+import type { EventMetricGauge, EventMetricHistogram } from './metrics-types';
+/**
+ * Event metrics collector for monitoring and observability.
+ *
+ * Collects 6 core metrics:
+ * - Event dispatch latency (Histogram)
+ * - Listener execution time (Histogram)
+ * - Queue depth by priority (Gauge)
+ * - Failure count by error type (Counter)
+ * - Timeout count (Counter)
+ * - Processed event count by status (Counter)
+ *
+ * @public
+ */
+export declare class EventMetrics {
+    private dispatchLatency;
+    private listenerExecutionTime;
+    private queueDepthGauge;
+    private failureCounter;
+    private timeoutCounter;
+    private processedCounter;
+    private circuitBreakerStateGauge;
+    private circuitBreakerTransitionsCounter;
+    private circuitBreakerFailuresCounter;
+    private circuitBreakerSuccessesCounter;
+    private circuitBreakerOpenDurationHistogram;
+    /**
+     * Create a new EventMetrics instance.
+     *
+     * @param registry - MetricsRegistry from @gravito/monitor
+     * @param prefix - Metric name prefix (default: 'gravito_event_')
+     */
+    constructor(registry: any, // MetricsRegistry type
+    prefix?: string);
+    /**
+     * Record event dispatch latency.
+     *
+     * @param eventName - Name of the event
+     * @param priority - Priority level (high, normal, low)
+     * @param seconds - Duration in seconds
+     */
+    recordDispatchLatency(eventName: string, priority: string, seconds: number): void;
+    /**
+     * Record listener execution time.
+     *
+     * @param eventName - Name of the event
+     * @param index - Index of the listener in the callback list
+     * @param seconds - Duration in seconds
+     */
+    recordListenerExecution(eventName: string, index: number, seconds: number): void;
+    /**
+     * Update queue depth gauge for a specific priority.
+     *
+     * @param priority - Priority level (high, normal, low)
+     * @param depth - Current queue depth
+     */
+    updateQueueDepth(priority: string, depth: number): void;
+    /**
+     * Record event processing failure.
+     *
+     * @param eventName - Name of the event
+     * @param errorType - Type of error (e.g., 'TypeError', 'TimeoutError')
+     */
+    recordFailure(eventName: string, errorType: string): void;
+    /**
+     * Record event processing timeout.
+     *
+     * @param eventName - Name of the event
+     */
+    recordTimeout(eventName: string): void;
+    /**
+     * Record processed event (success or failure).
+     *
+     * @param eventName - Name of the event
+     * @param status - Processing status ('success' or 'failure')
+     */
+    recordProcessed(eventName: string, status: 'success' | 'failure'): void;
+    /**
+     * Get reference to dispatch latency histogram.
+     * @internal
+     */
+    getDispatchLatencyHistogram(): EventMetricHistogram;
+    /**
+     * Get reference to listener execution time histogram.
+     * @internal
+     */
+    getListenerExecutionHistogram(): EventMetricHistogram;
+    /**
+     * Get reference to queue depth gauge.
+     * @internal
+     */
+    getQueueDepthGauge(): EventMetricGauge;
+    /**
+     * Record circuit breaker state change.
+     *
+     * @param eventName - Name of the event
+     * @param state - Circuit breaker state (0=CLOSED, 1=HALF_OPEN, 2=OPEN)
+     */
+    recordCircuitBreakerState(eventName: string, state: number): void;
+    /**
+     * Record circuit breaker state transition.
+     *
+     * @param eventName - Name of the event
+     * @param fromState - Previous state
+     * @param toState - New state
+     */
+    recordCircuitBreakerTransition(eventName: string, fromState: string, toState: string): void;
+    /**
+     * Record circuit breaker failure.
+     *
+     * @param eventName - Name of the event
+     */
+    recordCircuitBreakerFailure(eventName: string): void;
+    /**
+     * Record circuit breaker success.
+     *
+     * @param eventName - Name of the event
+     */
+    recordCircuitBreakerSuccess(eventName: string): void;
+    /**
+     * Record circuit breaker OPEN duration.
+     *
+     * @param eventName - Name of the event
+     * @param seconds - Duration in seconds
+     */
+    recordCircuitBreakerOpenDuration(eventName: string, seconds: number): void;
+}

package/dist/core/src/events/observability/EventTracer.d.ts

@@ -0,0 +1,68 @@
+/**
+ * @gravito/core - Event System Tracer
+ *
+ * Manages OpenTelemetry distributed tracing for event dispatch.
+ */
+import type { Span } from '@opentelemetry/api';
+/**
+ * Event tracer for distributed tracing support.
+ *
+ * Integrates with OpenTelemetry to provide:
+ * - Event dispatch tracing
+ * - Listener execution tracing
+ * - Error recording
+ * - Span hierarchy
+ *
+ * @public
+ */
+export declare class EventTracer {
+    private tracer;
+    /**
+     * Create a new EventTracer instance.
+     *
+     * @param tracerName - Name of the tracer (default: '@gravito/core')
+     */
+    constructor(tracerName?: string);
+    /**
+     * Start a span for event dispatch.
+     *
+     * @param eventName - Name of the event
+     * @param callbackCount - Number of callbacks registered for this event
+     * @param priority - Priority level (high, normal, low)
+     * @returns Span for the event dispatch
+     */
+    startDispatchSpan(eventName: string, callbackCount: number, priority: string): Span;
+    /**
+     * Start a span for listener execution.
+     *
+     * @param _parentSpan - Parent span for this listener
+     * @param eventName - Name of the event
+     * @param listenerIndex - Index of the listener in the callback list
+     * @returns Child span for the listener execution
+     */
+    startListenerSpan(_parentSpan: Span, eventName: string, listenerIndex: number): Span;
+    /**
+     * Record an error in the span.
+     *
+     * @param span - Span to record error in
+     * @param error - Error that occurred
+     */
+    recordError(span: Span, error: Error): void;
+    /**
+     * End a span with a specific status.
+     *
+     * @param span - Span to end
+     * @param status - Status ('ok' or 'error')
+     */
+    endSpan(span: Span, status?: 'ok' | 'error'): void;
+    /**
+     * Create a timer span for measuring duration.
+     *
+     * @param eventName - Name of the event
+     * @returns Object with span and duration recording function
+     */
+    startTimer(eventName: string): {
+        span: Span;
+        endTimer: (status?: 'ok' | 'error') => void;
+    };
+}

package/dist/core/src/events/observability/EventTracing.d.ts

@@ -0,0 +1,161 @@
+/**
+ * @gravito/core - Event System Tracing
+ *
+ * 使用 OpenTelemetry API 實現事件系統的分佈式追蹤。
+ * 提供事件派發、監聽器執行與隊列操作的端到端追蹤。
+ */
+import type { Span } from '@opentelemetry/api';
+/**
+ * 事件追蹤配置
+ */
+export interface EventTracingConfig {
+    /** Tracer 名稱 */
+    tracerName?: string;
+    /** 是否記錄詳細的 payload 信息 */
+    capturePayload?: boolean;
+    /** 最大 payload 大小（字節） */
+    maxPayloadSize?: number;
+}
+/**
+ * 事件追蹤管理器
+ *
+ * 提供事件系統的分佈式追蹤能力，包括：
+ * - 事件派發追蹤
+ * - 監聽器執行追蹤
+ * - 隊列操作追蹤
+ * - 異常記錄與追蹤
+ *
+ * @public
+ */
+export declare class EventTracing {
+    private tracer;
+    private config;
+    constructor(config?: EventTracingConfig);
+    /**
+     * 為事件派發創建追蹤 Span
+     *
+     * @param eventName - 事件名稱
+     * @param listenerCount - 監聽器數量
+     * @param priority - 優先級（high, normal, low）
+     * @param payload - 事件負載（可選，用於調試）
+     * @returns Span 實例
+     *
+     * @example
+     * ```typescript
+     * const tracer = new EventTracing()
+     * const span = tracer.startDispatchSpan('order:created', 3, 'high', orderData)
+     * try {
+     *   // 派發事件
+     *   await dispatchEvent()
+     *   tracer.endDispatchSpan(span, 'ok')
+     * } catch (error) {
+     *   tracer.endDispatchSpan(span, 'error', error)
+     * }
+     * ```
+     */
+    startDispatchSpan(eventName: string, listenerCount: number, priority?: 'high' | 'normal' | 'low', payload?: unknown): Span;
+    /**
+     * 為監聽器執行創建追蹤 Span
+     *
+     * @param _parentSpan - 父 Span
+     * @param eventName - 事件名稱
+     * @param listenerName - 監聽器名稱/標識
+     * @param listenerIndex - 監聽器索引
+     * @returns 子 Span 實例
+     */
+    startListenerSpan(_parentSpan: Span, eventName: string, listenerName: string, listenerIndex: number): Span;
+    /**
+     * 為隊列操作創建追蹤 Span
+     *
+     * @param _parentSpan - 父 Span
+     * @param operationType - 操作類型（enqueue, dequeue, requeue）
+     * @param eventName - 事件名稱
+     * @param priority - 優先級
+     * @returns Span 實例
+     */
+    startQueueOperationSpan(_parentSpan: Span, operationType: 'enqueue' | 'dequeue' | 'requeue', eventName: string, priority: 'high' | 'normal' | 'low'): Span;
+    /**
+     * 結束事件派發 Span
+     *
+     * @param span - Span 實例
+     * @param status - 完成狀態（ok, error）
+     * @param error - 如果 status 為 error，傳遞錯誤對象
+     */
+    endDispatchSpan(span: Span, status?: 'ok' | 'error', error?: Error): void;
+    /**
+     * 結束監聽器執行 Span
+     *
+     * @param span - Span 實例
+     * @param status - 完成狀態（ok, error）
+     * @param duration - 執行時間（毫秒）
+     * @param error - 如果發生錯誤，傳遞錯誤對象
+     */
+    endListenerSpan(span: Span, status?: 'ok' | 'error', duration?: number, error?: Error): void;
+    /**
+     * 結束隊列操作 Span
+     *
+     * @param span - Span 實例
+     * @param status - 完成狀態（ok, error）
+     * @param queueDepth - 當前隊列深度
+     * @param error - 如果發生錯誤，傳遞錯誤對象
+     */
+    endQueueOperationSpan(span: Span, status?: 'ok' | 'error', queueDepth?: number, error?: Error): void;
+    /**
+     * 在 Span 中添加自定義屬性
+     *
+     * @param span - Span 實例
+     * @param attributes - 屬性對象
+     */
+    addSpanAttributes(span: Span, attributes: Record<string, string | number | boolean>): void;
+    /**
+     * 在 Span 中添加自定義事件
+     *
+     * @param span - Span 實例
+     * @param eventName - 事件名稱
+     * @param attributes - 事件屬性（可選）
+     */
+    addSpanEvent(span: Span, eventName: string, attributes?: Record<string, string | number | boolean>): void;
+    /**
+     * 記錄異常到 Span
+     *
+     * @param span - Span 實例
+     * @param error - 錯誤對象
+     */
+    recordException(span: Span, error: Error | string): void;
+    /**
+     * 創建定時器 Span（用於測量操作時間）
+     *
+     * @param operationName - 操作名稱
+     * @returns 對象包含 span 和結束函數
+     *
+     * @example
+     * ```typescript
+     * const { span, endTimer } = tracer.startTimer('slow-operation')
+     * try {
+     *   await slowOperation()
+     *   endTimer('ok')
+     * } catch (error) {
+     *   endTimer('error', error)
+     * }
+     * ```
+     */
+    startTimer(operationName: string): {
+        span: Span;
+        endTimer: (status?: 'ok' | 'error', error?: Error) => void;
+    };
+    /**
+     * 獲取 tracer 實例（用於高級用法）
+     *
+     * @returns OpenTelemetry Tracer 實例
+     */
+    getTracer(): import("@opentelemetry/api").Tracer;
+}
+/**
+ * 獲取或創建全局 EventTracing 實例
+ *
+ * @param config - 配置選項
+ * @returns EventTracing 實例
+ *
+ * @public
+ */
+export declare function getEventTracing(config?: EventTracingConfig): EventTracing;