@gravito/radiance 1.0.3 → 1.0.5

package/dist/core/src/observability/contracts.d.ts

@@ -0,0 +1,137 @@
+/**
+ * @gravito/core - Observability Contracts
+ *
+ * Abstract interfaces for observability providers, decoupling core from OpenTelemetry.
+ * This allows @gravito/monitor to provide complete OTel implementations while core
+ * remains dependency-free.
+ */
+/**
+ * Represents a tracing span for distributed tracing.
+ * @public
+ */
+export interface TracingSpan {
+    /**
+     * Add an event to the span.
+     *
+     * @param name - Event name
+     * @param attributes - Optional event attributes
+     */
+    addEvent(name: string, attributes?: Record<string, string | number>): void;
+    /**
+     * Set the span status.
+     *
+     * @param code - Status code: 'OK' or 'ERROR'
+     * @param message - Optional error message
+     */
+    setStatus(code: 'OK' | 'ERROR', message?: string): void;
+    /**
+     * End the span.
+     */
+    end(): void;
+}
+/**
+ * Event tracing provider for distributed tracing of events.
+ * @public
+ */
+export interface EventTracingProvider {
+    /**
+     * Start a new tracing span for an event.
+     *
+     * @param name - Span name
+     * @returns A TracingSpan instance
+     */
+    startSpan(name: string): TracingSpan;
+    /**
+     * Record custom metrics for an event.
+     *
+     * @param eventName - Name of the event
+     * @param metrics - Metrics to record (e.g., duration, count)
+     */
+    recordMetrics(eventName: string, metrics: Record<string, number>): void;
+}
+/**
+ * Event metrics recorder for monitoring event processing.
+ * @public
+ */
+export interface EventMetricsRecorder {
+    /**
+     * Record event processing completion.
+     *
+     * @param eventName - Name of the event
+     * @param duration - Processing duration in milliseconds
+     * @param success - Whether processing was successful
+     */
+    recordEventProcessed(eventName: string, duration: number, success: boolean): void;
+    /**
+     * Record event publication.
+     *
+     * @param eventName - Name of the event
+     */
+    recordEventPublished(eventName: string): void;
+    /**
+     * Record event processing error.
+     *
+     * @param eventName - Name of the event
+     * @param error - The error that occurred
+     */
+    recordEventError(eventName: string, error: Error): void;
+}
+/**
+ * Worker metrics provider for monitoring worker pool operations.
+ * @public
+ */
+export interface WorkerMetricsProvider {
+    /**
+     * Record worker pool startup.
+     *
+     * @param poolId - ID of the worker pool
+     */
+    recordWorkerStartup(poolId: string): void;
+    /**
+     * Record task execution in a worker pool.
+     *
+     * @param poolId - ID of the worker pool
+     * @param duration - Task duration in milliseconds
+     * @param success - Whether task execution was successful
+     */
+    recordTaskExecution(poolId: string, duration: number, success: boolean): void;
+    /**
+     * Record worker pool error.
+     *
+     * @param poolId - ID of the worker pool
+     * @param error - The error that occurred
+     */
+    recordWorkerError(poolId: string, error: Error): void;
+}
+/**
+ * Main observability provider interface combining all observability capabilities.
+ * @public
+ */
+export interface ObservabilityProvider {
+    /**
+     * Event tracing provider (optional).
+     */
+    eventTracing?: EventTracingProvider;
+    /**
+     * Event metrics recorder (optional).
+     */
+    eventMetrics?: EventMetricsRecorder;
+    /**
+     * Worker metrics provider (optional).
+     */
+    workerMetrics?: WorkerMetricsProvider;
+    /**
+     * General tracing provider (optional).
+     */
+    tracing?: {
+        startSpan(name: string): TracingSpan;
+    };
+}
+/**
+ * Create a no-op observability provider.
+ * Used by default when no observability implementation is provided.
+ *
+ * @returns An ObservabilityProvider with all no-op implementations
+ * @internal
+ */
+export declare function createNoOpObservabilityProvider(): ObservabilityProvider;

package/dist/core/src/reliability/DeadLetterQueueManager.d.ts

