@gravito/ripple 4.0.1 → 5.0.0

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}

@@ -114,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.
      *
@@ -123,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/HookManager.d.ts

@@ -1,141 +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;
-    /**
-     * 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;
-    private actions;
+    private filterManager;
+    private actionManager;
+    private asyncDetector;
+    private migrationWarner;
     private eventQueue;
     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
-     */
-    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.
@@ -150,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;
@@ -168,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>;
@@ -186,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;
@@ -200,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.
@@ -207,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>;
@@ -217,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.
@@ -241,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.
      *
@@ -265,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
@@ -314,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.
      *
@@ -330,7 +184,6 @@ export declare class HookManager {
      * @public
      */
     getListenerInfo(hook: string): ListenerInfo[];
-    private shouldUseAsyncDispatch;
     /**
      * Get the current event queue depth.
      *
@@ -356,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.
      *
@@ -466,12 +324,6 @@ export declare class HookManager {
      * @returns Backpressure metrics snapshot or undefined if not enabled
      */
     getBackpressureMetrics(): object | undefined;
-    /**
-     * Remove all listeners for a specific action hook.
-     *
-     * @param hook - Hook name
-     */
-    removeAction(hook: string): void;
     /**
      * Get the persistent DLQ manager instance.
      *
@@ -511,7 +363,7 @@ export declare class HookManager {
         failed: number;
     }>;
     /**
-     * Dispatch an event through Bull Queue (分佈式異步處理).
+     * Dispatch an event through Bull Queue（分佈式異步處理）.
      *
      * 與 doActionAsync() 不同：
      * - doActionAsync() 使用 EventPriorityQueue (Memory-based)
@@ -538,9 +390,7 @@ export declare class HookManager {
      */
     dispatchQueued<TArgs = unknown>(event: string, args: TArgs, options?: any): Promise<string>;
     /**
-     * Dispatch an event through Bull Queue with delay (延遲隊列分發).
-     *
-     * 通過 Bull Queue 的 delayed jobs 功能實現延遲處理。
+     * Dispatch an event through Bull Queue with delay（延遲隊列分發）.
      *
      * @template TArgs - 事件參數類型
      * @param event - 事件名稱
@@ -572,12 +422,6 @@ export declare class HookManager {
      * @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>;

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;
@@ -123,6 +131,12 @@ export type GravitoConfig = {
             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';
@@ -160,14 +174,28 @@ 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;
+    /**
+     * Global shutdown timeout in milliseconds (D-10).
+     * If the entire shutdown sequence does not complete within this limit,
+     * a warning is logged and shutdown is force-completed so the process can exit.
+     */
+    private static readonly GLOBAL_SHUTDOWN_TIMEOUT;
     /**
      * 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;
@@ -175,6 +203,7 @@ export declare class PlanetCore {
      * Initialize Prometheus metrics asynchronously.
      *
      * @internal
+     * @deprecated Prometheus setup has been moved to @gravito/monitor
      */
     private initializePrometheusAsync;
     /**
@@ -262,6 +291,7 @@ export declare class PlanetCore {
         config?: Record<string, unknown>;
         adapter?: HttpAdapter;
         container?: Container;
+        observabilityProvider?: ObservabilityProvider;
     });
     /**
      * Setup process signal handlers for graceful shutdown