@gravito/ripple 4.0.0 → 4.0.1

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

@@ -1,3 +1,9 @@
+/**
+ * Configuration manager (ConfigManager)
+ *
+ * Unifies environment variables and application configuration access.
+ */
+import type { ZodSchema } from 'zod';
 /**
  * ConfigManager - Central configuration store.
  * Supports loading from environment variables and initial objects.
@@ -5,6 +11,7 @@
  */
 export declare class ConfigManager {
     private config;
+    private schema;
     constructor(initialConfig?: Record<string, unknown>);
     /**
      * Load all environment variables from the active runtime.
@@ -23,4 +30,36 @@ export declare class ConfigManager {
      * Check whether a key exists.
      */
     has(key: string): boolean;
+    /**
+     * Define a Zod schema for configuration validation.
+     *
+     * @param schema - Zod schema for validation
+     *
+     * @example
+     * ```typescript
+     * config.defineSchema(z.object({
+     *   DATABASE_URL: z.string().url(),
+     *   PORT: z.number().default(3000),
+     * }))
+     * ```
+     */
+    defineSchema(schema: ZodSchema): void;
+    /**
+     * Validate configuration against the defined schema.
+     *
+     * Should be called during bootstrap to catch configuration errors early.
+     *
+     * @throws Error if validation fails with details about missing/invalid fields
+     *
+     * @example
+     * ```typescript
+     * try {
+     *   config.validate()
+     * } catch (error) {
+     *   console.error('Config validation failed:', error.message)
+     *   process.exit(1)
+     * }
+     * ```
+     */
+    validate(): void;
 }

package/dist/core/src/Container/RequestScopeManager.d.ts

@@ -0,0 +1,62 @@
+import type { ServiceKey } from '../Container';
+import { RequestScopeMetrics, type RequestScopeObserver } from './RequestScopeMetrics';
+/**
+ * Manages request-scoped service instances within a single HTTP request.
+ *
+ * Each request gets its own RequestScopeManager instance with isolated state.
+ * Services are cached within the request and automatically cleaned up when
+ * the request ends.
+ *
+ * @example
+ * ```typescript
+ * const scope = new RequestScopeManager()
+ * const cache = scope.resolve('productCache', () => new ProductCache())
+ * // ... use cache ...
+ * await scope.cleanup() // Called automatically by Gravito engine
+ * ```
+ */
+export declare class RequestScopeManager {
+    private scoped;
+    private metadata;
+    private metrics;
+    private observer;
+    constructor(observer?: RequestScopeObserver);
+    /**
+     * Set observer for monitoring scope lifecycle
+     */
+    setObserver(observer: RequestScopeObserver): void;
+    /**
+     * Get metrics for this scope
+     */
+    getMetrics(): RequestScopeMetrics;
+    /**
+     * Resolve or retrieve a request-scoped service instance.
+     *
+     * If the service already exists in this scope, returns the cached instance.
+     * Otherwise, calls the factory function to create a new instance and caches it.
+     *
+     * Automatically detects and records services with cleanup methods.
+     *
+     * @template T - The type of the service.
+     * @param key - The service key (for caching).
+     * @param factory - Factory function to create the instance if not cached.
+     * @returns The cached or newly created instance.
+     */
+    resolve<T>(key: ServiceKey, factory: () => T): T;
+    /**
+     * Clean up all request-scoped instances.
+     *
+     * Calls the cleanup() method on each service that has one.
+     * Silently ignores cleanup errors to prevent cascading failures.
+     * Called automatically by the Gravito engine in the request finally block.
+     *
+     * @returns Promise that resolves when all cleanup is complete.
+     */
+    cleanup(): Promise<void>;
+    /**
+     * Get the number of services in this scope (for monitoring).
+     *
+     * @returns The count of cached services.
+     */
+    size(): number;
+}

package/dist/core/src/Container/RequestScopeMetrics.d.ts