@@ -0,0 +1,349 @@
+/**
+ * @gravito/core - Dead Letter Queue Manager
+ *
+ * 管理失敗事件的持久化存儲
+ * 支持 CRUD、重新入隊、批量重試和統計功能
+ */
+import type { EventOptions } from '../events/EventOptions';
+import type { RetryPolicy } from './RetryPolicy';
+/**
+ * DLQ 事件的數據庫記錄
+ */
+export interface DLQRecord {
+    id: number;
+    dlq_id: string;
+    event_name: string;
+    event_payload: unknown;
+    event_options: unknown;
+    attempt_count: number;
+    max_retries: number;
+    next_retry_at: string | null;
+    last_error: unknown;
+    status: 'pending' | 'requeued' | 'resolved' | 'abandoned';
+    resolution_notes: string | null;
+    failed_at: string;
+    created_at: string;
+    updated_at: string;
+}
+/**
+ * DLQ 事件查詢過濾選項（for DeadLetterQueueManager）
+ */
+export interface DLQManagerFilter {
+    /** 按事件名稱篩選 */
+    eventName?: string;
+    /** 按狀態篩選 */
+    status?: 'pending' | 'requeued' | 'resolved' | 'abandoned';
+    /** 開始時間 */
+    from?: Date;
+    /** 結束時間 */
+    to?: Date;
+    /** 結果數量限制 */
+    limit?: number;
+    /** 分頁偏移 */
+    offset?: number;
+}
+/**
+ * DLQ 統計信息
+ */
+export interface DLQStats {
+    /** 事件總數 */
+    total: number;
+    /** 按事件名稱的統計 */
+    byEvent: Record<string, number>;
+    /** 按狀態的統計 */
+    byStatus: Record<string, number>;
+}
+/**
+ * Dead Letter Queue 管理器
+ *
+ * 負責管理失敗事件的持久化存儲，支持：
+ * - 自動將失敗事件移至 DLQ
+ * - 查詢和篩選 DLQ 事件
+ * - 重新入隊單個或批量事件
+ * - 標記事件為已解決或已放棄
+ * - 查看統計信息
+ *
+ * @example
+ * ```typescript
+ * const db = container.make('db') as any
+ * const dlqManager = new DeadLetterQueueManager(db)
+ *
+ * // 將失敗事件移至 DLQ
+ * const dlqId = await dlqManager.moveToDlq(
+ *   'order:created',
+ *   { orderId: '123' },
+ *   { retry: {...} },
+ *   error,
+ *   3
+ * )
+ *
+ * // 查詢 DLQ 事件
+ * const events = await dlqManager.list({ event: 'order:created', status: 'pending' })
+ *
+ * // 重新入隊
+ * await dlqManager.requeue(dlqId)
+ *
+ * // 批量重試
+ * const result = await dlqManager.retryBatch({ eventName: 'order:created' })
+ *
+ * // 統計
+ * const stats = await dlqManager.getStats()
+ * ```
+ */
+export declare class DeadLetterQueueManager {
+    private db;
+    private retryEngine;
+    constructor(db: any);
+    /**
+     * 將失敗事件移至死信隊列
+     *
+     * @param eventName - 事件名稱
+     * @param payload - 事件負載
+     * @param options - 事件選項
+     * @param error - 導致失敗的錯誤
+     * @param attemptCount - 當前嘗試次數
+     * @param retryPolicy - 重試策略配置
+     * @returns DLQ 記錄的 UUID
+     *
+     * @example
+     * ```typescript
+     * const dlqId = await dlqManager.moveToDlq(
+     *   'order:created',
+     *   { orderId: 'ORD-123' },
+     *   { retry: { maxRetries: 3, backoff: 'exponential' } },
+     *   new Error('Service unavailable'),
+     *   3,
+     *   { maxRetries: 3, backoff: 'exponential', initialDelayMs: 1000, maxDelayMs: 30000 }
+     * )
+     * ```
+     */
+    moveToDlq(eventName: string, payload: unknown, options: EventOptions, error: Error, attemptCount: number, retryPolicy?: RetryPolicy): Promise<string>;
+    /**
+     * 按 DLQ ID 獲取單個事件
+     *
+     * @param dlqId - DLQ 事件的 UUID
+     * @returns DLQ 記錄，若不存在則返回 undefined
+     *
+     * @example
+     * ```typescript
+     * const event = await dlqManager.getById('550e8400-e29b-41d4-a716-446655440000')
+     * if (event) {
+     *   console.log(event.event_name, event.status)
+     * }
+     * ```
+     */
+    getById(dlqId: string): Promise<DLQRecord | undefined>;
+    /**
+     * 查詢 DLQ 事件
+     *
+     * @param filter - 查詢過濾條件
+     * @returns DLQ 記錄列表（按失敗時間倒序）
+     *
+     * @example
+     * ```typescript
+     * // 查詢特定事件的待處理事件
+     * const events = await dlqManager.list({
+     *   eventName: 'order:created',
+     *   status: 'pending',
+     *   limit: 50
+     * })
+     *
+     * // 查詢時間範圍內的所有失敗事件
+     * const eventsInRange = await dlqManager.list({
+     *   from: new Date('2026-02-01'),
+     *   to: new Date('2026-02-03'),
+     *   limit: 100
+     * })
+     * ```
+     */
+    list(filter?: DLQManagerFilter): Promise<DLQRecord[]>;
+    /**
+     * 重新入隊單個 DLQ 事件
+     *
+     * 重新入隊不會自動派發事件，而是標記狀態為 'requeued'
+     * 實際的事件派發應由調用者負責處理
+     *
+     * @param dlqId - DLQ 事件的 UUID
+     * @throws 如果事件不存在
+     *
+     * @example
+     * ```typescript
+     * const event = await dlqManager.getById(dlqId)
+     * if (event) {
+     *   // 由調用者決定如何派發事件
+     *   await eventSystem.doActionAsync(
+     *     event.event_name,
+     *     event.event_payload,
+     *     event.event_options
+     *   )
+     *
+     *   // 標記為已重新入隊
+     *   await dlqManager.requeue(dlqId)
+     * }
+     * ```
+     */
+    requeue(dlqId: string): Promise<void>;
+    /**
+     * 批量重新入隊 DLQ 事件
+     *
+     * @param filter - 查詢過濾條件
+     * @returns 包含處理結果的統計對象
+     *
+     * @example
+     * ```typescript
+     * const result = await dlqManager.retryBatch({
+     *   eventName: 'order:created',
+     *   status: 'pending'
+     * })
+     *
+     * console.log(`Success: ${result.succeeded}, Failed: ${result.failed}`)
+     * ```
+     */
+    retryBatch(filter?: DLQManagerFilter): Promise<{
+        total: number;
+        succeeded: number;
+        failed: number;
+    }>;
+    /**
+     * 標記 DLQ 事件為已解決
+     *
+     * @param dlqId - DLQ 事件的 UUID
+     * @param notes - 解決說明
+     *
+     * @example
+     * ```typescript
+     * await dlqManager.resolve(dlqId, 'Manual fix applied: Database issue resolved')
+     * ```
+     */
+    resolve(dlqId: string, notes?: string): Promise<void>;
+    /**
+     * 放棄 DLQ 事件（不再重試）
+     *
+     * @param dlqId - DLQ 事件的 UUID
+     * @param reason - 放棄原因
+     *
+     * @example
+     * ```typescript
+     * await dlqManager.abandon(dlqId, 'Data corrupted, cannot recover')
+     * ```
+     */
+    abandon(dlqId: string, reason?: string): Promise<void>;
+    /**
+     * 更新 DLQ 事件狀態
+     *
+     * @param dlqId - DLQ 事件的 UUID
+     * @param status - 新狀態
+     * @param notes - 狀態變更說明
+     * @throws 如果事件不存在
+     *
+     * @internal
+     */
+    updateStatus(dlqId: string, status: 'pending' | 'requeued' | 'resolved' | 'abandoned', notes?: string): Promise<void>;
+    /**
+     * 刪除單個 DLQ 事件
+     *
+     * @param dlqId - DLQ 事件的 UUID
+     * @returns true 如果刪除成功，false 如果事件不存在
+     *
+     * @example
+     * ```typescript
+     * const deleted = await dlqManager.deleteEntry(dlqId)
+     * if (deleted) {
+     *   console.log('Event deleted')
+     * }
+     * ```
+     */
+    deleteEntry(dlqId: string): Promise<boolean>;
+    /**
+     * 刪除多個 DLQ 事件
+     *
+     * @param dlqIds - DLQ 事件 UUID 列表
+     * @returns 刪除的事件數量
+     *
+     * @example
+     * ```typescript
+     * const deletedCount = await dlqManager.deleteEntries([id1, id2, id3])
+     * ```
+     */
+    deleteEntries(dlqIds: string[]): Promise<number>;
+    /**
+     * 獲取 DLQ 統計信息
+     *
+     * @returns 包含總數、按事件名稱和狀態的統計信息
+     *
+     * @example
+     * ```typescript
+     * const stats = await dlqManager.getStats()
+     *
+     * console.log(`Total events: ${stats.total}`)
+     * console.log('By event:', stats.byEvent)
+     * // Output: { 'order:created': 145, 'payment:succeeded': 23 }
+     *
+     * console.log('By status:', stats.byStatus)
+     * // Output: { pending: 120, requeued: 15, resolved: 8, abandoned: 2 }
+     * ```
+     */
+    getStats(): Promise<DLQStats>;
+    /**
+     * 獲取某個事件名稱的 DLQ 事件數
+     *
+     * @param eventName - 事件名稱
+     * @returns 事件數量
+     *
+     * @example
+     * ```typescript
+     * const count = await dlqManager.getCountByEvent('order:created')
+     * ```
+     */
+    getCountByEvent(eventName: string): Promise<number>;
+    /**
+     * 清空所有 DLQ 事件（慎用！）
+     *
+     * @param includeResolved - 是否包含已解決的事件
+     * @returns 清空的事件數量
+     *
+     * @example
+     * ```typescript
+     * // 只清空待處理的事件
+     * const count = await dlqManager.clear(false)
+     *
+     * // 清空所有事件（包括已解決和已放棄）
+     * const countAll = await dlqManager.clear(true)
+     * ```
+     */
+    clear(includeResolved?: boolean): Promise<number>;
+    /**
+     * 通過 Bull Job ID 查找 DLQ 記錄
+     *
+     * 用於 MessageQueueBridge 集成：當 Bull Queue job 失敗時，
+     * 通過 Job ID 查找相應的 DLQ 記錄。
+     *
+     * @param bullJobId - Bull Queue Job ID
+     * @returns DLQ 記錄或 undefined
+     *
+     * @example
+     * ```typescript
+     * const record = await dlqManager.findByBullJobId('job-abc123')
+     * if (record) {
+     *   console.log(`Event ${record.event_name} is in DLQ`)
+     * }
+     * ```
+     */
+    findByBullJobId(bullJobId: string): Promise<DLQRecord | undefined>;
+    /**
+     * 調度延遲重試（整合 Bull Queue delayed jobs）
+     *
+     * 從 DLQ 中提取事件，通過 Bull Queue 的延遲 job 功能進行重試。
+     *
+     * @param dlqId - DLQ 記錄 ID
+     * @param delayMs - 延遲時間（毫秒）
+     * @throws 如果記錄不存在
+     *
+     * @example
+     * ```typescript
+     * // 延遲 1 小時後重試
+     * await dlqManager.scheduleRetry('dlq-uuid-123', 3600000)
+     * ```
+     */
+    scheduleRetry(dlqId: string, delayMs: number): Promise<void>;
+}

