@gravito/echo 3.0.1 → 3.1.0

package/dist/core/src/instrumentation/opentelemetry.d.ts

@@ -0,0 +1,178 @@
+/**
+ * @gravito/core - OpenTelemetry SDK 集成
+ *
+ * 提供 OpenTelemetry 的初始化、配置與管理功能。
+ * 支援動態導入以實現可選依賴的優雅降級。
+ *
+ * @example
+ * ```typescript
+ * import { setupOpenTelemetry } from '@gravito/core'
+ *
+ * const sdk = await setupOpenTelemetry({
+ *   serviceName: 'my-service',
+ *   serviceVersion: '1.0.0',
+ *   tracing: {
+ *     enabled: true,
+ *     exporter: 'jaeger',
+ *     samplingRate: 0.1
+ *   },
+ *   metrics: {
+ *     enabled: true,
+ *     exporter: 'prometheus',
+ *     prometheusPort: 9090
+ *   }
+ * })
+ * ```
+ *
+ * @packageDocumentation
+ */
+import { type MetricsConfig, type OpenTelemetryConfig, type OpenTelemetrySDK, type TracingConfig } from './types';
+export type { MetricsConfig, OpenTelemetryConfig, OpenTelemetrySDK, TracingConfig };
+/**
+ * 初始化 OpenTelemetry SDK
+ *
+ * @param userConfig - 用戶配置
+ * @returns OpenTelemetry SDK 實例或 null（如果禁用或初始化失敗）
+ *
+ * @example
+ * ```typescript
+ * // 基本用法
+ * const sdk = await setupOpenTelemetry({
+ *   serviceName: 'my-service'
+ * })
+ *
+ * // 完整配置
+ * const sdk = await setupOpenTelemetry({
+ *   serviceName: 'my-service',
+ *   serviceVersion: '2.0.0',
+ *   environment: 'production',
+ *   tracing: {
+ *     enabled: true,
+ *     exporter: 'jaeger',
+ *     jaegerEndpoint: 'http://jaeger:14268/api/traces',
+ *     samplingRate: 0.1
+ *   },
+ *   metrics: {
+ *     enabled: true,
+ *     exporter: 'prometheus',
+ *     prometheusPort: 9090
+ *   }
+ * })
+ * ```
+ *
+ * @public
+ */
+export declare function setupOpenTelemetry(userConfig?: OpenTelemetryConfig): Promise<OpenTelemetrySDK | null>;
+/**
+ * 獲取全局 OpenTelemetry SDK 實例
+ *
+ * @returns SDK 實例或 null
+ *
+ * @example
+ * ```typescript
+ * const sdk = getOpenTelemetrySDK()
+ * if (sdk) {
+ *   console.log('Service:', sdk.serviceName)
+ * }
+ * ```
+ *
+ * @public
+ */
+export declare function getOpenTelemetrySDK(): OpenTelemetrySDK | null;
+/**
+ * 檢查 OpenTelemetry 是否已初始化
+ *
+ * @returns 初始化狀態
+ *
+ * @public
+ */
+export declare function isOpenTelemetryInitialized(): boolean;
+/**
+ * 關閉 OpenTelemetry SDK
+ *
+ * 應在應用程序關閉時調用，確保所有 spans 和 metrics 都被導出。
+ *
+ * @example
+ * ```typescript
+ * // 在應用程序退出前
+ * process.on('SIGTERM', async () => {
+ *   await shutdownOpenTelemetry()
+ *   process.exit(0)
+ * })
+ * ```
+ *
+ * @public
+ */
+export declare function shutdownOpenTelemetry(): Promise<void>;
+/**
+ * 重置 OpenTelemetry SDK（主要用於測試）
+ *
+ * 關閉現有 SDK 並重置所有狀態，允許重新初始化。
+ *
+ * @internal
+ */
+export declare function resetOpenTelemetry(): Promise<void>;
+/**
+ * 獲取 Tracer 實例
+ *
+ * @param name - Tracer 名稱（預設：@gravito/core）
+ * @param version - Tracer 版本
+ * @returns Tracer 實例
+ *
+ * @example
+ * ```typescript
+ * const tracer = getTracer('my-module')
+ * const span = tracer.startSpan('my-operation')
+ * // ... 執行操作
+ * span.end()
+ * ```
+ *
+ * @public
+ */
+export declare function getTracer(name?: string, version?: string): Promise<import("@opentelemetry/api").Tracer | {
+    startSpan: () => {
+        end: () => void;
+        setAttribute: () => void;
+        setStatus: () => void;
+        recordException: () => void;
+        addEvent: () => void;
+        isRecording: () => boolean;
+    };
+    startActiveSpan: (_name: string, fn: (span: any) => any) => any;
+}>;
+/**
+ * 獲取 Meter 實例
+ *
+ * @param name - Meter 名稱（預設：@gravito/core）
+ * @param version - Meter 版本
+ * @returns Meter 實例
+ *
+ * @example
+ * ```typescript
+ * const meter = getMeter('my-module')
+ * const counter = meter.createCounter('my_counter')
+ * counter.add(1, { key: 'value' })
+ * ```
+ *
+ * @public
+ */
+export declare function getMeter(name?: string, version?: string): Promise<import("@opentelemetry/api").Meter | {
+    createCounter: () => {
+        add: () => void;
+    };
+    createHistogram: () => {
+        record: () => void;
+    };
+    createUpDownCounter: () => {
+        add: () => void;
+    };
+    createObservableCounter: () => {
+        addCallback: () => void;
+    };
+    createObservableGauge: () => {
+        addCallback: () => void;
+    };
+    createObservableUpDownCounter: () => {
+        addCallback: () => void;
+    };
+}>;

