@gravito/ripple 4.0.0 → 4.0.3

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

@@ -1,129 +1,32 @@
-import type { ConnectionContract } from '@gravito/atlas';
-import { type CircuitBreakerOptions } from './events/CircuitBreaker';
 import { DeadLetterQueue } from './events/DeadLetterQueue';
 import type { EventBackend } from './events/EventBackend';
 import type { EventOptions } from './events/EventOptions';
-import { EventPriorityQueue, type EventQueueConfig } from './events/EventPriorityQueue';
+import { EventPriorityQueue } from './events/EventPriorityQueue';
 import { DeadLetterQueueManager } from './reliability/DeadLetterQueueManager';
+export type { ActionCallback, FilterCallback, HookManagerConfig, ListenerInfo, ListenerOptions, } from './hooks/types';
+import type { ActionCallback, FilterCallback, HookManagerConfig, ListenerInfo, ListenerOptions } from './hooks/types';
 /**
- * Callback function for filters (transforms values).
+ * Manager for WordPress-style hooks (actions and filters).
+ *
+ * 此為 facade 類別，將職責委派給專門的管理器：
+ * - FilterManager：處理 filter hook 的登記與執行
+ * - ActionManager：處理 action hook 的登記與執行
+ * - AsyncDetector：非同步偵測快取
+ * - MigrationWarner：遷移警告管理
+ *
  * @public
  */
