@gravito/ripple 4.0.0 → 4.0.3

package/README.md

@@ -11,16 +11,32 @@
 
 ## Features
 
-- ⚡ **Multi-Runtime Support** - Run on Bun (native WebSocket), Node.js (uWebSockets.js or ws)
-- 🚀 **Simplified API** - Single `start()` method to initialize and run your server
-- 📡 **Channel-based Broadcasting** - Public, Private, and Presence channels
-- 🔒 **Secure Authorization** - Flexible callback-based authorization system
-- 📊 **Production Ready** - 95.24% test coverage, battle-tested architecture
-- 🌐 **Horizontal Scaling** - Redis or NATS driver for multi-server deployments
-- 🔍 **Full Observability** - Built-in logging, health checks, metrics, and connection tracking
-- 💪 **Type-Safe** - Comprehensive TypeScript support with runtime-agnostic types
-- 🎯 **Laravel Echo Compatible** - Familiar API for Laravel developers
-- 🔄 **Backward Compatible** - Seamless upgrade from v4.x
+- ⚡ **Multi-Runtime Support** - Run on Bun (native WebSocket), Node.js (uWebSockets.js or ws).
+- 🚀 **Simplified API** - Single `start()` method to initialize and run your server.
+- 📡 **Real-time Pulse Sync** - Channel-based broadcasting for Public, Private, and Presence channels.
+- 🪐 **Galaxy-Ready Core** - Native integration with PlanetCore for universal WebSocket communication.
+- 🔒 **Secure Authorization** - Flexible callback-based authorization system.
+- 🌐 **Horizontal Scaling** - Redis or NATS driver for multi-server Galaxy deployments.
+- 🔍 **Full Observability** - Built-in logging, health checks, metrics, and connection tracking.
+
+## 🌌 Role in Galaxy Architecture
+
+In the **Gravito Galaxy Architecture**, Ripple acts as the **Gravitational Waves (Real-time Pulse)**.
+
+- **Instant Propagation**: Propagates state changes from the Galaxy's core to external observers (Users) with sub-millisecond latency.
+- **Satellite Interactivity**: Provides the foundation for real-time collaboration features within and between Satellites.
+- **Bi-directional Channel**: Unlike the one-way `Radiance` broadcast, Ripple provides a bi-directional "Pulse" that allows Clients to interact with the Sensing Layer over a persistent connection.
+
+```mermaid
+graph LR
+    Client([Client]) <--> Ripple{Ripple Pulse}
+    Ripple <--> Photon[Photon Engine]
+    subgraph Galaxy
+        Photon <--> S1[Satellite: Chat]
+        Photon <--> S2[Satellite: Dashboard]
+    end
+    Ripple -.-> Plasma[(Plasma: Redis Sync)]
+```
 
 ## Why Ripple?
 

package/dist/{ripple/src/OrbitRipple.d.ts → OrbitRipple.d.ts}

