@gravito/core 1.6.1 → 2.0.0

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

package/dist/events/EventOptions.d.ts

@@ -0,0 +1,204 @@
+/**
+ * Event dispatch options for async event handling.
+ * @public
+ */
+export interface EventOptions {
+    /**
+     * Whether to dispatch the event asynchronously.
+     * @default false
+     */
+    async?: boolean;
+    /**
+     * Priority level for event processing.
+     * - 'critical': Immediate processing, bypass queue (< 1ms)
+     * - 'high': High priority events (< 50ms)
+     * - 'normal': Standard events (< 200ms)
+     * - 'low': Non-critical events (< 500ms)
+     * @default 'normal'
+     */
+    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.
+     * @default 5000
+     */
+    timeout?: number;
+    /**
+     * Ordering guarantee strategy.
+     * - 'strict': Global strict ordering (slow, serialized)
+     * - 'partition': Partition-based ordering (recommended, balanced)
+     * - 'none': No ordering guarantee (fastest, parallel)
+     * @default 'none'
+     */
+    ordering?: 'strict' | 'partition' | 'none';
+    /**
+     * Partition key for partition-based ordering.
+     * Events with the same partition key are processed in order.
+     * Only used when ordering is 'partition'.
+     * @example 'order:123' or 'user:456'
+     */
+    partitionKey?: string;
+    /**
+     * Idempotency key for deduplication.
+     * Events with the same idempotency key within the TTL window
+     * will be processed only once.
+     * @example 'order:123:created'
+     */
+    idempotencyKey?: string;
+    /**
+     * Time-to-live for idempotency key in milliseconds.
+     * @default 3600000 (1 hour)
+     */
+    ttl?: number;
+    /**
+     * Retry policy for failed event processing.
+     */
+    retry?: {
+        /**
+         * Maximum number of retry attempts.
+         * @default 0
+         */
+        maxRetries?: number;
+        /**
+         * Backoff strategy for retries.
+         * - 'exponential': Delay doubles with each retry (1s, 2s, 4s, 8s...)
+         * - 'linear': Fixed delay between retries
+         * @default 'exponential'
+         */
+        backoff?: 'exponential' | 'linear';
+        /**
+         * Initial delay in milliseconds before first retry.
+         * @default 1000
+         */
+        initialDelayMs?: number;
+        /**
+         * Maximum delay in milliseconds between retries.
+         * @default 30000
+         */
+        maxDelayMs?: number;
+        /**
+         * Whether to send failed events to Dead Letter Queue after max retries.
+         * @default false
+         */
+        dlqAfterMaxRetries?: boolean;
+    };
+    /**
+     * Circuit breaker options for this event.
+     */
+    circuitBreaker?: {
+        /**
+         * Number of consecutive failures before opening the circuit.
+         * @default 5
+         */
+        failureThreshold?: number;
+        /**
+         * Time in milliseconds to wait before attempting to close the circuit.
+         * @default 30000
+         */
+        resetTimeout?: number;
+        /**
+         * Number of test requests to allow in half-open state.
+         * @default 3
+         */
+        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.
+ * @internal
+ */
+export declare const DEFAULT_EVENT_OPTIONS: Required<EventOptions>;

package/dist/events/EventPriorityQueue.d.ts

@@ -0,0 +1,63 @@
+import type { Span } from '@opentelemetry/api';
+import type { ActionCallback } from '../HookManager';
+import type { BackpressureManager } from './BackpressureManager';
+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.
+ *
+ * Composed of:
+ * - {@link QueueCore}: queue data structures and backpressure logic
+ * - {@link TaskExecutor}: task execution, retry, circuit breaker, DLQ
+ *
+ * @internal
+ */
+export declare class EventPriorityQueue implements EventBackend {
+    private queueCore;
+    private taskExecutor;
+    private processing;
+    private workerPool?;
+    constructor(config?: EventQueueConfig);
+    setDeadLetterQueue(dlq: DeadLetterQueue): void;
+    setPersistentDLQHandler(handler: (hook: string, args: unknown, options: EventOptions, error: Error, retryCount: number, firstFailedAt: number) => Promise<void>): void;
+    setEventMetrics(metrics: EventMetrics): void;
+    setOTelEventMetrics(metrics: OTelEventMetrics): void;
+    setPriorityStatistics(stats: PriorityStatistics): void;
+    getPriorityStatistics(): PriorityStatistics | undefined;
+    setEventTracing(tracing: EventTracing): void;
+    setCurrentDispatchSpan(span: Span | undefined): void;
+    getCurrentDispatchSpan(): Span | undefined;
+    setRetryScheduler(scheduler: RetryScheduler): void;
+    getRetryScheduler(): RetryScheduler | undefined;
+    getCircuitBreaker(hook: string): import("./CircuitBreaker").CircuitBreaker;
+    getCircuitBreakers(): Map<string, import("./CircuitBreaker").CircuitBreaker>;
+    resetCircuitBreaker(hook: string): boolean;
+    setWorkerPool(pool: WorkerPool): void;
+    getWorkerPool(): WorkerPool | undefined;
+    getBackpressureManager(): BackpressureManager | undefined;
+    enqueue(task: EventTask): string;
+    enqueue(hook: string, args: unknown, callbacks: ActionCallback[], options: EventOptions): string;
+    enqueueBatch(tasks: EventTask[]): string[];
+    getDepth(): number;
+    getDepthByPriority(priority: 'critical' | 'high' | 'normal' | 'low'): number;
+    getQueueDepthByPriority(): MultiPriorityQueueDepth;
+    clear(): void;
+    dequeue(): EventTask | undefined;
+    private processNext;
+}

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