-export type FilterCallback<T = unknown> = (value: T, ...args: unknown[]) => Promise<T> | T;
-/**
- * Callback function for actions (side effects).
- * @public
- */
-export type ActionCallback<TArgs = unknown> = (args: TArgs) => Promise<void> | void;
-/**
- * Options for listener registration.
- * @public
- */
-export interface ListenerOptions {
-    /**
-     * Explicitly specify the listener type.
-     * - 'sync': Force synchronous dispatch for this listener
-     * - 'async': Force asynchronous dispatch for this listener
-     * - 'auto': Auto-detect based on function signature (default)
-     * @default 'auto'
-     */
-    type?: 'sync' | 'async' | 'auto';
-    /**
-     * Circuit breaker configuration for this listener.
-     */
-    circuitBreaker?: CircuitBreakerOptions;
-}
-/**
- * Information about a registered listener.
- * @public
- */
-export interface ListenerInfo {
-    /**
-     * The callback function.
-     */
-    callback: ActionCallback;
-    /**
-     * Whether the listener is considered async.
-     */
-    isAsync: boolean;
-    /**
-     * The explicit type override, if any.
-     */
-    typeOverride?: 'sync' | 'async' | 'auto';
-}
-/**
- * Configuration for HookManager.
- * @public
- */
-export interface HookManagerConfig {
-    /**
-     * Enable async event dispatch by default.
-     * When true, doAction() will automatically use async dispatch if any listener is async.
-     * @default false
-     */
-    asyncByDefault?: boolean;
-    /**
-     * Migration mode for backward compatibility.
-     * - 'sync': All events use synchronous dispatch (legacy mode)
-     * - 'hybrid': Auto-detect and use async for async listeners (recommended)
-     * - 'async': All events use async dispatch (future mode)
-     * @default 'sync'
-     */
-    migrationMode?: 'sync' | 'hybrid' | 'async';
-    /**
-     * Enable deprecation warnings for synchronous event dispatch.
-     * @default false
-     */
-    showDeprecationWarnings?: boolean;
-    /**
-     * Enable Dead Letter Queue for failed events.
-     * @default true
-     */
-    enableDLQ?: boolean;
-    /**
-     * Configuration for the event priority queue (Backpressure).
-     */
-    queue?: EventQueueConfig;
-    /**
-     * Custom event backend for distributed processing.
-     */
-    backend?: EventBackend;
-    /**
-     * Database connection for persistent DLQ (optional).
-     * If provided, failed events after max retries will be persisted to database.
-     */
-    db?: ConnectionContract;
-    /**
-     * Enable persistent DLQ for failed events (requires db).
-     * @default false
-     */
-    enablePersistentDLQ?: boolean;
-}
 export declare class HookManager {
-    private filters;
-    private actions;
+    private filterManager;
+    private actionManager;
+    private asyncDetector;
+    private migrationWarner;
     private eventQueue;
     private backend;
     private dlq?;
     private persistentDlqManager?;
-    private idempotencyCache;
+    private messageQueueBridge?;
     private config;
-    private migrationWarner;
-    /**
-     * Cache for async detection results (WeakMap for automatic garbage collection).
-     * @internal
-     */
-    private asyncDetectionCache;
-    /**
-     * Count of items in the async detection cache (for testing/debugging).
-     * @internal
-     */
-    private asyncDetectionCacheCount;
-    /**
-     * Map of listener type overrides (callback -> type).
-     * @internal
-     */
-    private listenerTypeOverrides;
     constructor(config?: HookManagerConfig);
     /**
      * Register a filter hook.
@@ -138,8 +41,8 @@ export declare class HookManager {
      * @example
      * ```typescript
      * core.hooks.addFilter('content', async (content: string) => {
-     *   return content.toUpperCase();
-     * });
+     *   return content.toUpperCase()
+     * })
      * ```
      */
     addFilter<T = unknown>(hook: string, callback: FilterCallback<T>): void;
@@ -156,7 +59,7 @@ export declare class HookManager {
      *
      * @example
      * ```typescript
-     * const content = await core.hooks.applyFilters('content', 'hello world');
+     * const content = await core.hooks.applyFilters('content', 'hello world')
      * ```
      */
     applyFilters<T = unknown>(hook: string, initialValue: T, ...args: unknown[]): Promise<T>;
@@ -174,11 +77,8 @@ export declare class HookManager {
      * @example
      * ```typescript
      * core.hooks.addAction('user_registered', async (user: User) => {
-     *   await sendWelcomeEmail(user);
-     * });
-     *
-     * // With explicit type override
-     * core.hooks.addAction('sync_handler', handler, { type: 'async' });
+     *   await sendWelcomeEmail(user)
+     * })
      * ```
      */
     addAction<TArgs = unknown>(hook: string, callback: ActionCallback<TArgs>, options?: ListenerOptions): void;
@@ -188,6 +88,9 @@ export declare class HookManager {
      * This method supports both synchronous and asynchronous dispatch based on configuration.
      * In hybrid mode, it auto-detects async listeners and uses async dispatch.
      *
+     * 注意：dispatch 模式決策在此層級完成，以確保子類別（如 ObservableHookManager）
+     * 可透過多型覆寫正確攔截 doActionSync / doActionAsync 的呼叫。
+     *
      * @template TArgs - The type of arguments passed to the action.
      * @param hook - The name of the hook.
      * @param args - The arguments to pass to the callbacks.
@@ -195,7 +98,7 @@ export declare class HookManager {
      *
      * @example
      * ```typescript
-     * await core.hooks.doAction('user_registered', user);
+     * await core.hooks.doAction('user_registered', user)
      * ```
      */
     doAction<TArgs = unknown>(hook: string, args: TArgs, options?: EventOptions): Promise<void>;
@@ -205,18 +108,11 @@ export declare class HookManager {
      * @template TArgs - The type of arguments passed to the action.
      * @param hook - The name of the hook.
      * @param args - The arguments to pass to the callbacks.
-     * @internal
      */
     doActionSync<TArgs = unknown>(hook: string, args: TArgs): Promise<void>;
     /**
      * Run all registered actions asynchronously via priority queue.
      *
-     * This method uses EventPriorityQueue for async dispatch with support for:
-     * - Priority-based processing (high > normal > low)
-     * - Timeout handling
-     * - Ordering guarantees (strict, partition, none)
-     * - Idempotency
-     *
      * @template TArgs - The type of arguments passed to the action.
      * @param hook - The name of the hook.
      * @param args - The arguments to pass to the callbacks.
@@ -229,18 +125,10 @@ export declare class HookManager {
      *   ordering: 'partition',
      *   partitionKey: order.id,
      *   timeout: 5000,
-     * });
+     * })
      * ```
      */
     doActionAsync<TArgs = unknown>(hook: string, args: TArgs, options?: EventOptions): Promise<void>;
-    /**
-     * Determine if async dispatch should be used.
-     *
-     * @param callbacks - Callbacks to check
-     * @param options - Event options
-     * @returns True if async dispatch should be used
-     * @internal
-     */
     /**
      * Determine the dispatch mode for an event.
      *
@@ -253,28 +141,14 @@ export declare class HookManager {
     /**
      * Check if a callback is an async function (with caching).
      *
-     * Detection methods:
-     * 1. Check cache first
-     * 2. Check type override
-     * 3. Check constructor.name === 'AsyncFunction'
-     * 4. Fallback: Check function string representation
-     *
      * @param callback - The callback to check
      * @returns True if the callback is async
      * @public
      */
     isAsyncListener(callback: ActionCallback): boolean;
-    /**
-     * Cache async detection result.
-     * @internal
-     */
-    private cacheAsyncResult;
     /**
      * Runtime detection for functions that return Promises but aren't declared async.
      *
-     * This method executes the callback with test args and checks if the result is a Promise.
-     * Use with caution as it actually invokes the callback.
-     *
      * @param callback - The callback to check
      * @param testArgs - Arguments to pass to the callback for testing
      * @returns True if the callback returns a Promise
@@ -302,14 +176,6 @@ export declare class HookManager {
      * @public
      */
     hasAsyncListeners(hook: string): boolean;
-    /**
-     * Check if a listener is effectively async (considering type override).
-     *
-     * @param callback - The callback to check
-     * @returns True if the listener should be treated as async
-     * @internal
-     */
-    private isListenerEffectivelyAsync;
     /**
      * Get detailed information about all listeners for a hook.
      *
@@ -318,7 +184,6 @@ export declare class HookManager {
      * @public
      */
     getListenerInfo(hook: string): ListenerInfo[];
-    private shouldUseAsyncDispatch;
     /**
      * Get the current event queue depth.
      *
@@ -344,9 +209,14 @@ export declare class HookManager {
      *
      * @param hook - Hook name
      * @returns Array of callbacks
-     * @internal
      */
     getListeners(hook: string): ActionCallback[];
+    /**
+     * Remove all listeners for a specific action hook.
+     *
+     * @param hook - Hook name
+     */
+    removeAction(hook: string): void;
     /**
      * Update HookManager configuration.
      *
@@ -443,11 +313,17 @@ export declare class HookManager {
      */
     resetCircuitBreaker(eventName: string): boolean;
     /**
-     * Remove all listeners for a specific action hook.
+     * Get the current backpressure state.
      *
-     * @param hook - Hook name
+     * @returns Backpressure state ('NORMAL', 'WARNING', 'CRITICAL', 'OVERFLOW') or undefined if not enabled
      */
-    removeAction(hook: string): void;
+    getBackpressureState(): string | undefined;
+    /**
+     * Get backpressure metrics snapshot.
+     *
+     * @returns Backpressure metrics snapshot or undefined if not enabled
+     */
+    getBackpressureMetrics(): object | undefined;
     /**
      * Get the persistent DLQ manager instance.
      *
@@ -486,6 +362,69 @@ export declare class HookManager {
         succeeded: number;
         failed: number;
     }>;
+    /**
+     * Dispatch an event through Bull Queue（分佈式異步處理）.
+     *
+     * 與 doActionAsync() 不同：
+     * - doActionAsync() 使用 EventPriorityQueue (Memory-based)
+     * - dispatchQueued() 使用 Bull Queue (Redis-backed, 分佈式)
+     *
+     * 適用於需要持久化和跨進程處理的事件。
+     *
+     * @template TArgs - 事件參數類型
+     * @param event - 事件名稱
+     * @param args - 事件參數
+     * @param options - 事件選項（可選）
+     * @returns Job ID
+     * @throws 如果未配置 MessageQueueBridge 或沒有 listeners
+     *
+     * @example
+     * ```typescript
+     * const jobId = await hookManager.dispatchQueued('order:created', {
+     *   orderId: 'ORD-123',
+     *   amount: 999.99
+     * })
+     * ```
+     *
+     * @public
+     */
+    dispatchQueued<TArgs = unknown>(event: string, args: TArgs, options?: any): Promise<string>;
+    /**
+     * Dispatch an event through Bull Queue with delay（延遲隊列分發）.
+     *
+     * @template TArgs - 事件參數類型
+     * @param event - 事件名稱
+     * @param args - 事件參數
+     * @param delay - 延遲時間（毫秒）
+     * @param options - 事件選項（可選）
+     * @returns Job ID
+     * @throws 如果未配置 MessageQueueBridge
+     *
+     * @example
+     * ```typescript
+     * // 延遲 5 秒後處理
+     * const jobId = await hookManager.dispatchDeferredQueued(
+     *   'reminder:send',
+     *   { userId: '123' },
+     *   5000
+     * )
+     * ```
+     *
+     * @public
+     */
+    dispatchDeferredQueued<TArgs = unknown>(event: string, args: TArgs, delay: number, options?: any): Promise<string>;
+    /**
+     * Get the execution status of an event.
+     *
+     * 查詢事件執行狀態，支持查詢 Bull Queue 和 DLQ 中的事件。
+     *
+     * @param eventId - 事件 ID (task.id 或 jobId)
+     * @returns 事件狀態信息
+     * @throws 如果未配置 MessageQueueBridge
+     *
+     * @public
+     */
+    getEventStatus(eventId: string): Promise<any>;
     /**
      * Get persistent DLQ statistics.
      *

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

@@ -16,6 +16,7 @@ import { HookManager } from './HookManager';
 import type { fail } from './helpers/response';
 import type { ContentfulStatusCode, GravitoContext } from './http/types';
 import { type Logger } from './Logger';
+import { type ObservabilityProvider } from './observability/contracts';
 import type { ServiceProvider } from './ServiceProvider';
 /**
  * CacheService interface for orbit-injected cache
@@ -71,7 +72,14 @@ export type GravitoConfig = {
     config?: Record<string, unknown>;
     orbits?: (new () => GravitoOrbit)[] | GravitoOrbit[];
     /**
-     * HTTP Adapter to use. Defaults to PhotonAdapter.
+     * HTTP Adapter to use. Defaults to BunNativeAdapter in Bun environments.
+     * In non-Bun environments, must be provided explicitly.
+     * @example
+     * ```typescript
+     * import { PhotonAdapter } from '@gravito/photon/adapter'
+     * new PlanetCore({ adapter: new PhotonAdapter() })
+     * ```
+     * See https://gravito.dev/guides/http-adapters for available adapters.
      * @since 2.0.0
      */
     adapter?: HttpAdapter;
@@ -82,6 +90,53 @@ export type GravitoConfig = {
      * @since 2.0.0
      */
     container?: Container;
+    /**
+     * Observability configuration for event system.
+     * @since 2.1.0
+     */
+    observability?: {
+        /**
+         * Enable event system observability (metrics, tracing).
+         * @default false
+         */
+        enabled?: boolean;
+        /**
+         * Enable OpenTelemetry distributed tracing.
+         * @default false
+         */
+        tracing?: boolean;
+        /**
+         * Prefix for metric names.
+         * @default 'gravito_event_'
+         */
+        metricsPrefix?: string;
+        /**
+         * Prometheus metrics configuration.
+         */
+        prometheus?: {
+            /**
+             * Enable Prometheus metrics endpoint.
+             * @default true
+             */
+            enabled?: boolean;
+            /**
+             * Port for Prometheus metrics endpoint.
+             * @default 9090
+             */
+            port?: number;
+            /**
+             * Endpoint path for metrics.
+             * @default '/metrics'
+             */
+            endpoint?: string;
+        };
+    };
+    /**
+     * Observability provider for distributed tracing and metrics.
+     * If provided, this will be used instead of the default OTel setup.
+     * @since 2.2.0
+     */
+    observabilityProvider?: ObservabilityProvider;
 };
 import { Router } from './Router';
 import { Encrypter } from './security/Encrypter';
@@ -119,9 +174,32 @@ export declare class PlanetCore {
     services: Map<string, unknown>;
     encrypter?: Encrypter;
     hasher: BunHasher;
+    /**
+     * Observability provider for distributed tracing and metrics.
+     * @since 2.2.0
+     */
+    observabilityProvider: ObservabilityProvider;
     private providers;
     private deferredProviders;
     private bootedProviders;
+    private isShuttingDown;
+    /**
+     * Initialize observability asynchronously (metrics, tracing, Prometheus).
+     * This is called from constructor but doesn't block initialization.
+     *
+     * Phase 2.2 Update: Now uses the observabilityProvider passed from @gravito/monitor
+     * or falls back to OTel implementation if available for backward compatibility.
+     *
+     * @internal
+     */
+    private initializeObservabilityAsync;
+    /**
+     * Initialize Prometheus metrics asynchronously.
+     *
+     * @internal
+     * @deprecated Prometheus setup has been moved to @gravito/monitor
+     */
+    private initializePrometheusAsync;
     /**
      * Register a service provider to the core.
      *
@@ -155,6 +233,34 @@ export declare class PlanetCore {
      * ```
      */
     bootstrap(): Promise<void>;
+    /**
+     * Called when the application is ready to accept requests.
+     *
+     * Invokes the `onReady()` lifecycle hook on all providers.
+     * Called automatically at the end of `bootstrap()`.
+     *
+     * @returns Promise that resolves when all providers are ready.
+     *
+     * @example
+     * ```typescript
+     * await core.ready();
+     * ```
+     */
+    ready(): Promise<void>;
+    /**
+     * Gracefully shutdown the application.
+     *
+     * Invokes the `onShutdown()` lifecycle hook on all providers in reverse order (LIFO).
+     * Should be called when the application receives a termination signal.
+     *
+     * @returns Promise that resolves when all providers have shut down.
+     *
+     * @example
+     * ```typescript
+     * process.on('SIGTERM', () => core.shutdown());
+     * ```
+     */
+    shutdown(): Promise<void>;
     /**
      * Setup deferred provider resolution.
      * Wraps container.make to auto-register deferred providers on first request.
@@ -179,7 +285,14 @@ export declare class PlanetCore {
         config?: Record<string, unknown>;
         adapter?: HttpAdapter;
         container?: Container;
+        observabilityProvider?: ObservabilityProvider;
     });
+    /**
+     * Setup process signal handlers for graceful shutdown
+     *
+     * @internal
+     */
+    private setupSignalHandlers;
     /**
      * Programmatically register an infrastructure module (Orbit).
      * @since 2.0.0

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

@@ -0,0 +1,97 @@
+/**
+ * @fileoverview RequestContext - AsyncLocalStorage-based request context management
+ *
+ * Allows deep service layers to access request-scoped data (requestId, userId, etc.)
+ * without passing parameters through the call stack.
+ *
+ * @module @gravito/core/RequestContext
+ * @since 2.2.0
+ */
+/**
+ * 請求上下文資料介面
+ * 包含請求相關的唯一識別碼和上下文資訊
+ * @public
+ */
+export interface RequestContextData {
+    /** 唯一的請求識別碼 */
+    requestId: string;
+    /** 使用者 ID（可選） */
+    userId?: string;
+    /** 租戶 ID（可選） */
+    tenantId?: string;
+    /** 追蹤 ID（可選） */
+    traceId?: string;
+    /** 自訂欄位 */
+    [key: string]: unknown;
+}
+/**
+ * RequestContext 物件 - 管理請求上下文的 API
+ *
+ * 提供在非同步鏈中存取和設定請求上下文的方法
+ * @public
+ */
+export declare const RequestContext: {
+    /**
+     * 在給定的上下文中執行函式
+     *
+     * 確保函式及其所有非同步呼叫都在同一個上下文中執行
+     *
+     * @param data - 請求上下文資料
+     * @param fn - 要執行的函式（可以是非同步的或同步的）
+     * @returns 如果函式是非同步的，返回 Promise；如果是同步的，直接返回值
+     *
+     * @example
+     * ```typescript
+     * await RequestContext.run({ requestId: 'req-123' }, async () => {
+     *   const userId = RequestContext.get()?.userId;
+     * });
+     *
+     * const result = RequestContext.run({ requestId: 'req-123' }, () => {
+     *   return 'sync-result';
+     * });
+     * ```
+     */
+    run<T>(data: RequestContextData, fn: () => T | Promise<T>): T | Promise<T>;
+    /**
+     * 獲取當前請求的上下文資料
+     *
+     * @returns 請求上下文資料，如果不在請求上下文中則返回 undefined
+     *
+     * @example
+     * ```typescript
+     * const context = RequestContext.get();
+     * if (context) {
+     *   console.log(context.requestId);
+     * }
+     * ```
+     */
+    get(): RequestContextData | undefined;
+    /**
+     * 獲取當前請求的上下文資料，如果不存在則拋出錯誤
+     *
+     * @returns 請求上下文資料
+     * @throws Error 如果不在請求上下文中
+     *
+     * @example
+     * ```typescript
+     * const context = RequestContext.getOrThrow();
+     * console.log(context.requestId); // 保證不為 undefined
+     * ```
+     */
+    getOrThrow(): RequestContextData;
+    /**
+     * 在當前上下文中設定或修改值
+     *
+     * @param key - 要設定的欄位名稱
+     * @param value - 要設定的值
+     * @throws Error 如果不在請求上下文中
+     *
+     * @example
+     * ```typescript
+     * RequestContext.set('userId', 'user-456');
+     * const userId = RequestContext.get()?.userId; // 'user-456'
+     * ```
+     */
+    set(key: string, value: unknown): void;
+};
+export default RequestContext;