@@ -36,6 +36,7 @@ export declare class OrbitRipple implements GravitoOrbit {
      *
      * - Registers 'ripple' (RippleServer) and 'broadcast' (BroadcastManager) in the container.
      * - Adds middleware to inject 'ripple' and 'broadcast' into GravitoContext.
+     * - Integrates with BunNativeAdapter for same-port WebSocket support.
      * - Initializes the server and registers shutdown hooks.
      *
      * @param core - The PlanetCore instance

package/dist/{ripple/src/RippleServer.d.ts → RippleServer.d.ts}

@@ -80,7 +80,6 @@ export declare class RippleServer {
     private broadcastBinaryToChannel;
     broadcastBinary(channel: string, event: string, data: ArrayBuffer): void;
     private handleClose;
-    private handleDrain;
     private handleSubscribe;
     private handleUnsubscribe;
     private handleWhisper;
@@ -115,6 +114,36 @@ export declare class RippleServer {
      * Get server health status.
      */
     getHealth(): Promise<import(".").HealthCheckResult>;
+    /**
+     * Initialize driver and serializer without starting the engine.
+     *
+     * This method:
+     * 1. Initializes the driver (Redis/NATS/Local)
+     * 2. Initializes the serializer (JSON/Protobuf)
+     * 3. Starts the ping interval
+     *
+     * Used by OrbitRipple for same-port integration with BunNativeAdapter.
+     *
+     * @since 5.0.0
+     */
+    initDriver(): Promise<void>;
+    /**
+     * Start ping interval (internal helper)
+     */
+    private startPingInterval;
+    /**
+     * Get WebSocket handler configuration (Bun only).
+     *
+     * Returns handler object for use with BunNativeAdapter.registerWebSocketRoute().
+     *
+     * @throws Error if engine is not BunEngine
+     */
+    getWebSocketConfig(): {
+        open: (ws: any) => void;
+        message: (ws: any, data: any) => void;
+        close: (ws: any, code: number, reason: string) => void;
+        drain: (_ws: any) => void;
+    };
     /**
      * Initialize and start the RippleServer.
      *
@@ -124,9 +153,10 @@ export declare class RippleServer {
      * 3. Starts the WebSocket engine (Bun/uWS/ws)
      * 4. Starts the ping interval
      *
+     * @param port - Optional port override (defaults to config.port or 3000)
      * @since 5.0.0
      */
-    start(): Promise<void>;
+    start(port?: number): Promise<void>;
     /**
      * Initialize the RippleServer without starting the engine.
      *

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

@@ -5,6 +5,12 @@
  * Provides a centralized entry point for enterprise applications with
  * auto-discovery of providers, config loading, and lifecycle management.
  *
+ * Phase 4 優化：Provider 預掃描 + 平行載入
+ * - Phase 1：預掃描所有 Provider 文件（語法驗證）
+ * - Phase 2：篩選有效 Provider（跳過無效的）
+ * - Phase 3：平行 import 所有有效 Provider
+ * - Phase 4：註冊到容器
+ *
  * @module @gravito/core
  * @since 2.0.0
  */
@@ -141,9 +147,44 @@ export declare class Application {
     /**
      * Discover and register providers from the providers directory.
      *
+     * Phase 4 優化版本：採用 4-Phase 載入策略
+     * - Phase 1：預掃描所有候選 Provider 檔案（語法驗證）
+     * - Phase 2：篩選有效 Provider 檔案（跳過語法錯誤的）
+     * - Phase 3：平行 import 所有有效 Provider（從循序 → 並行）
+     * - Phase 4：逐一註冊到容器
+     *
+     * 效能改進：N 個 Provider 從 O(N * importTime) 降至 O(importTime + overhead)
+     *
      * @internal
      */
     private discoverProviders;
+    /**
+     * Phase 1+2：預掃描 Provider 目錄中的所有候選檔案。
+     *
+     * 使用輕量語法驗證（嘗試讀取 + 基本結構檢查）篩選有效的 Provider 檔案，
+     * 讓語法錯誤在 import 之前被發現，提供更清晰的錯誤訊息。
+     *
+     * 策略：
+     * 1. 使用 Bun.Transpiler 進行 import 掃描（在 Bun 環境下）
+     * 2. Fallback 至基本檔案讀取驗證（在 Node/Deno 環境下）
+     *
+     * @param providersPath - Provider 目錄絕對路徑
+     * @returns 掃描結果陣列（含有效/無效標記）
+     * @internal
+     */
+    private prescribeProviders;
+    /**
+     * Phase 3：平行 import 所有有效的 Provider 檔案。
+     *
+     * 使用 Promise.all() 同時 import 所有通過預掃描的 Provider 檔案，
+     * 從循序載入（O(N)）改善為平行載入（O(1) 理論上），
+     * 實際效能受 I/O、CPU 和 V8 模組解析限制。
+     *
+     * @param validProviders - 通過預掃描的 Provider 掃描結果
+     * @returns 模組載入結果陣列
+     * @internal
+     */
+    private loadProvidersInParallel;
     /**
      * Resolve a service instance from the IoC container.
      *

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>;
     /**