@gravito/ripple 4.0.0 → 4.0.3

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
@@ -21,6 +22,10 @@ declare class MinimalRequest implements FastRequest {
     private readonly _path;
     private readonly _routePattern?;
     private _searchParams;
+    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;
@@ -39,6 +44,7 @@ declare class MinimalRequest implements FastRequest {
     json<T = unknown>(): Promise<T>;
     text(): Promise<string>;
     formData(): Promise<FormData>;
+    get cookies(): Record<string, string>;
     get raw(): Request;
 }
 /**
@@ -53,6 +59,7 @@ declare class MinimalRequest implements FastRequest {
 export declare class MinimalContext implements IFastContext {
     readonly req: MinimalRequest;
     private _resHeaders;
+    private _requestScope;
     constructor(request: Request, params: Record<string, string>, path: string, routePattern?: string);
     private getHeaders;
     json<T>(data: T, status?: number): Response;
@@ -69,8 +76,24 @@ export declare class MinimalContext implements IFastContext {
     unauthorized(message?: string): Response;
     badRequest(message?: string): Response;
     forward(target: string, _options?: any): Promise<Response>;
+    escape(html: string): string;
     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/analyzer.d.ts

@@ -1,27 +1,113 @@
 /**
- * Handler Static Analyzer (Elysia-inspired)
+ * @fileoverview Handler 靜態分析器（Elysia-inspired，升級版）
  *
- * Analyzes handler functions to determine what request properties
- * they access, allowing for optimized code paths.
+ * 分析 handler 函式，偵測其存取了哪些請求屬性，
+ * 以選擇最優化的 Context 類型（minimal/fast/full）。
+ *
+ * ## 版本歷史
+ *
+ * ### v2（目前版本）- 使用 Bun.Transpiler
+ * - 精確度：~99%（AST 層級分析）
+ * - 正確處理假陽性：`const header = '...'` 不再誤判
+ * - 支援解構賦值：`const { header } = ctx.req`
+ * - 支援 Minified 代碼（transformSync 先標準化）
+ * - Fallback：若 Transpiler 失敗，退回字串匹配
+ *
+ * ### v1（原版本）- 字串匹配
+ * - 精確度：~85%
+ * - 假陽性：變數名稱包含目標字串會誤判
+ * - 假陰性：解構賦值無法偵測
+ * - Minified 代碼可能失效
+ *
+ * @module @gravito/core/engine/analyzer
+ * @since 3.0.0
  */
 /**
- * Represents the results of a static analysis performed on a handler function.
+ * Handler 靜態分析結果
+ *
+ * 記錄 handler 函式使用了哪些請求屬性，
+ * 用於選擇最優化的 Context 類型。
  *
  * @public
  * @since 3.0.0
  */
 export interface HandlerAnalysis {
+    /** 是否存取了 request headers */
     usesHeaders: boolean;
+    /** 是否存取了 query string 參數 */
     usesQuery: boolean;
+    /** 是否存取了 request body */
     usesBody: boolean;
+    /** 是否存取了 route 路徑參數 */
     usesParams: boolean;
+    /** 是否為非同步函式（含 async/await） */
     isAsync: boolean;
 }
 /**
- * Analyze a handler function to detect what it accesses
+ * 分析 handler 函式，偵測其使用了哪些請求屬性
+ *
+ * 使用 Bun.Transpiler 進行 AST 層級的精確分析（精確度 ~99%）。
+ * 若 Transpiler 不可用，自動 fallback 到字串匹配（精確度 ~85%）。
+ *
+ * ## 精確度提升說明
+ *
+ * **假陽性修復**（原本誤判，現在正確）：
+ * ```typescript
+ * // 這個 handler 原本會誤判 usesHeaders = true
+ * // 因為字串 'header' 出現在變數名稱中
+ * function handler(ctx) {
+ *   const header = 'Content-Type'  // ← 變數名稱，不是 API 呼叫
+ *   return ctx.json({ header })
+ * }
+ * // 現在：usesHeaders = false ✅
+ * ```
+ *
+ * **假陰性修復**（原本漏偵測，現在正確）：
+ * ```typescript
+ * // 這個 handler 原本會漏偵測解構賦值
+ * function handler(ctx) {
+ *   const { header, query } = ctx.req  // ← 解構賦值
+ *   return ctx.json({ header })
+ * }
+ * // 現在：usesHeaders = true, usesQuery = true ✅
+ * ```
+ *
+ * @param handler - 要分析的 handler 函式
+ * @returns HandlerAnalysis 分析結果
+ *
+ * @example
+ * ```typescript
+ * const handler = async (ctx) => {
+ *   const name = ctx.req.query('name')
+ *   return ctx.json({ name })
+ * }
+ *
+ * const analysis = analyzeHandler(handler)
+ * // analysis.usesQuery === true
+ * // analysis.usesHeaders === false
+ * // analysis.isAsync === true
+ *
+ * const type = getOptimalContextType(analysis)
+ * // type === 'fast'
+ * ```
  */
 export declare function analyzeHandler(handler: Function): HandlerAnalysis;
 /**
- * Determine optimal context type based on analysis
+ * 根據分析結果決定最優化的 Context 類型
+ *
+ * Context 類型由輕到重：
+ * - `minimal`：僅支援路徑參數與靜態回應，零 overhead
+ * - `fast`：支援 headers 與 query，使用物件池
+ * - `full`：支援完整功能含 body 解析（async）
+ *
+ * 選擇邏輯（優先順序）：
+ * 1. 若存取 headers → `fast`（header 設置需要完整支援）
+ * 2. 若不存取任何屬性 → `minimal`
+ * 3. 若僅存取 params → `minimal`（params 在 minimal 中也可用）
+ * 4. 若存取 body → `full`（async body 解析需要完整 context）
+ * 5. 其他 → `fast`
+ *
+ * @param analysis - HandlerAnalysis 分析結果
+ * @returns 最優化的 context 類型
  */
 export declare function getOptimalContextType(analysis: HandlerAnalysis): 'minimal' | 'fast' | 'full';

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

@@ -25,6 +25,7 @@ export interface FastContext {
     unauthorized(message?: string): Response;
     badRequest(message?: string): Response;
     forward(target: string, options?: any): Promise<Response>;
+    escape(html: string): string;
     /** Header management */
     header(name: string): string | undefined;
     header(name: string, value: string): void;
@@ -32,6 +33,9 @@ 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;
@@ -67,6 +71,8 @@ export interface FastRequest {
     header(name: string): string | undefined;
     /** Get all headers */
     headers(): Record<string, string>;
+    /** Get all cookies (Native Bun 1.39+ / Lazy Parsed) */
+    readonly cookies: Record<string, string>;
     /** Parse JSON body */
     json<T = unknown>(): Promise<T>;
     /** Parse text body */

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[];
+};

package/dist/core/src/events/BackpressureManager.d.ts

@@ -0,0 +1,215 @@
+/**
+ * @gravito/core - Event System Backpressure Management
+ *
+ * Implements a backpressure management system to prevent high-priority events
+ * from starving low-priority events when the queue is under resource constraints.
+ *
+ * 背壓管理器：在資源受限時進行智慧型流量控制，防止優先級飢餓。
+ *
+ * FS-103 增強：
+ * - 多優先級隊列深度監控
+ * - 背壓反饋迴路支持
+ * - 智能 DLQ 路由決策
+ */
+import type { DeadLetterDecision, MultiPriorityQueueDepth } from './types';
+/**
+ * 背壓狀態枚舉。
+ *
+ * 狀態轉換：Normal → Warning → Critical → Overflow
+ * 恢復方向：遲滯設計（需降至觸發閾值的 80%）
+ *
+ * @public
+ */
+export declare enum BackpressureState {
+    /** 正常運作，無背壓 */
+    NORMAL = "NORMAL",
+    /** 警告狀態，開始限制低優先級事件 */
+    WARNING = "WARNING",
+    /** 危急狀態，僅允許高優先級事件 */
+    CRITICAL = "CRITICAL",
+    /** 溢位狀態，全部拒絕 */
+    OVERFLOW = "OVERFLOW"
+}
+/**
+ * 背壓配置選項。
+ *
+ * @public
+ */
+export interface BackpressureConfig {
+    /** 是否啟用背壓管理器（預設 true） */
+    enabled?: boolean;
+    /** 總隊列深度限制（預設無限） */
+    maxQueueSize?: number;
+    /** 分優先級隊列深度限制 */
+    maxSizeByPriority?: {
+        critical?: number;
+        high?: number;
+        normal?: number;
+        low?: number;
+    };
+    /** 每秒最大入隊速率（events/sec，預設無限） */
+    maxEnqueueRate?: number;
+    /** 速率限制滑動視窗大小（ms，預設 1000） */
+    rateLimitWindowMs?: number;
+    /** 背壓狀態閾值（佔 maxQueueSize 的百分比） */
+    thresholds?: {
+        /** WARNING 觸發百分比（預設 0.6 = 60%） */
+        warning?: number;
+        /** CRITICAL 觸發百分比（預設 0.85 = 85%） */
+        critical?: number;
+        /** OVERFLOW 觸發百分比（預設 1.0 = 100%） */
+        overflow?: number;
+    };
+    /** 被拒絕事件的處理策略（預設 'drop-with-callback'） */
+    rejectionPolicy?: 'throw' | 'drop-silent' | 'drop-with-callback';
+    /** 當 rejectionPolicy 為 'drop-with-callback' 時的回呼 */
+    onRejected?: (eventName: string, priority: string, reason: string) => void;
+    /** 背壓狀態變更回呼 */
+    onStateChange?: (from: BackpressureState, to: BackpressureState) => void;
+    /** 低優先級事件在 WARNING 狀態下的延遲入隊時間（ms，預設 100） */
+    lowPriorityDelayMs?: number;
+    /** 是否啟用優先級反轉防護（預設 true） */
+    enableStarvationProtection?: boolean;
+    /** 低優先級事件最大等待時間，超過則提升優先級（ms，預設 5000） */
+    starvationTimeoutMs?: number;
+    /** 當進入 OVERFLOW 狀態時，是否將被拒絕事件路由到 DLQ（預設 false） */
+    dlqOnOverflow?: boolean;
+    /** OVERFLOW 時的重試策略（預設 'dlq-only'） */
+    overflowRetryStrategy?: 'immediate' | 'delayed' | 'dlq-only';
+    /** OVERFLOW 延遲重試的基礎延遲時間（ms，預設 5000） */
+    overflowRetryDelayMs?: number;
+}
+/**
+ * 背壓決策結果。
+ *
+ * @public
+ */
+export interface BackpressureDecision {
+    /** 是否允許入隊 */
+    allowed: boolean;
+    /** 拒絕原因（若不允許） */
+    reason?: string;
+    /** 是否需要延遲入隊 */
+    delayed?: boolean;
+    /** 延遲時間（ms） */
+    delayMs?: number;
+    /** 建議降級後的優先級（若降級） */
+    degradedPriority?: 'high' | 'normal' | 'low';
+    /** 是否是由於 OVERFLOW 狀態被拒絕 */
+    isOverflow?: boolean;
+    /** OVERFLOW 時的重試策略建議（'immediate'、'delayed'、'dlq-only'） */
+    retryStrategy?: 'immediate' | 'delayed' | 'dlq-only';
+}
+/**
+ * 背壓指標快照。
+ *
+ * @public
+ */
+export interface BackpressureMetricsSnapshot {
+    state: BackpressureState;
+    totalDepth: number;
+    depthByPriority: {
+        critical: number;
+        high: number;
+        normal: number;
+        low: number;
+    };
+    enqueueRate: number;
+    rejectedCount: number;
+    degradedCount: number;
+    stateTransitions: number;
+    dlqRouteCount?: number;
+    windowAdjustmentCount?: number;
+}
+/**
+ * 背壓管理器。
+ *
+ * 根據隊列深度、速率、優先級等因素，決定是否允許新事件入隊，
+ * 以及是否需要降級優先級或延遲入隊。
+ *
+ * @public
+ */
+export declare class BackpressureManager {
+    private enabled;
+    private config;
+    private onRejected?;
+    private onStateChange?;
+    private state;
+    private rejectedCount;
+    private degradedCount;
+    private stateTransitions;
+    private rateCounter;
+    private depthByPriority;
+    private windowAdjustmentHistory;
+    private dlqRouteCount;
+    constructor(config?: BackpressureConfig);
+    /**
+     * 評估是否允許新事件入隊。
+     *
+     * @param eventName 事件名稱
+     * @param priority 事件優先級
+     * @param queueDepth 當前隊列深度
+     * @param depthByPriority 分優先級隊列深度
+     * @returns 背壓決策結果
+     */
+    evaluate(eventName: string, priority: 'critical' | 'high' | 'normal' | 'low', queueDepth: number, depthByPriority: {
+        critical: number;
+        high: number;
+        normal: number;
+        low: number;
+    }): BackpressureDecision;
+    /**
+     * 獲取當前背壓狀態。
+     */
+    getState(): BackpressureState;
+    /**
+     * 獲取背壓指標快照。
+     */
+    getMetrics(): BackpressureMetricsSnapshot;
+    /**
+     * 重置背壓管理器狀態。
+     */
+    reset(): void;
+    /**
+     * 同步隊列深度（由 EventPriorityQueue 調用）。
+     * FS-103：多優先級隊列深度監控
+     */
+    updateQueueDepth(depths: MultiPriorityQueueDepth): void;
+    /**
+     * 獲取各優先級的隊列深度。
+     * FS-103：提供實時隊列深度快照
+     */
+    getQueueDepthByPriority(): MultiPriorityQueueDepth;
+    /**
+     * 獲取總隊列深度。
+     */
+    getTotalQueueDepth(): number;
+    /**
+     * 接收來自 AggregationWindow 的窗口調整通知。
+     * FS-103：背壓反饋迴路
+     */
+    notifyWindowAdjustment(oldWindowMs: number, newWindowMs: number): void;
+    /**
+     * 檢查是否可以從 CRITICAL 或更高級別降級。
+     * FS-103：自動狀態恢復機制
+     */
+    private checkStateRecovery;
+    /**
+     * 決定是否應該將事件路由到死信隊列。
+     * FS-103：智能 DLQ 路由決策
+     */
+    makeDeadLetterDecision(_eventName: string, priority: 'critical' | 'high' | 'normal' | 'low'): DeadLetterDecision;
+    /**
+     * 更新背壓狀態。
+     * 使用遲滯設計（80% 回復比例）避免邊界震盪。
+     */
+    private updateState;
+    /**
+     * 執行狀態轉換。
+     */
+    private transitionTo;
+    /**
+     * 建立決策結果並記錄拒絕。
+     */
+    private createDecision;
+}

package/dist/core/src/events/DeadLetterQueue.d.ts

@@ -1,4 +1,9 @@
 import type { EventOptions } from './EventOptions';
+/**
+ * Source of DLQ entry - reason why event entered the DLQ.
+ * @public
+ */
+export type DLQEntrySource = 'retry_exhausted' | 'circuit_breaker' | 'backpressure_overflow' | 'manual';
 /**
  * Dead Letter Queue entry representing a failed event.
  * @public
@@ -44,6 +49,10 @@ export interface DLQEntry {
      * Timestamp when the event was last retried (if any).
      */
     lastRetriedAt?: number;
+    /**
+     * Source of the DLQ entry - reason why event entered the DLQ.
+     */
+    source: DLQEntrySource;
 }
 /**
  * Filter options for querying DLQ entries.
@@ -67,6 +76,11 @@ export interface DLQFilter {
      */
     limit?: number;
 }
