@gravito/ripple 3.1.0 → 4.0.1

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/Router.d.ts

@@ -125,7 +125,7 @@ export declare class Router {
         path: string;
         domain?: string;
     }>;
-    private controllers;
+    private dispatcher;
     private namedRoutes;
     private bindings;
     /**
@@ -268,10 +268,6 @@ export declare class Router {
      * Internal Request Registration
      */
     req(method: HttpMethod, path: string, requestOrHandlerOrMiddleware: FormRequestClass | RouteHandler | GravitoMiddleware | GravitoMiddleware[], handler?: RouteHandler, options?: RouteOptions): Route;
-    /**
-     * Resolve Controller Instance and Method
-     */
-    private resolveControllerHandler;
 }
 /**
  * Standard RESTful resource action names.

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.

package/dist/core/src/adapters/GravitoEngineAdapter.d.ts

@@ -23,4 +23,5 @@ export declare class GravitoEngineAdapter<V extends GravitoVariables = GravitoVa
     fetch: (request: Request, _server?: unknown) => Response | Promise<Response>;
     warmup(paths: string[]): Promise<void>;
     createContext(_request: Request): GravitoContext<V>;
+    useScoped(scope: string, path: string, ...middleware: GravitoMiddleware<V>[]): void;
 }

package/dist/core/src/adapters/PhotonAdapter.d.ts

@@ -8,6 +8,7 @@
  * @since 2.0.0
  */
 import type { Context, Handler, MiddlewareHandler, Photon } from '@gravito/photon';
+import { RequestScopeManager } from '../Container/RequestScopeManager';
 import type { GravitoContext, GravitoErrorHandler, GravitoHandler, GravitoMiddleware, GravitoNotFoundHandler, GravitoRequest, GravitoVariables, HttpMethod, ProxyOptions, StatusCode } from '../http/types';
 import type { AdapterConfig, HttpAdapter, RouteDefinition } from './types';
 /**
@@ -50,6 +51,7 @@ declare class PhotonRequestWrapper implements GravitoRequest {
 declare class PhotonContextWrapper<V extends GravitoVariables = GravitoVariables> implements GravitoContext<V> {
     private _req;
     private photonCtx;
+    private _requestScope;
     route: (name: string, params?: Record<string, any>, query?: Record<string, any>) => string;
     /**
      * Reset the wrapper for pooling
@@ -90,6 +92,8 @@ declare class PhotonContextWrapper<V extends GravitoVariables = GravitoVariables
     get env(): Record<string, unknown> | undefined;
     get native(): Context;
     forward(target: string, options?: ProxyOptions): Promise<Response>;
+    requestScope(): RequestScopeManager;
+    scoped<T>(key: string | symbol, factory: () => T): T;
 }
 /**
  * Convert a GravitoHandler to a Photon Handler
@@ -136,6 +140,7 @@ export declare class PhotonAdapter<V extends GravitoVariables = GravitoVariables
     routes(routes: RouteDefinition[]): void;
     use(path: string, ...middleware: GravitoMiddleware<V>[]): void;
     useGlobal(...middleware: GravitoMiddleware<V>[]): void;
+    useScoped(scope: string, path: string, ...middleware: GravitoMiddleware<V>[]): void;
     mount(path: string, subAdapter: HttpAdapter<V>): void;
     onError(handler: GravitoErrorHandler<V>): void;
     onNotFound(handler: GravitoNotFoundHandler<V>): void;

package/dist/core/src/adapters/bun/BunContext.d.ts

@@ -1,3 +1,4 @@
+import { RequestScopeManager } from '../../Container/RequestScopeManager';
 import type { ContentfulStatusCode, GravitoContext, GravitoVariables, ProxyOptions, StatusCode } from '../../http/types';
 import { BunRequest } from './BunRequest';
 /**
@@ -8,6 +9,7 @@ export declare class BunContext<V extends GravitoVariables = GravitoVariables> i
     readonly env: Record<string, unknown>;
     readonly req: BunRequest;
     private _variables;
+    private _requestScope;
     /**
      * URL generator helper
      */
@@ -42,4 +44,6 @@ export declare class BunContext<V extends GravitoVariables = GravitoVariables> i
     get<K extends keyof V>(key: K): V[K];
     set<K extends keyof V>(key: K, value: V[K]): void;
     get executionCtx(): ExecutionContext | undefined;
+    requestScope(): RequestScopeManager;
+    scoped<T>(key: string | symbol, factory: () => T): T;
 }

package/dist/core/src/adapters/bun/BunNativeAdapter.d.ts

