@gravito/ripple 4.0.0 → 4.0.1

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

@@ -312,6 +312,25 @@ export interface GravitoContext<V extends GravitoVariables = GravitoVariables> {
      * ```
      */
     readonly native: unknown;
+    /**
+     * Access the RequestScopeManager for this request
+     * Services resolved through this manager are scoped to the HTTP request lifetime.
+     */
+    requestScope(): any;
+    /**
+     * Resolve or create a request-scoped service
+     *
+     * @param key - Service key (string or symbol)
+     * @param factory - Factory function to create the service if not cached
+     * @returns The cached or newly created service instance
+     *
+     * @example
+     * ```typescript
+     * // Subsequent calls in the same request return the same instance
+     * const cache = ctx.scoped('product:cache', () => new RequestProductCache())
+     * ```
+     */
+    scoped<T>(key: string | symbol, factory: () => T): T;
 }
 /**
  * Next function for middleware chain

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

@@ -20,18 +20,29 @@ export { Application, type ApplicationConfig } from './Application';
 export { type CommandHandler, CommandKernel } from './CommandKernel';
 export { ConfigManager } from './ConfigManager';
 export { Container, type Factory, type ServiceKey, type ServiceMap } from './Container';
+export { RequestScopeManager } from './Container/RequestScopeManager';
+export { RequestScopeMetrics, RequestScopeMetricsCollector, type RequestScopeObserver, } from './Container/RequestScopeMetrics';
+export { registerQueueCommands } from './cli/queue-commands';
 export { codeFromStatus, ErrorHandler, type ErrorHandlerDeps, messageFromStatus, } from './ErrorHandler';
 export { EventManager } from './EventManager';
+export { cleanupRequestScopeOnError, detectRequestScopeLeaks, extractRequestScopeErrorContext, RequestScopeCleanupError, type RequestScopeErrorContext, withRequestScopeCleanup, } from './error-handling/RequestScopeErrorContext';
 export type { CircuitBreakerOptions, DLQEntry, DLQFilter, EventBackend, EventOptions, EventTask, } from './events';
 export { CircuitBreaker, CircuitBreakerState, DEFAULT_EVENT_OPTIONS, DeadLetterQueue, EventPriorityQueue, } from './events';
 export type { EventTracingConfig, ObservabilityConfig, QueueDepthCallback, } from './events/observability';
 export { EventMetrics, EventTracer, EventTracing, getEventTracing, ObservableHookManager, OTelEventMetrics, } from './events/observability';
+export { type DashboardSnapshot, type ErrorStats, type JobEvent, QueueDashboard, type QueueDashboardConfig, type QueueMetrics, type WorkerMetrics as QueueWorkerMetrics, } from './observability/QueueDashboard';
 export * from './exceptions';
 export { type GlobalErrorHandlersMode, type GlobalProcessErrorHandlerContext, type GlobalProcessErrorKind, type RegisterGlobalErrorHandlersOptions, registerGlobalErrorHandlers, } from './GlobalErrorHandlers';
 export { type GravitoManifest, GravitoServer } from './GravitoServer';
 export type { ActionCallback, FilterCallback, ListenerInfo, ListenerOptions } from './HookManager';
 export { HookManager, type HookManagerConfig } from './HookManager';
-export * from './helpers';
+export type { HealthCheck, HealthCheckResult } from './health/HealthProvider';
+export { HealthProvider } from './health/HealthProvider';
+export type { DumpOptions } from './helpers';
+export { Arr, abort, abortIf, abortUnless, app, blank, config, DumpDieError, dd, dump, env, filled, hasApp, logger, router, Str, setApp, tap, throwIf, throwUnless, value, } from './helpers';
+export * from './helpers/data';
+export * from './helpers/errors';
+export * from './helpers/response';
 export { CookieJar, type CookieOptions } from './http/CookieJar';
 export { deleteCookie, getCookie, setCookie } from './http/cookie';
 export { type BodySizeLimitOptions, bodySizeLimit } from './http/middleware/BodySizeLimit';
@@ -46,6 +57,7 @@ export type { Listener, ShouldQueue } from './Listener';
 export type { Logger } from './Logger';
 export { ConsoleLogger } from './Logger';
 export { type CacheService, type ErrorHandlerContext, type GravitoConfig, type GravitoOrbit, PlanetCore, type ViewService, } from './PlanetCore';
+export { RequestContext, type RequestContextData, } from './RequestContext';
 export { Route } from './Route';
 export { type ControllerClass, FORM_REQUEST_SYMBOL, type FormRequestClass, type FormRequestLike, RouteGroup, type RouteHandler, type RouteOptions, Router, } from './Router';
 export type { DLQManagerFilter, DLQRecord, DLQStats, RetryPolicy } from './reliability';

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

@@ -0,0 +1,244 @@
+/**
+ * @gravito/core - Prometheus Metrics Setup
+ *
+ * 設置和導出 Prometheus 指標，用於性能監控。
+ */
+/**
+ * Prometheus 指標配置
+ */
+export interface PrometheusMetricsConfig {
+    /** Prometheus 抓取端口 */
+    port?: number;
+    /** 指標前綴 */
+    prefix?: string;
+    /** 上報間隔（毫秒） */
+    interval?: number;
+    /** 是否啟用默認指標（如內存、CPU） */
+    defaultMetrics?: boolean;
+}
+/**
+ * Prometheus 指標導出器
+ *
+ * 將 Gravito 事件系統的指標導出到 Prometheus
+ *
+ * @example
+ * ```typescript
+ * import { setupPrometheusMetrics } from '@gravito/core/observability'
+ *
+ * const exporter = await setupPrometheusMetrics({
+ *   port: 9090,
+ *   prefix: 'gravito_event_'
+ * })
+ * ```
+ *
+ * @public
+ */
+export declare function setupPrometheusMetrics(config?: PrometheusMetricsConfig): Promise<{
+    port: number;
+    endpoint: string;
+} | null>;
+/**
+ * 事件系統指標定義
+ *
+ * 這些指標用於監控事件派發系統的性能和可靠性。
+ *
+ * @public
+ */
+export interface EventMetricsDefinition {
+    /** 事件派發延遲（直方圖） */
+    dispatchLatency: {
+        name: string;
+        help: string;
+        labels: string[];
+        buckets: number[];
+    };
+    /** 監聽器執行時間（直方圖） */
+    listenerExecutionTime: {
+        name: string;
+        help: string;
+        labels: string[];
+        buckets: number[];
+    };
+    /** 隊列深度（量表） */
+    queueDepth: {
+        name: string;
+        help: string;
+        labels: string[];
+    };
+    /** 失敗計數（計數器） */
+    failureRate: {
+        name: string;
+        help: string;
+        labels: string[];
+    };
+    /** 超時計數（計數器） */
+    timeoutCount: {
+        name: string;
+        help: string;
+        labels: string[];
+    };
+    /** 吞吐量（計數器） */
+    throughput: {
+        name: string;
+        help: string;
+        labels: string[];
+    };
+    /** 熔斷器狀態（量表） */
+    circuitBreakerState: {
+        name: string;
+        help: string;
+        labels: string[];
+    };
+    /** 熔斷器狀態轉換（計數器） */
+    circuitBreakerTransitions: {
+        name: string;
+        help: string;
+        labels: string[];
+    };
+    /** 熔斷器失敗計數（計數器） */
+    circuitBreakerFailures: {
+        name: string;
+        help: string;
+        labels: string[];
+    };
+    /** 熔斷器成功計數（計數器） */
+    circuitBreakerSuccesses: {
+        name: string;
+        help: string;
+        labels: string[];
+    };
+    /** 熔斷器 OPEN 持續時間（直方圖） */
+    circuitBreakerOpenDuration: {
+        name: string;
+        help: string;
+        labels: string[];
+        buckets: number[];
+    };
+}
+/**
+ * 獲取事件系統的標準指標定義
+ *
+ * @param prefix - 指標名稱前綴（默認：gravito_event_）
+ * @returns 指標定義對象
+ *
+ * @example
+ * ```typescript
+ * import { getEventMetricsDefinition } from '@gravito/core/observability'
+ *
+ * const metrics = getEventMetricsDefinition('gravito_event_')
+ * console.log(metrics.dispatchLatency.name)  // gravito_event_dispatch_latency_seconds
+ * ```
+ *
+ * @public
+ */
+export declare function getEventMetricsDefinition(prefix?: string): EventMetricsDefinition;
+/**
+ * Prometheus 查詢範例
+ *
+ * 提供常用的 Prometheus 查詢語句，用於監控事件系統
+ *
+ * @public
+ */
+export declare const PROMETHEUS_QUERIES: {
+    /** 事件派發延遲 P95 */
+    dispatchLatencyP95: string;
+    /** 事件派發延遲 P99 */
+    dispatchLatencyP99: string;
+    /** 隊列深度（按優先級） */
+    queueDepthByPriority: string;
+    /** 吞吐量（事件/秒） */
+    throughput: string;
+    /** 失敗率 */
+    failureRate: string;
+    /** 監聽器執行時間 P99 */
+    listenerLatencyP99: string;
+    /** 超時次數 */
+    timeoutCount: string;
+    /** 吞吐量異常檢測 */
+    throughputAnomaly: string;
+    /** 熔斷器狀態（0=CLOSED, 1=HALF_OPEN, 2=OPEN） */
+    circuitBreakerState: string;
+    /** 熔斷器開啟率 */
+    circuitBreakerOpenRate: string;
+    /** 熔斷器恢復率 */
+    circuitBreakerRecoveryRate: string;
+    /** 熔斷器失敗率 */
+    circuitBreakerFailureRate: string;
+    /** 熔斷器 OPEN 持續時間 P95 */
+    circuitBreakerOpenDurationP95: string;
+    /** 熔斷器 OPEN 持續時間 P99 */
+    circuitBreakerOpenDurationP99: string;
+};
+/**
+ * Prometheus 告警規則
+ *
+ * 提供預定義的告警規則，用於監控事件系統的健康狀況
+ *
+ * @public
+ */
+export declare const PROMETHEUS_ALERT_RULES: {
+    /** P99 延遲過高 */
+    HighDispatchLatency: {
+        expr: string;
+        for: string;
+        severity: string;
+        summary: string;
+        description: string;
+    };
+    /** 隊列深度過高 */
+    HighQueueDepth: {
+        expr: string;
+        for: string;
+        severity: string;
+        summary: string;
+        description: string;
+    };
+    /** 失敗率過高 */
+    HighFailureRate: {
+        expr: string;
+        for: string;
+        severity: string;
+        summary: string;
+        description: string;
+    };
+    /** 監聽器執行時間過長 */
+    SlowListener: {
+        expr: string;
+        for: string;
+        severity: string;
+        summary: string;
+        description: string;
+    };
+    /** 吞吐量異常下降 */
+    ThroughputDrop: {
+        expr: string;
+        for: string;
+        severity: string;
+        summary: string;
+        description: string;
+    };
+    /** 熔斷器持續開啟 */
+    CircuitBreakerOpen: {
+        expr: string;
+        for: string;
+        severity: string;
+        summary: string;
+        description: string;
+    };
+    /** 熔斷器頻繁切換 */
+    CircuitBreakerFlapping: {
+        expr: string;
+        for: string;
+        severity: string;
+        summary: string;
+        description: string;
+    };
+    /** 熔斷器故障率過高 */
+    CircuitBreakerHighFailureRate: {
+        expr: string;
+        for: string;
+        severity: string;
+        summary: string;
+        description: string;
+    };
+};

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

@@ -0,0 +1,136 @@
+import type { DeadLetterQueue } from '../events/DeadLetterQueue';
+import type { EventPriorityQueue } from '../events/EventPriorityQueue';
+import type { MessageQueueBridge } from '../events/MessageQueueBridge';
+import type { WorkerPool } from '../events/WorkerPool';
+import type { HookManager } from '../HookManager';
+/**
+ * Configuration for QueueDashboard
+ * All subsystem references are optional to support progressive integration
+ */
+export interface QueueDashboardConfig {
+    eventQueue?: EventPriorityQueue;
+    workerPool?: WorkerPool;
+    hookManager?: HookManager;
+    dlq?: DeadLetterQueue;
+    messageQueueBridge?: MessageQueueBridge;
+}
+/**
+ * Queue depth and backpressure metrics
+ */
+export interface QueueMetrics {
+    depth: {
+        total: number;
+        high: number;
+        normal: number;
+        low: number;
+    };
+    backpressure: {
+        state: string;
+        rejectedCount: number;
+        degradedCount: number;
+        enqueueRate: number;
+    };
+    processing: boolean;
+}
+/**
+ * Worker pool and thread statistics
+ */
+export interface WorkerMetrics {
+    poolSize: number;
+    activeWorkers: number;
+    utilization: number;
+    queueDepth: number;
+    totalProcessed: number;
+    totalSuccess: number;
+    totalFailures: number;
+    successRate: number;
+    workers: Array<{
+        id: string;
+        state: string;
+        tasksProcessed: number;
+        tasksSucceeded: number;
+        tasksFailed: number;
+        avgDurationMs: number;
+        currentLoad: number;
+    }>;
+}
+/**
+ * Timeline event for job processing history
+ */
+export interface JobEvent {
+    id: string;
+    hook: string;
+    status: 'pending' | 'processing' | 'completed' | 'failed' | 'in_dlq';
+    priority: string;
+    createdAt: number;
+    error?: string;
+    retryCount: number;
+}
+/**
+ * Error statistics and circuit breaker status
+ */
+export interface ErrorStats {
+    totalErrors: number;
+    byEvent: Record<string, number>;
+    circuitBreakers: Array<{
+        eventName: string;
+        state: string;
+        failures: number;
+        successes: number;
+    }>;
+    dlqCount: number;
+}
+/**
+ * Complete dashboard snapshot at a point in time
+ */
+export interface DashboardSnapshot {
+    timestamp: number;
+    queue: QueueMetrics;
+    workers: WorkerMetrics;
+    timeline: JobEvent[];
+    errors: ErrorStats;
+}
+/**
+ * QueueDashboard aggregates metrics from all event processing subsystems
+ * Uses Facade pattern to read-only aggregate data without modifying subsystems
+ */
+export declare class QueueDashboard {
+    private readonly config;
+    constructor(config: QueueDashboardConfig);
+    /**
+     * Get current queue metrics (depth, backpressure state, enqueue rate)
+     */
+    getQueueMetrics(): QueueMetrics;
+    /**
+     * Get current worker pool metrics (size, utilization, success rate)
+     */
+    getWorkerMetrics(): WorkerMetrics;
+    /**
+     * Get job event timeline from DLQ entries (recent failures)
+     * @param limit Maximum number of entries to return (default: 50)
+     */
+    getJobTimeline(limit?: number): JobEvent[];
+    /**
+     * Get error statistics including circuit breaker status and DLQ counts
+     */
+    getErrorBreakdown(): ErrorStats;
+    /**
+     * Export metrics in JSON or Prometheus format
+     * @param format Export format: 'json' or 'prometheus'
+     */
+    exportMetrics(format: 'json' | 'prometheus'): string;
+    /**
+     * Get complete snapshot of all metrics at a point in time
+     */
+    getSnapshot(options?: {
+        timelineLimit?: number;
+    }): DashboardSnapshot;
+    /**
+     * Format metrics in Prometheus/OpenMetrics text format
+     */
+    private formatPrometheus;
+    /**
+     * Escape special characters in Prometheus labels
+     */
+    private escapePrometheusLabel;
+}

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

@@ -313,4 +313,38 @@ export declare class DeadLetterQueueManager {
      * ```
      */
     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>;
 }