+/**
+ * Callback type for DLQ entry events.
+ * @public
+ */
+export type DLQEntryCallback = (entry: DLQEntry) => void;
 /**
  * Dead Letter Queue Manager for handling failed events.
  *
@@ -78,6 +92,15 @@ export interface DLQFilter {
 export declare class DeadLetterQueue {
     private entries;
     private entryIdCounter;
+    private maxEntries?;
+    private onEntryAdded?;
+    private onEntryRemoved?;
+    /**
+     * Create a new DeadLetterQueue instance.
+     *
+     * @param maxEntries - Maximum number of entries to keep (optional, no limit if not set)
+     */
+    constructor(maxEntries?: number);
     /**
      * Add a failed event to the Dead Letter Queue.
      *
@@ -87,9 +110,10 @@ export declare class DeadLetterQueue {
      * @param error - Error that caused the failure
      * @param retryCount - Number of retry attempts made
      * @param firstFailedAt - Timestamp of first failure
+     * @param source - Source of the DLQ entry (default: 'retry_exhausted')
      * @returns DLQ entry ID
      */
-    add(eventName: string, payload: unknown, options: EventOptions, error: Error, retryCount: number, firstFailedAt: number): string;
+    add(eventName: string, payload: unknown, options: EventOptions, error: Error, retryCount: number, firstFailedAt: number, source?: DLQEntrySource): string;
     /**
      * Get a specific DLQ entry by ID.
      *
@@ -142,4 +166,54 @@ export declare class DeadLetterQueue {
      * @internal
      */
     updateLastRetried(entryId: string): void;