@@ -17,6 +17,7 @@ export declare class BunNativeAdapter implements HttpAdapter {
     routes(routes: RouteDefinition[]): void;
     use(path: string, ...middleware: GravitoMiddleware[]): void;
     useGlobal(...middleware: GravitoMiddleware[]): void;
+    useScoped(scope: string, path: string, ...middleware: GravitoMiddleware[]): void;
     mount(path: string, subAdapter: HttpAdapter): void;
     createContext(request: Request): GravitoContext;
     onError(handler: GravitoErrorHandler): void;

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

@@ -115,6 +115,33 @@ export interface HttpAdapter<V extends GravitoVariables = GravitoVariables> {
      * @param middleware - Middleware function
      */
     useGlobal(...middleware: GravitoMiddleware<V>[]): void;
+    /**
+     * Register a scoped middleware for Orbit-level isolation
+     *
+     * Unlike regular `use()`, this method enforces stricter scoping rules:
+     * - REJECTS '*' wildcard paths (prevents global middleware in Orbits)
+     * - ENFORCES that all middleware paths must include the scope prefix
+     * - Throws error if attempting to register global middleware within an Orbit scope
+     *
+     * This is designed to prevent accidental middleware cross-contamination
+     * when multiple Orbits are mounted to a single PlanetCore instance.
+     *
+     * @param scope - The scope/path prefix (e.g., '/api', '/blog')
+     * @param path - Path pattern to match (cannot be '*')
+     * @param middleware - One or more middleware functions
+     * @throws {Error} If path is '*' when in Orbit scope
+     * @since 2.3.0
+     *
+     * @example
+     * ```typescript
+     * // Correct: Scoped to specific path
+     * adapter.useScoped('/api', '/users/*', authMiddleware)
+     *
+     * // Error: Cannot use wildcard in Orbit scope
+     * adapter.useScoped('/api', '*', loggerMiddleware)
+     * ```
+     */
+    useScoped(scope: string, path: string, ...middleware: GravitoMiddleware<V>[]): void;
     /**
      * Mount a sub-adapter at a path
      *

package/dist/core/src/cli/queue-commands.d.ts

@@ -0,0 +1,6 @@
+import type { CommandKernel } from '../CommandKernel';
+import type { QueueDashboard } from '../observability/QueueDashboard';
+/**
+ * Register queue management commands with CommandKernel
+ */
+export declare function registerQueueCommands(kernel: CommandKernel, dashboard: QueueDashboard): void;

package/dist/core/src/engine/AOTRouter.d.ts

@@ -34,9 +34,15 @@ export declare class AOTRouter {
     readonly globalMiddleware: Middleware[];
     /** @internal */
     readonly pathMiddleware: Map<string, Middleware[]>;
+    private dynamicRoutePatterns;
     private middlewareCache;
     private cacheMaxSize;
-    private version;
+    private _version;
+    /**
+     * Get the current version for cache invalidation
+     * Incremented whenever middleware or routes are modified
+     */
+    get version(): number;
     /**
      * Register a route
      *
@@ -111,17 +117,6 @@ export declare class AOTRouter {
      * @returns True if pattern matches
      */
     private matchPattern;
-    /**
-     * Find the original route key for a matched dynamic route
-     *
-     * This is needed to look up route-specific middleware.
-     * It's a bit of a hack, but avoids storing duplicate data.
-     *
-     * @param method - HTTP method
-     * @param path - Matched path
-     * @returns Route key or null
-     */
-    private findDynamicRouteKey;
     /**
      * Get all registered routes (for debugging)
      */

package/dist/core/src/engine/FastContext.d.ts

@@ -6,6 +6,7 @@
  *
  * @module @gravito/core/engine
  */
+import { RequestScopeManager } from '../Container/RequestScopeManager';
 import type { FastRequest, FastContext as IFastContext } from './types';
 /**
  * Lazy-parsed request wrapper
@@ -17,17 +18,23 @@ declare class FastRequestImpl implements FastRequest {
     private _request;
     private _params;
     private _path;
+    private _routePattern?;
     private _url;
     private _query;
     private _headers;
     private _cachedJson;
     private _jsonParsed;
+    private _cachedText;
+    private _textParsed;
+    private _cachedFormData;
+    private _formDataParsed;
+    private _cachedQueries;
     private _ctx;
     constructor(ctx: FastContext);
     /**
      * Initialize for new request
      */
-    init(request: Request, params?: Record<string, string>, path?: string): this;
+    init(request: Request, params?: Record<string, string>, path?: string, routePattern?: string): this;
     /**
      * Reset for pooling
      */
@@ -36,6 +43,7 @@ declare class FastRequestImpl implements FastRequest {
     get url(): string;
     get method(): string;
     get path(): string;
+    get routePattern(): string | undefined;
     param(name: string): string | undefined;
     params(): Record<string, string>;
     private getUrl;
@@ -58,12 +66,13 @@ export declare class FastContext implements IFastContext {
     readonly req: FastRequestImpl;
     private _headers;
     _isReleased: boolean;
+    private _requestScope;
     /**
      * Initialize context for a new request
      *
      * This is called when acquiring from the pool.
      */
-    init(request: Request, params?: Record<string, string>, path?: string): this;
+    init(request: Request, params?: Record<string, string>, path?: string, routePattern?: string): this;
     /**
      * Reset context for pooling (Cleanup)
      *
@@ -92,6 +101,22 @@ export declare class FastContext implements IFastContext {
     private _store;
     get<T>(key: string): T;
     set(key: string, value: any): void;
+    /**
+     * Get the request-scoped service manager for this request.
+     *
+     * @returns The RequestScopeManager for this request.
+     * @throws Error if called before init() or after reset().
+     */
+    requestScope(): RequestScopeManager;
+    /**
+     * Resolve a request-scoped service (convenience method).
+     *
+     * @template T - The service type.
+     * @param key - The service key for caching.
+     * @param factory - Factory function to create the service.
+     * @returns The cached or newly created service instance.
+     */
+    scoped<T>(key: string | symbol, factory: () => T): T;
     route: (name: string, params?: any, query?: any) => string;
     get native(): this;
 }

package/dist/core/src/engine/Gravito.d.ts

@@ -25,7 +25,6 @@ export declare class Gravito {
     staticRoutes: Map<string, RouteMetadata>;
     private isPureStaticApp;
     private compiledDynamicRoutes;
-    private middlewareVersion;
     /**
      * Create a new Gravito instance
      *

package/dist/core/src/engine/MinimalContext.d.ts

@@ -11,6 +11,7 @@
  *
  * @module @gravito/core/engine
  */
+import { RequestScopeManager } from '../Container/RequestScopeManager';
 import type { FastRequest, FastContext as IFastContext } from './types';
 /**
  * Minimal request wrapper
@@ -19,11 +20,17 @@ declare class MinimalRequest implements FastRequest {
     private readonly _request;
     private readonly _params;
     private readonly _path;
+    private readonly _routePattern?;
     private _searchParams;
-    constructor(_request: Request, _params: Record<string, string>, _path: string);
+    private _cachedQueries;
+    private _cachedJsonPromise;
+    private _cachedTextPromise;
+    private _cachedFormDataPromise;
+    constructor(_request: Request, _params: Record<string, string>, _path: string, _routePattern?: string | undefined);
     get url(): string;
     get method(): string;
     get path(): string;
+    get routePattern(): string | undefined;
     param(name: string): string | undefined;
     params(): Record<string, string>;
     /**
@@ -51,7 +58,8 @@ declare class MinimalRequest implements FastRequest {
 export declare class MinimalContext implements IFastContext {
     readonly req: MinimalRequest;
     private _resHeaders;
-    constructor(request: Request, params: Record<string, string>, path: string);
+    private _requestScope;
+    constructor(request: Request, params: Record<string, string>, path: string, routePattern?: string);
     private getHeaders;
     json<T>(data: T, status?: number): Response;
     text(text: string, status?: number): Response;
@@ -69,6 +77,21 @@ export declare class MinimalContext implements IFastContext {
     forward(target: string, _options?: any): Promise<Response>;
     get<T>(_key: string): T;
     set(_key: string, _value: any): void;
+    /**
+     * Get the request-scoped service manager for this request.
+     *
+     * @returns The RequestScopeManager for this request.
+     */
+    requestScope(): RequestScopeManager;
+    /**
+     * Resolve a request-scoped service (convenience method).
+     *
+     * @template T - The service type.
+     * @param key - The service key for caching.
+     * @param factory - Factory function to create the service.
+     * @returns The cached or newly created service instance.
+     */
+    scoped<T>(key: string | symbol, factory: () => T): T;
     route: (name: string, params?: any, query?: any) => string;
     get native(): this;
     init(_request: Request, _params?: Record<string, string>, _path?: string): this;

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

@@ -32,11 +32,14 @@ export interface FastContext {
     /** Context Variables */
     get<T>(key: string): T;
     set(key: string, value: any): void;
+    /** Request Scope Management */
+    requestScope(): any;
+    scoped<T>(key: string | symbol, factory: () => T): T;
     /** Lifecycle helpers */
     route: (name: string, params?: any, query?: any) => string;
     readonly native: any;
     /** Internal initialization for pooling */
-    init(request: Request, params?: Record<string, string>, path?: string): this;
+    init(request: Request, params?: Record<string, string>, path?: string, routePattern?: string): this;
     /** Internal cleanup for pooling */
     reset(): void;
 }
@@ -50,6 +53,11 @@ export interface FastRequest {
     readonly method: string;
     /** Path without query */
     readonly path: string;
+    /**
+     * Route pattern (e.g., /users/:id) for metrics labeling
+     * Prevents high cardinality issues in monitoring systems
+     */
+    readonly routePattern?: string;
     /** Get route parameter */
     param(name: string): string | undefined;
     /** Get all route parameters */

package/dist/core/src/error-handling/RequestScopeErrorContext.d.ts

@@ -0,0 +1,126 @@
+/**
+ * RequestScope-Aware Error Handling
+ *
+ * Integrates RequestScope lifecycle with error handling to provide:
+ * - Error context with request-scoped resources
+ * - Automatic cleanup of scoped services on error
+ * - Request tracing and diagnostics
+ * - Resource leak detection
+ */
+import type { RequestScopeManager } from '../Container/RequestScopeManager';
+import type { RequestScopeMetrics } from '../Container/RequestScopeMetrics';
+import type { GravitoContext } from '../http/types';
+/**
+ * Extended error context with RequestScope information
+ *
+ * Provides error handlers access to request-scoped resources
+ * for proper resource cleanup and error diagnostics.
+ */
+export interface RequestScopeErrorContext {
+    /**
+     * The original error that was thrown
+     */
+    error: unknown;
+    /**
+     * HTTP context where error occurred
+     */
+    context: GravitoContext;
+    /**
+     * RequestScope manager for this request
+     * Allows error handlers to access or clean up scoped resources
+     */
+    scope?: RequestScopeManager;
+    /**
+     * Metrics about the request scope state
+     * Useful for diagnostics and understanding resource usage
+     */
+    scopeMetrics?: RequestScopeMetrics;
+    /**
+     * Number of scoped services at time of error
+     * High numbers might indicate resource leaks
+     */
+    scopeSize?: number;
+    /**
+     * Request processing time in milliseconds
+     * Useful for timeout errors
+     */
+    duration?: number;
+    /**
+     * Additional diagnostic information
+     */
+    diagnostics?: {
+        servicesCleanedUp?: string[];
+        cleanupErrors?: Array<{
+            service: string;
+            error: unknown;
+        }>;
+        peakMemoryMb?: number;
+    };
+}
+/**
+ * Error that occurred during RequestScope cleanup
+ *
+ * Wraps original error with cleanup context for proper error reporting
+ */
+export declare class RequestScopeCleanupError extends Error {
+    originalError: unknown;
+    cleanupErrors: Array<{
+        service: string;
+        error: unknown;
+    }>;
+    constructor(message: string, originalError: unknown, cleanupErrors: Array<{
+        service: string;
+        error: unknown;
+    }>);
+}
+/**
+ * Helper to extract RequestScope context from GravitoContext
+ *
+ * @param ctx - Gravito context
+ * @returns RequestScope error context with available information
+ */
+export declare function extractRequestScopeErrorContext(ctx: GravitoContext, error: unknown): RequestScopeErrorContext;
+/**
+ * Cleanup scoped services safely during error handling
+ *
+ * Ensures all scoped services are cleaned up even if some fail,
+ * and collects cleanup errors for diagnostics.
+ *
+ * @param scope - RequestScope manager
+ * @returns Array of cleanup errors if any occurred
+ */
+export declare function cleanupRequestScopeOnError(scope?: RequestScopeManager): Promise<Array<{
+    service: string;
+    error: unknown;
+}>>;
+/**
+ * Safe error handler wrapper that manages RequestScope cleanup
+ *
+ * Ensures scoped services are properly cleaned up before returning error response.
+ * Use this to wrap error handlers to make them RequestScope-aware.
+ *
+ * @example
+ * ```typescript
+ * const errorHandler = withRequestScopeCleanup(async (ctx, error) => {
+ *   // Handle error...
+ *   return ctx.json({ error: error.message }, 500)
+ * })
+ *
+ * // In your app:
+ * try {
+ *   // Handle request...
+ * } catch (error) {
+ *   return errorHandler(ctx, error)
+ * }
+ * ```
+ */
+export declare function withRequestScopeCleanup<T extends (ctx: GravitoContext, error: unknown) => Promise<Response>>(handler: T): T;
+/**
+ * Detect potential resource leaks in RequestScope
+ *
+ * Returns diagnostic information about suspicious resource usage patterns
+ */
+export declare function detectRequestScopeLeaks(context: RequestScopeErrorContext): {
+    potentialLeaks: boolean;
+    warnings: string[];
+};