package/dist/core/src/reliability/RetryPolicy.d.ts

@@ -0,0 +1,217 @@
+/**
+ * @gravito/core - Retry Policy
+ *
+ * 重試策略和退避算法的實現
+ * 支持指數和線性退避，包含 Jitter 防止雷鳴羊群
+ */
+/**
+ * 重試策略配置接口
+ *
+ * @example
+ * ```typescript
+ * const policy: RetryPolicy = {
+ *   maxRetries: 3,
+ *   backoff: 'exponential',
+ *   initialDelayMs: 1000,
+ *   maxDelayMs: 30000,
+ *   dlqAfterMaxRetries: true
+ * }
+ * ```
+ */
+export interface RetryPolicy {
+    /** 最大重試次數 */
+    maxRetries: number;
+    /** 退避策略：指數或線性 */
+    backoff: 'exponential' | 'linear';
+    /** 初始延遲時間（毫秒） */
+    initialDelayMs: number;
+    /** 最大延遲時間（毫秒） */
+    maxDelayMs: number;
+    /** 超過最大重試次數後是否發送到死信隊列 */
+    dlqAfterMaxRetries?: boolean;
+}
+/**
+ * 重試引擎
+ *
+ * 負責計算重試延遲、判斷是否應該重試等邏輯
+ *
+ * @example
+ * ```typescript
+ * const engine = new RetryEngine()
+ * const delay = engine.calculateDelay(1, policy)
+ * const shouldRetry = engine.shouldRetry(3, policy)
+ * ```
+ */
+export declare class RetryEngine {
+    /**
+     * 計算下次重試的延遲時間（毫秒）
+     *
+     * @param attemptCount - 當前嘗試次數（從 1 開始）
+     * @param policy - 重試策略配置
+     * @returns 延遲時間（毫秒）
+     *
+     * @description
+     * - 指數退避：delay = initialDelay * 2^(attemptCount - 1)
+     * - 線性退避：delay = initialDelay * attemptCount
+     * - 添加隨機抖動（Jitter），防止雷鳴羊群問題
+     * - 結果不超過 maxDelayMs
+     *
+     * @example
+     * ```typescript
+     * const policy: RetryPolicy = {
+     *   maxRetries: 3,
+     *   backoff: 'exponential',
+     *   initialDelayMs: 1000,
+     *   maxDelayMs: 30000
+     * }
+     *
+     * // 第 1 次重試：1000ms * 2^0 = 1000ms (加抖動)
+     * const delay1 = engine.calculateDelay(1, policy)  // ~1100ms
+     *
+     * // 第 2 次重試：1000ms * 2^1 = 2000ms (加抖動)
+     * const delay2 = engine.calculateDelay(2, policy)  // ~2200ms
+     *
+     * // 第 3 次重試：1000ms * 2^2 = 4000ms (加抖動)
+     * const delay3 = engine.calculateDelay(3, policy)  // ~4400ms
+     * ```
+     */
+    calculateDelay(attemptCount: number, policy: RetryPolicy): number;
+    /**
+     * 判斷是否應該重試
+     *
+     * @param attemptCount - 當前嘗試次數（從 1 開始）
+     * @param policy - 重試策略配置
+     * @returns 是否應該重試
+     *
+     * @description
+     * 當 attemptCount < maxRetries 時返回 true
+     *
+     * @example
+     * ```typescript
+     * const policy = { maxRetries: 3, ... }
+     *
+     * engine.shouldRetry(1, policy)  // true（1 < 3）
+     * engine.shouldRetry(3, policy)  // false（3 >= 3）
+     * engine.shouldRetry(4, policy)  // false（4 >= 3）
+     * ```
+     */
+    shouldRetry(attemptCount: number, policy: RetryPolicy): boolean;
+    /**
+     * 獲取退避時間（包含延遲計算和 Jitter）
+     *
+     * @param retryCount - 重試次數（從 0 開始）
+     * @param policy - 重試策略配置
+     * @returns 退避時間（毫秒）
+     *
+     * @description
+     * 這是 calculateDelay 的別名，但接收的是從 0 開始的重試計數
+     *
+     * @example
+     * ```typescript
+     * const policy = { maxRetries: 3, initialDelayMs: 1000, maxDelayMs: 30000, backoff: 'exponential' }
+     *
+     * // 第 0 次重試（第 1 次嘗試失敗）
+     * const time1 = engine.getBackoffTime(0, policy)  // ~1100ms
+     *
+     * // 第 1 次重試（第 2 次嘗試失敗）
+     * const time2 = engine.getBackoffTime(1, policy)  // ~2200ms
+     * ```
+     */
+    getBackoffTime(retryCount: number, policy: RetryPolicy): number;
+    /**
+     * 計算下次重試的絕對時間
+     *
+     * @param retryCount - 重試次數（從 0 開始）
+     * @param policy - 重試策略配置
+     * @param baseTime - 基礎時間戳（默認為當前時間）
+     * @returns 下次重試的時間戳（毫秒）
+     *
+     * @example
+     * ```typescript
+     * const policy = { maxRetries: 3, initialDelayMs: 1000, maxDelayMs: 30000, backoff: 'exponential' }
+     *
+     * const now = Date.now()
+     * const nextRetryTime = engine.getNextRetryTime(0, policy, now)
+     * // 返回大約 now + 1000 + jitter
+     * ```
+     */
+    getNextRetryTime(retryCount: number, policy: RetryPolicy, baseTime?: number): number;
+    /**
+     * 驗證重試策略配置
+     *
+     * @param policy - 重試策略配置
+     * @returns 是否有效
+     *
+     * @description
+     * 檢查配置是否合理：
+     * - maxRetries >= 0
+     * - initialDelayMs > 0
+     * - maxDelayMs >= initialDelayMs
+     *
+     * @example
+     * ```typescript
+     * const validPolicy = { maxRetries: 3, initialDelayMs: 1000, maxDelayMs: 30000, backoff: 'exponential' }
+     * engine.isValidPolicy(validPolicy)  // true
+     *
+     * const invalidPolicy = { maxRetries: 3, initialDelayMs: 5000, maxDelayMs: 1000, backoff: 'exponential' }
+     * engine.isValidPolicy(invalidPolicy)  // false (maxDelayMs < initialDelayMs)
+     * ```
+     */
+    isValidPolicy(policy: RetryPolicy): boolean;
+    /**
+     * 獲取人類可讀的重試信息
+     *
+     * @param attemptCount - 當前嘗試次數（從 1 開始）
+     * @param policy - 重試策略配置
+     * @returns 描述性文本
+     *
+     * @example
+     * ```typescript
+     * const policy = { maxRetries: 3, initialDelayMs: 1000, maxDelayMs: 30000, backoff: 'exponential' }
+     *
+     * engine.getRetryInfo(1, policy)  // "Retry 1 of 3, will retry in ~1100ms"
+     * engine.getRetryInfo(3, policy)  // "Retry 3 of 3 (final attempt), will retry in ~4400ms"
+     * engine.getRetryInfo(4, policy)  // "Max retries exceeded (4 >= 3)"
+     * ```
+     */
+    getRetryInfo(attemptCount: number, policy: RetryPolicy): string;
+}
+/**
+ * 創建默認的重試策略
+ *
+ * @returns 默認重試策略
+ *
+ * @description
+ * 默認配置：
+ * - 最多重試 3 次
+ * - 指數退避
+ * - 初始延遲 1 秒
+ * - 最大延遲 30 秒
+ * - 超過最大重試後發送 DLQ
+ *
+ * @example
+ * ```typescript
+ * const policy = getDefaultRetryPolicy()
+ * // { maxRetries: 3, backoff: 'exponential', initialDelayMs: 1000, maxDelayMs: 30000, dlqAfterMaxRetries: true }
+ * ```
+ */
+export declare function getDefaultRetryPolicy(): RetryPolicy;
+/**
+ * 為不同類型的操作獲取預設的重試策略
+ *
+ * @param type - 操作類型
+ * @returns 推薦的重試策略
+ *
+ * @example
+ * ```typescript
+ * // 外部 API 調用：更多重試，更長延遲
+ * const apiPolicy = getPresetRetryPolicy('external-api')
+ *
+ * // 數據庫操作：較少重試，短延遲
+ * const dbPolicy = getPresetRetryPolicy('database')
+ *
+ * // 消息隊列：適中重試
+ * const mqPolicy = getPresetRetryPolicy('message-queue')
+ * ```
+ */
+export declare function getPresetRetryPolicy(type: 'external-api' | 'database' | 'message-queue' | 'default'): RetryPolicy;

package/dist/core/src/reliability/index.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Reliability and retry exports.
+ * @packageDocumentation
+ */
+export { DeadLetterQueueManager, type DLQManagerFilter, type DLQRecord, type DLQStats, } from './DeadLetterQueueManager';
+export { getDefaultRetryPolicy, getPresetRetryPolicy, RetryEngine, type RetryPolicy, } from './RetryPolicy';