+    /**
+     * Evict the oldest entry from the DLQ.
+     * Used when capacity limit is reached.
+     *
+     * @private
+     */
+    private evictOldest;
+    /**
+     * Get the oldest entry in the DLQ.
+     *
+     * @returns Oldest DLQ entry or undefined if empty
+     */
+    getOldestEntry(): DLQEntry | undefined;
+    /**
+     * Get the newest entry in the DLQ.
+     *
+     * @returns Newest DLQ entry or undefined if empty
+     */
+    getNewestEntry(): DLQEntry | undefined;
+    /**
+     * Get all entries grouped by source.
+     *
+     * @param source - Source to filter by
+     * @returns Array of entries matching the source
+     */
+    getEntriesBySource(source: DLQEntrySource): DLQEntry[];
+    /**
+     * Set callback for when an entry is added to the DLQ.
+     *
+     * @param callback - Callback function or undefined to clear
+     */
+    setOnEntryAdded(callback?: DLQEntryCallback): void;
+    /**
+     * Set callback for when an entry is removed from the DLQ.
+     *
+     * @param callback - Callback function or undefined to clear
+     */
+    setOnEntryRemoved(callback?: DLQEntryCallback): void;
+    /**
+     * Get the maximum number of entries allowed in the DLQ.
+     *
+     * @returns Max entries limit or undefined if no limit
+     */
+    getMaxEntries(): number | undefined;
+    /**
+     * Set the maximum number of entries allowed in the DLQ.
+     *
+     * @param maxEntries - Maximum entries or undefined to remove limit
+     */
+    setMaxEntries(maxEntries?: number): void;
 }

package/dist/core/src/events/EventBackend.d.ts

@@ -6,6 +6,7 @@ export interface EventBackend {
     /**
      * Enqueue an event for processing.
      * @param task - The event task to process
+     * @returns Task ID or 'dropped' if event was rejected (can be async for some backends)
      */
-    enqueue(task: EventTask): Promise<void> | void;
+    enqueue(task: EventTask): string | Promise<void>;
 }