package/dist/core/src/instrumentation/types.d.ts

@@ -0,0 +1,182 @@
+/**
+ * @gravito/core - OpenTelemetry 類型定義
+ *
+ * 定義 OpenTelemetry SDK 集成所需的類型與介面。
+ */
+/**
+ * Tracing（追蹤）導出器類型
+ */
+export type TracingExporter = 'jaeger' | 'otlp' | 'console' | 'none';
+/**
+ * Metrics（指標）導出器類型
+ */
+export type MetricsExporter = 'prometheus' | 'otlp' | 'console' | 'none';
+/**
+ * Tracing 配置選項
+ */
+export interface TracingConfig {
+    /** 是否啟用追蹤（預設：true） */
+    enabled?: boolean;
+    /** 導出器類型（預設：otlp） */
+    exporter?: TracingExporter;
+    /** Jaeger HTTP 端點（使用 jaeger 導出器時） */
+    jaegerEndpoint?: string;
+    /** OTLP 端點（使用 otlp 導出器時） */
+    otlpEndpoint?: string;
+    /** 採樣率（0-1，預設：1.0 = 100%） */
+    samplingRate?: number;
+    /** 是否啟用自動儀器化（預設：false） */
+    autoInstrumentation?: boolean;
+    /** Batch Span Processor 配置 */
+    batchConfig?: {
+        /** 最大批次大小（預設：512） */
+        maxExportBatchSize?: number;
+        /** 導出間隔（毫秒，預設：5000） */
+        scheduledDelayMillis?: number;
+        /** 導出超時（毫秒，預設：30000） */
+        exportTimeoutMillis?: number;
+        /** 最大隊列大小（預設：2048） */
+        maxQueueSize?: number;
+    };
+}
+/**
+ * Metrics 配置選項
+ */
+export interface MetricsConfig {
+    /** 是否啟用指標（預設：true） */
+    enabled?: boolean;
+    /** 導出器類型（預設：otlp） */
+    exporter?: MetricsExporter;
+    /** Prometheus 端口（使用 prometheus 導出器時，預設：9090） */
+    prometheusPort?: number;
+    /** Prometheus 端點路徑（預設：/metrics） */
+    prometheusEndpoint?: string;
+    /** OTLP 端點（使用 otlp 導出器時） */
+    otlpEndpoint?: string;
+    /** 導出間隔（毫秒，預設：60000） */
+    exportIntervalMillis?: number;
+}
+/**
+ * OpenTelemetry SDK 完整配置
+ */
+export interface OpenTelemetryConfig {
+    /** 是否啟用 OpenTelemetry（預設：true） */
+    enabled?: boolean;
+    /** 服務名稱（預設：gravito-app） */
+    serviceName?: string;
+    /** 服務版本（預設：1.0.0） */
+    serviceVersion?: string;
+    /** 環境名稱（預設：development） */
+    environment?: 'development' | 'staging' | 'production' | string;
+    /** 自定義 Resource Attributes */
+    resourceAttributes?: Record<string, string | number | boolean>;
+    /** Tracing 配置 */
+    tracing?: TracingConfig;
+    /** Metrics 配置 */
+    metrics?: MetricsConfig;
+    /** 是否在控制台輸出初始化日誌（預設：true） */
+    logInitialization?: boolean;
+}
+/**
+ * OpenTelemetry SDK 實例包裝
+ *
+ * 封裝初始化後的 SDK 實例與相關資源。
+ */
+export interface OpenTelemetrySDK {
+    /** SDK 是否已啟動 */
+    isStarted: boolean;
+    /** SDK 是否已關閉 */
+    isShutdown: boolean;
+    /** 服務名稱 */
+    serviceName: string;
+    /** 服務版本 */
+    serviceVersion: string;
+    /** Tracer Provider（如果啟用追蹤） */
+    tracerProvider: unknown | null;
+    /** Meter Provider（如果啟用指標） */
+    meterProvider: unknown | null;
+    /** 原始配置 */
+    config: OpenTelemetryConfig;
+    /** 關閉 SDK */
+    shutdown: () => Promise<void>;
+}
+/**
+ * 支援的 OpenTelemetry 環境變數
+ *
+ * 參考：https://opentelemetry.io/docs/specs/otel/configuration/sdk-environment-variables/
+ */
+export declare const OTEL_ENV_VARS: {
+    /** 服務名稱 */
+    readonly SERVICE_NAME: "OTEL_SERVICE_NAME";
+    /** 服務版本 */
+    readonly SERVICE_VERSION: "OTEL_SERVICE_VERSION";
+    /** 環境名稱 */
+    readonly DEPLOYMENT_ENVIRONMENT: "OTEL_DEPLOYMENT_ENVIRONMENT";
+    /** Resource Attributes */
+    readonly RESOURCE_ATTRIBUTES: "OTEL_RESOURCE_ATTRIBUTES";
+    /** OTLP 端點（通用） */
+    readonly OTLP_ENDPOINT: "OTEL_EXPORTER_OTLP_ENDPOINT";
+    /** OTLP Traces 端點 */
+    readonly OTLP_TRACES_ENDPOINT: "OTEL_EXPORTER_OTLP_TRACES_ENDPOINT";
+    /** OTLP Metrics 端點 */
+    readonly OTLP_METRICS_ENDPOINT: "OTEL_EXPORTER_OTLP_METRICS_ENDPOINT";
+    /** 採樣器類型 */
+    readonly TRACES_SAMPLER: "OTEL_TRACES_SAMPLER";
+    /** 採樣率參數 */
+    readonly TRACES_SAMPLER_ARG: "OTEL_TRACES_SAMPLER_ARG";
+    /** 是否啟用 OpenTelemetry */
+    readonly GRAVITO_ENABLED: "GRAVITO_OTEL_ENABLED";
+    /** Jaeger 端點 */
+    readonly JAEGER_ENDPOINT: "JAEGER_ENDPOINT";
+    /** Prometheus 端口 */
+    readonly PROMETHEUS_PORT: "PROMETHEUS_PORT";
+};
+/**
+ * 完整的 BatchConfig 類型（所有屬性必填）
+ */
+export interface BatchConfigRequired {
+    maxExportBatchSize: number;
+    scheduledDelayMillis: number;
+    exportTimeoutMillis: number;
+    maxQueueSize: number;
+}
+/**
+ * 完整的 TracingConfig 類型（所有屬性必填）
+ */
+export interface TracingConfigRequired {
+    enabled: boolean;
+    exporter: TracingExporter;
+    jaegerEndpoint: string;
+    otlpEndpoint: string;
+    samplingRate: number;
+    autoInstrumentation: boolean;
+    batchConfig: BatchConfigRequired;
+}
+/**
+ * 完整的 MetricsConfig 類型（所有屬性必填）
+ */
+export interface MetricsConfigRequired {
+    enabled: boolean;
+    exporter: MetricsExporter;
+    prometheusPort: number;
+    prometheusEndpoint: string;
+    otlpEndpoint: string;
+    exportIntervalMillis: number;
+}
+/**
+ * 完整的 OpenTelemetryConfig 類型（所有屬性必填）
+ */
+export interface OpenTelemetryConfigRequired {
+    enabled: boolean;
+    serviceName: string;
+    serviceVersion: string;
+    environment: 'development' | 'staging' | 'production';
+    resourceAttributes: Record<string, string | number | boolean>;
+    tracing: TracingConfigRequired;
+    metrics: MetricsConfigRequired;
+    logInitialization: boolean;
+}
+/**
+ * 預設配置值
+ */
+export declare const DEFAULT_CONFIG: OpenTelemetryConfigRequired;

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

@@ -0,0 +1,316 @@
+/**
+ * @gravito/core - Dead Letter Queue Manager
+ *
+ * 管理失敗事件的持久化存儲
+ * 支持 CRUD、重新入隊、批量重試和統計功能
+ */
+import type { ConnectionContract } from '@gravito/atlas';
+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 ConnectionContract
+ * 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: ConnectionContract);
+    /**
+     * 將失敗事件移至死信隊列
+     *
+     * @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>;
+}