@gravito/ripple 3.1.0 → 4.0.1

package/dist/ripple/src/RippleServer.d.ts

@@ -5,35 +5,20 @@
  *
  * @module @gravito/ripple
  */
-import type { Server } from 'bun';
-import type { ClientData, RippleConfig, RippleWebSocket, WebSocketHandlerConfig } from './types';
+import type { RippleSocket } from './engines/IRippleEngine';
+import type { RippleConfig, RippleInterceptor, WebSocketHandlerConfig } from './types';
 /**
  * Ripple WebSocket Server
  *
- * Provides channel-based real-time communication using Bun's native WebSocket.
+ * Provides channel-based real-time communication with multi-runtime support.
+ * Can run on Bun (native WebSocket), Node.js (uWebSockets.js or ws).
  *
- * @example
- * ```typescript
- * const ripple = new RippleServer({
- *   path: '/ws',
- *   authorizer: async (channel, userId) => {
- *     // Custom authorization logic
- *     return true
- *   }
- * })
- *
- * Bun.serve({
- *   fetch: (req, server) => {
- *     if (ripple.upgrade(req, server)) return
- *     return new Response('Not found', { status: 404 })
- *   },
- *   websocket: ripple.getHandler()
- * })
- * ```
+ * @since 5.0.0 - Multi-runtime support via engine abstraction
  */
 export declare class RippleServer {
     private channels;
     private driver;
+    private engine;
     private authorizer?;
     private pingInterval?;
     private eventListeners;
@@ -41,291 +26,77 @@ export declare class RippleServer {
     private tracker;
     private healthChecker;
     private serializer;
+    private whisperLimiters;
+    private sessionManager?;
+    private ackManager;
+    private rippleMetrics?;
+    private interceptors;
+    private clientSockets;
     readonly config: Required<Pick<RippleConfig, 'path' | 'authEndpoint' | 'pingInterval'>> & RippleConfig;
     constructor(config?: RippleConfig);
     /**
-     * Register an event listener for custom client events.
-     *
-     * Allows server-side code to react to custom events sent by WebSocket clients.
-     * This is useful for handling client-initiated actions like typing indicators,
-     * presence updates, or custom application logic.
-     *
-     * @param event - The event name to listen for (e.g., 'typing', 'user.online')
-     * @param handler - Callback function invoked when the event is received
-     * @param handler.socket - The WebSocket connection that sent the event
-     * @param handler.data - The event payload sent by the client
-     *
-     * @example
-     * ```typescript
-     * // Listen for typing indicators
-     * ripple.on('typing', (socket, data) => {
-     *   console.log(`User ${socket.data.userId} is typing in ${data.channel}`)
-     *   // Broadcast typing indicator to other users
-     *   ripple.to(data.channel).emit('user-typing', {
-     *     userId: socket.data.userId
-     *   })
-     * })
-     *
-     * // Listen for custom game moves
-     * ripple.on('game.move', async (socket, data) => {
-     *   await saveGameMove(data.gameId, data.move)
-     *   ripple.to(`game.${data.gameId}`).emit('move-made', data)
-     * })
-     * ```
+     * Create the appropriate WebSocket engine based on configuration.
      */
-    on(event: string, handler: (socket: RippleWebSocket, data: any) => void): void;
+    private createEngine;
     /**
-     * Fluent API for broadcasting to a channel.
-     *
-     * Provides a chainable interface for emitting events to specific channels.
-     * This is a convenience method that returns an object with an `emit()` function.
-     *
-     * @param channel - The channel name (e.g., 'news', 'private-orders.123', 'presence-chat.lobby')
-     * @returns An object with an `emit` method for sending events
-     *
-     * @example
-     * ```typescript
-     * // Broadcast to a public channel
-     * ripple.to('news').emit('article.published', {
-     *   id: 123,
-     *   title: 'Breaking News',
-     *   author: 'John Doe'
-     * })
-     *
-     * // Broadcast to a private channel
-     * ripple.to('private-orders.456').emit('order.shipped', {
-     *   orderId: 456,
-     *   trackingNumber: 'ABC123'
-     * })
-     *
-     * // Broadcast to a presence channel
-     * ripple.to('presence-chat.room1').emit('message', {
-     *   userId: 'user-789',
-     *   text: 'Hello everyone!'
-     * })
-     * ```
+     * Auto-detect the current JavaScript runtime.
      */
+    private detectRuntime;
+    /**
+     * Setup engine event handlers.
+     */
+    private setupEngineHandlers;
+    private emit;
+    on(event: string, handler: (socket: RippleSocket, data: any) => void): void;
+    /**
+     * Get the name of the active message driver.
+     */
+    get driverName(): string;
     to(channel: string): {
-        emit: (event: string, data: unknown) => void;
+        emit: (event: string, data: unknown, options?: {
+            needAck?: boolean;
+            timeout?: number;
+        }) => void;
     };
     /**
-     * Attempt to upgrade an HTTP request to WebSocket.
-     *
-     * This method should be called in your Bun.serve fetch handler to check if an incoming
-     * HTTP request should be upgraded to a WebSocket connection. It validates the request path
-     * against the configured WebSocket endpoint and performs the upgrade if matched.
-     *
-     * **Important**: For private/presence channels, you must pass the authenticated `userId`
-     * in the options parameter. This userId will be used for channel authorization.
-     *
-     * @param req - The incoming HTTP request from Bun.serve
-     * @param server - The Bun server instance
-     * @param options - Optional upgrade options
-     * @param options.userId - The authenticated user ID (required for private/presence channels)
-     * @returns `true` if the request was upgraded to WebSocket, `false` otherwise
-     *
-     * @example
-     * ```typescript
-     * // Basic setup (public channels only)
-     * Bun.serve({
-     *   fetch: (req, server) => {
-     *     if (ripple.upgrade(req, server)) return
-     *     return new Response('Not found', { status: 404 })
-     *   },
-     *   websocket: ripple.getHandler()
-     * })
-     *
-     * // With authentication (supports private/presence channels)
-     * Bun.serve({
-     *   fetch: async (req, server) => {
-     *     // Extract userId from JWT, session, or other auth mechanism
-     *     const userId = await extractUserIdFromRequest(req)
-     *
-     *     // Pass userId to enable private/presence channel authorization
-     *     if (ripple.upgrade(req, server, { userId })) return
-     *
-     *     // Handle other HTTP routes
-     *     return app.fetch(req, server)
-     *   },
-     *   websocket: ripple.getHandler()
-     * })
+     * Upgrade an HTTP request to WebSocket (Bun/uWS only).
      *
-     * // Integration with Sentinel auth
-     * Bun.serve({
-     *   fetch: async (req, server) => {
-     *     const user = await sentinel.getUserFromRequest(req)
-     *     if (ripple.upgrade(req, server, { userId: user?.id })) return
-     *     return handleHttpRequest(req)
-     *   },
-     *   websocket: ripple.getHandler()
-     * })
-     * ```
+     * @deprecated Use engine-based initialization via init() instead.
+     * This method is kept for backward compatibility with v4.x.
      */
-    upgrade(req: Request, server: Server<ClientData>, options?: {
+    upgrade(req: Request, options?: {
         userId?: string;
     }): boolean;
     /**
-     * Get WebSocket handler configuration for Bun.serve.
+     * Get WebSocket handler configuration (Bun only).
      *
-     * Returns an object containing all WebSocket event handlers (open, message, close, drain)
-     * that Bun requires for WebSocket server configuration. This should be passed to the
-     * `websocket` property of `Bun.serve()`.
-     *
-     * @returns WebSocket handler configuration object with event handlers
-     *
-     * @example
-     * ```typescript
-     * const ripple = new RippleServer({ path: '/ws' })
-     *
-     * Bun.serve({
-     *   port: 3000,
-     *   fetch: (req, server) => {
-     *     if (ripple.upgrade(req, server)) return
-     *     return new Response('Not found', { status: 404 })
-     *   },
-     *   // Pass the handler configuration to Bun.serve
-     *   websocket: ripple.getHandler()
-     * })
-     * ```
-     *
-     * @see {@link https://bun.sh/docs/api/websockets Bun WebSocket API}
+     * @deprecated Use engine-based initialization via init() instead.
+     * This method is kept for backward compatibility with v4.x.
      */
     getHandler(): WebSocketHandlerConfig;
     private handleOpen;
     private handleMessage;
+    private handleBinaryMessage;
+    private broadcastBinaryToChannel;
+    broadcastBinary(channel: string, event: string, data: ArrayBuffer): void;
     private handleClose;
-    private handleDrain;
     private handleSubscribe;
     private handleUnsubscribe;
     private handleWhisper;
-    /**
-     * Broadcast an event to all subscribers of a channel.
-     *
-     * Sends an event with data to all WebSocket clients currently subscribed to the specified channel.
-     * This method is the primary way to push server-side events to connected clients.
-     *
-     * **Note**: Use the fluent `to()` API for more readable code: `ripple.to(channel).emit(event, data)`
-     *
-     * @param channel - The full channel name (e.g., 'news', 'private-orders.123', 'presence-chat.lobby')
-     * @param event - The event name that clients will listen for
-     * @param data - The event payload (must be JSON-serializable)
-     *
-     * @example
-     * ```typescript
-     * // Broadcast to a public channel
-     * ripple.broadcast('news', 'article.published', {
-     *   id: 123,
-     *   title: 'Breaking News',
-     *   publishedAt: new Date().toISOString()
-     * })
-     *
-     * // Broadcast order update to a private channel
-     * ripple.broadcast('private-orders.456', 'order.status.updated', {
-     *   orderId: 456,
-     *   status: 'shipped',
-     *   trackingNumber: 'ABC123XYZ'
-     * })
-     *
-     * // Broadcast to presence channel
-     * ripple.broadcast('presence-chat.room1', 'message', {
-     *   userId: 'user-789',
-     *   text: 'Hello everyone!',
-     *   timestamp: Date.now()
-     * })
-     * ```
-     *
-     * @see {@link to} - Fluent API alternative for broadcasting
-     */
-    broadcast(channel: string, event: string, data: unknown): void;
-    /**
-     * Broadcast an event to specific client IDs.
-     *
-     * Sends an event directly to an array of client IDs, regardless of their channel subscriptions.
-     * This is useful for targeted notifications or private messages to specific users.
-     *
-     * **Note**: The event is sent without a channel context. Clients receive it as a direct message.
-     *
-     * @param clientIds - Array of client socket IDs (from `ws.data.id`)
-     * @param event - The event name that clients will listen for
-     * @param data - The event payload (must be JSON-serializable)
-     *
-     * @example
-     * ```typescript
-     * // Send notification to specific clients
-     * const clientIds = ['client-uuid-1', 'client-uuid-2', 'client-uuid-3']
-     * ripple.broadcastToClients(clientIds, 'notification', {
-     *   type: 'alert',
-     *   message: 'Your order has been confirmed',
-     *   timestamp: Date.now()
-     * })
-     *
-     * // Send direct message to a single client
-     * const recipientId = 'client-uuid-xyz'
-     * ripple.broadcastToClients([recipientId], 'private.message', {
-     *   from: 'admin',
-     *   text: 'Welcome to our platform!',
-     *   priority: 'high'
-     * })
-     *
-     * // Notify users from a query result
-     * const onlineUsers = await db.query('SELECT socket_id FROM online_users WHERE premium = true')
-     * const clientIds = onlineUsers.map(u => u.socket_id)
-     * ripple.broadcastToClients(clientIds, 'premium.announcement', {
-     *   title: 'Exclusive Offer',
-     *   discount: 20
-     * })
-     * ```
-     *
-     * @see {@link broadcast} - For broadcasting to channels
-     */
+    broadcast(channel: string, event: string, data: unknown, options?: {
+        needAck?: boolean;
+        timeout?: number;
+    }): void;
     broadcastToClients(clientIds: string[], event: string, data: unknown): void;
     private broadcastToChannel;
     private sendRaw;
     private send;
+    /**
+     * Add a middleware interceptor (v4.0+).
+     */
+    use(interceptor: RippleInterceptor): this;
     /**
      * Get real-time server statistics.
-     *
-     * Returns current metrics about active connections and channel subscriptions.
-     * Useful for monitoring, debugging, and building admin dashboards.
-     *
-     * @returns Server statistics object
-     * @returns stats.totalConnections - Number of active WebSocket connections
-     * @returns stats.totalChannels - Number of channels with at least one subscriber
-     * @returns stats.channelSubscriptions - Map of channel names to subscriber counts
-     *
-     * @example
-     * ```typescript
-     * // Get current stats
-     * const stats = ripple.getStats()
-     * console.log(`Active connections: ${stats.totalConnections}`)
-     * console.log(`Active channels: ${stats.totalChannels}`)
-     *
-     * // Log channel-specific stats
-     * for (const [channel, count] of Object.entries(stats.channelSubscriptions)) {
-     *   console.log(`${channel}: ${count} subscribers`)
-     * }
-     *
-     * // Build monitoring endpoint
-     * app.get('/admin/websocket-stats', (req, res) => {
-     *   const stats = ripple.getStats()
-     *   return res.json({
-     *     connections: stats.totalConnections,
-     *     channels: stats.totalChannels,
-     *     topChannels: Object.entries(stats.channelSubscriptions)
-     *       .sort(([, a], [, b]) => b - a)
-     *       .slice(0, 10)
-     *       .map(([name, count]) => ({ name, subscribers: count }))
-     *   })
-     * })
-     *
-     * // Periodic logging
-     * setInterval(() => {
-     *   const stats = ripple.getStats()
-     *   logger.info('WebSocket metrics', stats)
-     * }, 60000) // Every minute
-     * ```
-     *
-     * @see {@link getHealth} - For health check information
      */
     getStats(): {
         totalClients: number;
@@ -335,184 +106,32 @@ export declare class RippleServer {
             subscribers: number;
         }[];
     };
+    /**
+     * Get Prometheus metrics (v3.7+).
+     */
+    getMetrics(): string;
     /**
      * Get server health status.
-     *
-     * Performs a comprehensive health check of the WebSocket server and its dependencies.
-     * Checks include driver connectivity (Redis/Local), server responsiveness, and error metrics.
-     *
-     * **Use case**: Health check endpoints for load balancers, monitoring systems, and orchestration platforms.
-     *
-     * @returns Promise resolving to health check result
-     * @returns result.healthy - Overall health status (true if all checks pass)
-     * @returns result.checks - Detailed status of individual health checks
-     *
-     * @example
-     * ```typescript
-     * // Basic health check endpoint
-     * app.get('/health', async (req, res) => {
-     *   const health = await ripple.getHealth()
-     *
-     *   return res
-     *     .status(health.healthy ? 200 : 503)
-     *     .json(health)
-     * })
-     *
-     * // Kubernetes liveness probe
-     * app.get('/healthz', async (req, res) => {
-     *   try {
-     *     const health = await ripple.getHealth()
-     *     if (health.healthy) {
-     *       return res.status(200).send('OK')
-     *     } else {
-     *       return res.status(503).json({ error: 'Unhealthy', details: health.checks })
-     *     }
-     *   } catch (error) {
-     *     return res.status(503).json({ error: 'Health check failed' })
-     *   }
-     * })
-     *
-     * // Detailed health monitoring
-     * app.get('/admin/health-detail', async (req, res) => {
-     *   const [health, stats] = await Promise.all([
-     *     ripple.getHealth(),
-     *     Promise.resolve(ripple.getStats())
-     *   ])
-     *
-     *   return res.json({
-     *     ...health,
-     *     metrics: {
-     *       connections: stats.totalConnections,
-     *       channels: stats.totalChannels,
-     *       uptime: process.uptime()
-     *     }
-     *   })
-     * })
-     * ```
-     *
-     * @see {@link getStats} - For connection and channel statistics
      */
     getHealth(): Promise<import(".").HealthCheckResult>;
     /**
-     * Initialize the RippleServer.
+     * Initialize and start the RippleServer.
      *
-     * Performs initialization tasks including driver setup (Redis/Local) and starting
-     * the ping interval for connection health monitoring. This method **must** be called
-     * before the server starts accepting WebSocket connections.
+     * This method:
+     * 1. Initializes the driver (Redis/NATS/Local)
+     * 2. Initializes the serializer (JSON/Protobuf)
+     * 3. Starts the WebSocket engine (Bun/uWS/ws)
+     * 4. Starts the ping interval
      *
-     * **Important**: Call this method during application startup, before `Bun.serve()`.
-     *
-     * @returns Promise that resolves when initialization is complete
-     * @throws {Error} If driver initialization fails (e.g., Redis connection failed)
-     *
-     * @example
-     * ```typescript
-     * // Basic initialization
-     * const ripple = new RippleServer({ path: '/ws' })
-     * await ripple.init()
-     *
-     * Bun.serve({
-     *   fetch: (req, server) => {
-     *     if (ripple.upgrade(req, server)) return
-     *     return new Response('Not found', { status: 404 })
-     *   },
-     *   websocket: ripple.getHandler()
-     * })
-     *
-     * // With Redis driver
-     * const ripple = new RippleServer({
-     *   path: '/ws',
-     *   driver: 'redis',
-     *   redis: {
-     *     host: 'localhost',
-     *     port: 6379
-     *   }
-     * })
-     *
-     * try {
-     *   await ripple.init()
-     *   console.log('RippleServer initialized successfully')
-     * } catch (error) {
-     *   console.error('Failed to initialize RippleServer:', error)
-     *   process.exit(1)
-     * }
-     *
-     * // With graceful shutdown
-     * const ripple = new RippleServer({ path: '/ws' })
-     * await ripple.init()
-     *
-     * process.on('SIGTERM', async () => {
-     *   console.log('SIGTERM received, shutting down...')
-     *   await ripple.shutdown()
-     *   process.exit(0)
-     * })
-     * ```
-     *
-     * @see {@link shutdown} - For graceful server shutdown
+     * @since 5.0.0
      */
-    init(): Promise<void>;
+    start(): Promise<void>;
     /**
-     * Shutdown the RippleServer gracefully.
-     *
-     * Performs cleanup tasks including stopping the ping interval, closing driver connections
-     * (Redis/Local), and releasing resources. This method should be called during application
-     * shutdown to ensure graceful cleanup.
-     *
-     * **Important**: Call this method when receiving shutdown signals (SIGTERM, SIGINT) or
-     * during application teardown to prevent resource leaks.
+     * Initialize the RippleServer without starting the engine.
      *
-     * @returns Promise that resolves when shutdown is complete
-     *
-     * @example
-     * ```typescript
-     * // Basic shutdown
-     * const ripple = new RippleServer({ path: '/ws' })
-     * await ripple.init()
-     *
-     * // Later, during shutdown
-     * await ripple.shutdown()
-     *
-     * // Graceful shutdown with signal handling
-     * const ripple = new RippleServer({ path: '/ws' })
-     * await ripple.init()
-     *
-     * process.on('SIGTERM', async () => {
-     *   console.log('SIGTERM received, shutting down gracefully...')
-     *   await ripple.shutdown()
-     *   console.log('RippleServer shutdown complete')
-     *   process.exit(0)
-     * })
-     *
-     * process.on('SIGINT', async () => {
-     *   console.log('SIGINT received, shutting down gracefully...')
-     *   await ripple.shutdown()
-     *   process.exit(0)
-     * })
-     *
-     * // Shutdown with timeout for Kubernetes
-     * process.on('SIGTERM', async () => {
-     *   const timeout = setTimeout(() => {
-     *     console.error('Shutdown timeout, forcing exit')
-     *     process.exit(1)
-     *   }, 10000) // 10 second timeout
-     *
-     *   try {
-     *     await ripple.shutdown()
-     *     clearTimeout(timeout)
-     *     process.exit(0)
-     *   } catch (error) {
-     *     console.error('Shutdown error:', error)
-     *     process.exit(1)
-     *   }
-     * })
-     *
-     * // Test cleanup
-     * afterAll(async () => {
-     *   await ripple.shutdown()
-     * })
-     * ```
-     *
-     * @see {@link init} - For server initialization
+     * @deprecated Use start() instead. This method is kept for backward compatibility.
+     * @since 3.0.0
      */
+    init(): Promise<void>;
     shutdown(): Promise<void>;
 }

package/dist/ripple/src/channels/ChannelManager.d.ts

@@ -5,7 +5,8 @@
  *
  * @module @gravito/ripple/channels
  */
-import type { PresenceUserInfo, RippleWebSocket } from '../types';
+import type { RippleSocket } from '../engines/IRippleEngine';
+import type { PresenceUserInfo, RippleDriver } from '../types';
 /**
  * Manages all channel subscriptions and presence tracking.
  *
@@ -46,6 +47,14 @@ export declare class ChannelManager {
     private clients;
     /** Map of presence channel -> Map of user ID -> user info */
     private presenceMembers;
+    /** Optional driver for distributed presence tracking */
+    private driver?;
+    /**
+     * Create a new ChannelManager.
+     *
+     * @param driver - Optional driver for distributed presence tracking
+     */
+    constructor(driver?: RippleDriver);
     /**
      * Register a new client WebSocket connection.
      *
@@ -63,7 +72,7 @@ export declare class ChannelManager {
      * }
      * ```
      */
-    addClient(ws: RippleWebSocket): void;
+    addClient(ws: RippleSocket): void;
     /**
      * Remove a client and unsubscribe from all channels.
      *
@@ -96,13 +105,13 @@ export declare class ChannelManager {
      * @param clientId - The client identifier
      * @returns The WebSocket connection, or undefined if not found
      */
-    getClient(clientId: string): RippleWebSocket | undefined;
+    getClient(clientId: string): RippleSocket | undefined;
     /**
      * Get all currently connected WebSocket clients.
      *
      * @returns Array of all connected WebSocket instances
      */
-    getAllClients(): RippleWebSocket[];
+    getAllClients(): RippleSocket[];
     /**
      * Subscribe a client to a channel.
      *
@@ -111,7 +120,7 @@ export declare class ChannelManager {
      * @param userInfo - User information for presence channels (required for presence-* channels)
      * @returns true if subscription succeeded, false if client not found
      */
-    subscribe(clientId: string, channel: string, userInfo?: PresenceUserInfo): boolean;
+    subscribe(clientId: string, channel: string, userInfo?: PresenceUserInfo): Promise<boolean>;
     /**
      * Unsubscribe a client from a channel.
      *
@@ -119,14 +128,14 @@ export declare class ChannelManager {
      * @param channel - The channel name
      * @returns true if unsubscription succeeded, false if client not found
      */
-    unsubscribe(clientId: string, channel: string): boolean;
+    unsubscribe(clientId: string, channel: string): Promise<boolean>;
     /**
      * Get all WebSocket subscribers of a channel.
      *
      * @param channel - The channel name
      * @returns Array of WebSocket connections subscribed to the channel
      */
-    getSubscribers(channel: string): RippleWebSocket[];
+    getSubscribers(channel: string): RippleSocket[];
     /**
      * Check if a client is subscribed to a channel.
      *
@@ -136,20 +145,26 @@ export declare class ChannelManager {
      */
     isSubscribed(clientId: string, channel: string): boolean;
     /**
-     * Add a member to a presence channel
+     * Add a member to a presence channel.
+     *
+     * Uses driver for distributed tracking if available.
      */
     private addPresenceMember;
     /**
-     * Remove a member from a presence channel
+     * Remove a member from a presence channel.
+     *
+     * Uses driver for distributed tracking if available.
      */
     private removePresenceMember;
     /**
      * Get all members of a presence channel.
      *
+     * Queries driver if available for distributed presence data.
+     *
      * @param channel - The presence channel name
      * @returns Array of user information for all members in the channel
      */
-    getPresenceMembers(channel: string): PresenceUserInfo[];
+    getPresenceMembers(channel: string): Promise<PresenceUserInfo[]>;
     /**
      * Get subscriber count for a channel.
      *