@@ -0,0 +1,144 @@
+/**
+ * RequestScopeMetrics - Observability for RequestScope lifecycle
+ *
+ * Tracks cleanup execution time, scope size, and service counts
+ * for performance monitoring and diagnostics.
+ *
+ * @example
+ * ```typescript
+ * const metrics = new RequestScopeMetrics()
+ * metrics.recordCleanupStart()
+ * await scope.cleanup()
+ * metrics.recordCleanupEnd()
+ *
+ * console.log(metrics.toJSON())
+ * // { cleanupDuration: 2.5, scopeSize: 3, servicesCleaned: 3 }
+ * ```
+ */
+export declare class RequestScopeMetrics {
+    private cleanupStartTime;
+    private cleanupDuration;
+    private scopeSize;
+    private servicesCleaned;
+    private errorsOccurred;
+    /**
+     * Record start of cleanup operation
+     */
+    recordCleanupStart(): void;
+    /**
+     * Record end of cleanup operation
+     *
+     * @param scopeSize - Number of services in the scope
+     * @param servicesCleaned - Number of services that had cleanup called
+     * @param errorsOccurred - Number of cleanup errors
+     */
+    recordCleanupEnd(scopeSize: number, servicesCleaned: number, errorsOccurred?: number): void;
+    /**
+     * Get cleanup duration in milliseconds
+     *
+     * @returns Duration in ms, or null if cleanup not completed
+     */
+    getCleanupDuration(): number | null;
+    /**
+     * Check if cleanup took longer than threshold (default 2ms)
+     * Useful for detecting slow cleanups
+     *
+     * @param thresholdMs - Threshold in milliseconds
+     * @returns True if cleanup exceeded threshold
+     */
+    isSlowCleanup(thresholdMs?: number): boolean;
+    /**
+     * Export metrics as JSON for logging/monitoring
+     */
+    toJSON(): {
+        cleanupDuration: number | null;
+        scopeSize: number;
+        servicesCleaned: number;
+        errorsOccurred: number;
+        hasErrors: boolean;
+        isSlowCleanup: boolean;
+    };
+    /**
+     * Export metrics as compact string for logging
+     */
+    toString(): string;
+}
+/**
+ * RequestScopeObserver - Hook for monitoring RequestScope lifecycle
+ *
+ * Implement this interface to receive callbacks during scope operations
+ */
+export interface RequestScopeObserver {
+    /**
+     * Called when a service is resolved in the scope
+     */
+    onServiceResolved?(key: string | symbol, isFromCache: boolean): void;
+    /**
+     * Called when cleanup starts
+     */
+    onCleanupStart?(): void;
+    /**
+     * Called when cleanup completes
+     */
+    onCleanupEnd?(metrics: RequestScopeMetrics): void;
+    /**
+     * Called when cleanup encounters an error
+     */
+    onCleanupError?(error: Error): void;
+}
+/**
+ * RequestScopeMetricsCollector - Aggregates metrics across multiple scopes
+ *
+ * Used for application-level monitoring and performance tracking
+ *
+ * @example
+ * ```typescript
+ * const collector = new RequestScopeMetricsCollector()
+ *
+ * // Record metrics from multiple requests
+ * collector.record(metrics1)
+ * collector.record(metrics2)
+ * collector.record(metrics3)
+ *
+ * // Get aggregated stats
+ * const stats = collector.getStats()
+ * console.log(stats.averageCleanupTime) // 3.5ms
+ * ```
+ */
+export declare class RequestScopeMetricsCollector {
+    private metrics;
+    /**
+     * Record metrics from a request scope
+     */
+    record(metrics: RequestScopeMetrics): void;
+    /**
+     * Get aggregated statistics
+     */
+    getStats(): {
+        count: number;
+        averageCleanupTime: number | null;
+        maxCleanupTime: number | null;
+        minCleanupTime: number | null;
+        totalErrorCount: number;
+        errorRate: number;
+    };
+    /**
+     * Clear collected metrics
+     */
+    clear(): void;
+    /**
+     * Get number of recorded metrics
+     */
+    size(): number;
+    /**
+     * Export metrics as JSON array
+     */
+    toJSON(): {
+        cleanupDuration: number | null;
+        scopeSize: number;
+        servicesCleaned: number;
+        errorsOccurred: number;
+        hasErrors: boolean;
+        isSlowCleanup: boolean;
+    }[];
+}

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

@@ -1,3 +1,4 @@
+import type { RequestScopeManager } from './Container/RequestScopeManager';
 /**
  * Factory type for creating service instances
  */
@@ -31,6 +32,27 @@ export declare class Container {
     private bindings;
     private instances;
     private resolutionStack;
+    /**
+     * Run a function within a request scope context.
+     *
+     * All service resolutions within the function will use the provided scope,
+     * enabling request-scoped service instances to be properly isolated.
+     *
+     * @template T - The return type of the function.
+     * @param scope - The RequestScopeManager for this request.
+     * @param fn - The function to execute within the scope.
+     * @returns The result of the function.
+     *
+     * @example
+     * ```typescript
+     * const scope = new RequestScopeManager()
+     * const result = await Container.runWithScope(scope, async () => {
+     *   const service = container.make('requestScoped')
+     *   return service.doSomething()
+     * })
+     * ```
+     */
+    static runWithScope<T>(scope: RequestScopeManager, fn: () => T | Promise<T>): T | Promise<T>;
     /**
      * Bind a service to the container.
      *
@@ -63,6 +85,22 @@ export declare class Container {
      * ```
      */
     singleton<T>(key: ServiceKey, factory: Factory<T>): void;
+    /**
+     * Bind a request-scoped service to the container.
+     *
+     * A new instance will be created for each request and cached within that request.
+     * The service is automatically cleaned up when the request ends.
+     *
+     * @template T - The type of the service being bound.
+     * @param key - The unique identifier for the service.
+     * @param factory - The factory function that creates the service instance.
+     *
+     * @example
+     * ```typescript
+     * container.scoped('requestCache', (c) => new RequestProductCache());
+     * ```
+     */
+    scoped<T>(key: ServiceKey, factory: Factory<T>): void;
     /**
      * Register an existing instance as a shared service.
      *
@@ -70,6 +108,13 @@ export declare class Container {
      * @param instance - The instance to register.
      */
     instance<T>(key: ServiceKey, instance: T): void;
+    /**
+     * Check if a service is request-scoped.
+     *
+     * @param key - The service key to check.
+     * @returns True if the service is request-scoped.
+     */
+    isRequestScoped(key: ServiceKey): boolean;
     /**
      * Resolve a service instance from the container.
      *

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

@@ -42,6 +42,9 @@ export declare class ErrorHandler {
     constructor(deps: ErrorHandlerDeps);
     /**
      * Handle application errors
+     *
+     * Integrates RequestScope cleanup to ensure proper resource management
+     * even when errors occur during request processing.
      */
     handleError(err: unknown, c: GravitoContext): Promise<Response>;
     /**

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

@@ -98,6 +98,16 @@ export interface HookManagerConfig {
      * @default false
      */
     enablePersistentDLQ?: boolean;
+    /**
+     * Message Queue Bridge for distributed event processing via Bull Queue.
+     * When provided, enables dispatchQueued() method for routing events to Redis-backed queue.
+     */
+    messageQueueBridge?: any;
+    /**
+     * Event aggregation configuration (FS-102).
+     * Enables deduplication and micro-batching for improved throughput.
+     */
+    aggregation?: any;
 }
 export declare class HookManager {
     private filters;
@@ -106,9 +116,11 @@ export declare class HookManager {
     private backend;
     private dlq?;
     private persistentDlqManager?;
+    private messageQueueBridge?;
     private idempotencyCache;
     private config;
     private migrationWarner;
+    private aggregationManager?;
     /**
      * Cache for async detection results (WeakMap for automatic garbage collection).
      * @internal
@@ -442,6 +454,18 @@ export declare class HookManager {
      * @returns True if reset, false if circuit breaker not found
      */
     resetCircuitBreaker(eventName: string): boolean;
+    /**
+     * Get the current backpressure state.
+     *
+     * @returns Backpressure state ('NORMAL', 'WARNING', 'CRITICAL', 'OVERFLOW') or undefined if not enabled
+     */
+    getBackpressureState(): string | undefined;
+    /**
+     * Get backpressure metrics snapshot.
+     *
+     * @returns Backpressure metrics snapshot or undefined if not enabled
+     */
+    getBackpressureMetrics(): object | undefined;
     /**
      * Remove all listeners for a specific action hook.
      *
@@ -486,6 +510,77 @@ 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 (延遲隊列分發).
+     *
+     * 通過 Bull Queue 的 delayed jobs 功能實現延遲處理。
+     *
+     * @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
+     *
+     * @example
+     * ```typescript
+     * const status = await hookManager.getEventStatus('queue-1707000000000-abc123')
+     * console.log(status) // { eventId, status, attempts, createdAt, ... }
+     * ```
+     *
+     * @public
+     */
+    getEventStatus(eventId: string): Promise<any>;
     /**
      * Get persistent DLQ statistics.
      *

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

@@ -82,6 +82,47 @@ 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;
+        };
+    };
 };
 import { Router } from './Router';
 import { Encrypter } from './security/Encrypter';
@@ -122,6 +163,20 @@ export declare class PlanetCore {
     private providers;
     private deferredProviders;
     private bootedProviders;
+    private isShuttingDown;
+    /**
+     * Initialize observability asynchronously (metrics, tracing, Prometheus).
+     * This is called from constructor but doesn't block initialization.
+     *
+     * @internal
+     */
+    private initializeObservabilityAsync;
+    /**
+     * Initialize Prometheus metrics asynchronously.
+     *
+     * @internal
+     */
+    private initializePrometheusAsync;
     /**
      * Register a service provider to the core.
      *
@@ -155,6 +210,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.
@@ -180,6 +263,12 @@ export declare class PlanetCore {
         adapter?: HttpAdapter;
         container?: Container;
     });
+    /**
+     * 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;

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

@@ -74,6 +74,28 @@ export declare abstract class ServiceProvider {
      * @param core - The PlanetCore application instance
      */
     boot?(core: PlanetCore): void | Promise<void>;
+    /**
+     * Called when the application is ready to accept requests.
+     *
+     * This method is called after ALL providers have booted.
+     * Use this for final initialization before the server starts accepting traffic.
+     *
+     * @param core - The PlanetCore application instance
+     * @since 2.2.0
+     */
+    onReady?(core: PlanetCore): void | Promise<void>;
+    /**
+     * Called when the application is shutting down.
+     *
+     * This method is called during graceful shutdown.
+     * Use this to clean up resources, close connections, etc.
+     *
+     * Providers are called in reverse order (LIFO).
+     *
+     * @param core - The PlanetCore application instance
+     * @since 2.2.0
+     */
+    onShutdown?(core: PlanetCore): void | Promise<void>;
     /**
      * Set the core instance reference.
      * Called internally by the application during registration.