@gravito/ripple 3.0.1 → 4.0.0

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

@@ -5,98 +5,99 @@
  *
  * @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;
+    private logger;
+    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 client messages.
-     *
-     * @param event - The event name to listen for.
-     * @param handler - The callback function.
+     * 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.
-     *
-     * @param channel - The channel name.
+     * 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.
+     * Upgrade an HTTP request to WebSocket (Bun/uWS only).
      *
-     * @param req - The HTTP request.
-     * @param server - The Bun server instance.
-     * @returns True if the request was upgraded, false otherwise.
+     * @deprecated Use engine-based initialization via init() instead.
+     * This method is kept for backward compatibility with v4.x.
      */
-    upgrade(req: Request, server: Server<ClientData>): boolean;
+    upgrade(req: Request, options?: {
+        userId?: string;
+    }): boolean;
     /**
-     * Get WebSocket handler configuration for Bun.serve.
+     * Get WebSocket handler configuration (Bun only).
      *
-     * @returns An object containing the WebSocket event handlers.
+     * @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 a channel.
-     *
-     * @param channel - The channel name.
-     * @param event - The event name.
-     * @param data - The event data.
-     */
-    broadcast(channel: string, event: string, data: unknown): void;
-    /**
-     * Broadcast to specific client IDs.
-     *
-     * @param clientIds - An array of client IDs.
-     * @param event - The event name.
-     * @param data - The event data.
-     */
+    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;
     /**
-     * Get server statistics.
-     *
-     * @returns An object containing connection and channel statistics.
+     * Add a middleware interceptor (v4.0+).
+     */
+    use(interceptor: RippleInterceptor): this;
+    /**
+     * Get real-time server statistics.
      */
     getStats(): {
         totalClients: number;
@@ -107,19 +108,31 @@ export declare class RippleServer {
         }[];
     };
     /**
-     * Initialize the server.
+     * Get Prometheus metrics (v3.7+).
+     */
+    getMetrics(): string;
+    /**
+     * Get server health status.
+     */
+    getHealth(): Promise<import(".").HealthCheckResult>;
+    /**
+     * Initialize and start the RippleServer.
      *
-     * Initializes the driver and starts the ping interval.
+     * 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
      *
-     * @returns A promise that resolves when initialization is complete.
+     * @since 5.0.0
      */
-    init(): Promise<void>;
+    start(): Promise<void>;
     /**
-     * Shutdown the server.
+     * Initialize the RippleServer without starting the engine.
      *
-     * Clears the ping interval and shuts down the driver.
-     *
-     * @returns A promise that resolves when shutdown is complete.
+     * @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,9 +5,40 @@
  *
  * @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
+ * Manages all channel subscriptions and presence tracking.
+ *
+ * The ChannelManager is the central coordinator for WebSocket channel subscriptions.
+ * It maintains mappings between clients, channels, and presence information, providing
+ * efficient lookups for broadcasting and presence tracking.
+ *
+ * **Internal Use**: This class is primarily used internally by RippleServer. Most developers
+ * interact with channels through RippleServer's public API instead.
+ *
+ * @example
+ * ```typescript
+ * // Typically used internally by RippleServer
+ * const manager = new ChannelManager()
+ *
+ * // Add a client when they connect
+ * manager.addClient(ws)
+ *
+ * // Subscribe them to a channel
+ * manager.subscribe(ws.data.id, 'news')
+ *
+ * // Get all subscribers for broadcasting
+ * const subscribers = manager.getSubscribers('news')
+ * subscribers.forEach(ws => ws.send(message))
+ *
+ * // For presence channels with user info
+ * manager.subscribe(ws.data.id, 'presence-chat.room1', {
+ *   id: 'user-123',
+ *   info: { name: 'John Doe', avatar: '/avatars/john.jpg' }
+ * })
+ * const members = manager.getPresenceMembers('presence-chat.room1')
+ * ```
  */
 export declare class ChannelManager {
     /** Map of channel name -> Set of client IDs */
@@ -16,56 +47,135 @@ 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 connection
+     * Register a new client WebSocket connection.
+     *
+     * Adds the client to the internal clients map, making it available for channel subscriptions
+     * and broadcasts. This should be called immediately when a WebSocket connection is established.
+     *
+     * @param ws - The WebSocket connection with client data
+     *
+     * @example
+     * ```typescript
+     * // Called internally by RippleServer on connection
+     * private handleOpen(ws: RippleWebSocket): void {
+     *   this.channels.addClient(ws)
+     *   // ... other connection logic
+     * }
+     * ```
      */
-    addClient(ws: RippleWebSocket): void;
+    addClient(ws: RippleSocket): void;
     /**
-     * Remove a client and all its subscriptions
+     * Remove a client and unsubscribe from all channels.
+     *
+     * Performs cleanup when a client disconnects, removing them from all channel subscriptions
+     * and the client registry. Returns the list of channels the client was subscribed to,
+     * useful for sending presence leave events.
+     *
+     * @param clientId - The unique client identifier (ws.data.id)
+     * @returns Array of channel names the client was subscribed to before removal
+     *
+     * @example
+     * ```typescript
+     * // Called internally by RippleServer on disconnect
+     * private handleClose(ws: RippleWebSocket): void {
+     *   const leftChannels = this.channels.removeClient(ws.data.id)
+     *
+     *   // Notify presence channels about user leaving
+     *   for (const channel of leftChannels) {
+     *     if (channel.startsWith('presence-')) {
+     *       this.broadcast(channel, 'presence', { event: 'leave', data: ... })
+     *     }
+     *   }
+     * }
+     * ```
      */
     removeClient(clientId: string): string[];
     /**
-     * Get a client by ID
+     * Get a client WebSocket by ID.
+     *
+     * @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 connected clients
+     * Get all currently connected WebSocket clients.
+     *
+     * @returns Array of all connected WebSocket instances
      */
-    getAllClients(): RippleWebSocket[];
+    getAllClients(): RippleSocket[];
     /**
-     * Subscribe a client to a channel
+     * Subscribe a client to a channel.
+     *
+     * @param clientId - The client identifier
+     * @param channel - The channel name
+     * @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
+     * Unsubscribe a client from a channel.
+     *
+     * @param clientId - The client identifier
+     * @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 subscribers of a channel
+     * 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
+     * Check if a client is subscribed to a channel.
+     *
+     * @param clientId - The client identifier
+     * @param channel - The channel name
+     * @returns true if subscribed, false otherwise
      */
     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
+     * 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 member count for a channel
+     * Get subscriber count for a channel.
+     *
+     * @param channel - The channel name
+     * @returns Number of clients subscribed to the channel
      */
     getMemberCount(channel: string): number;
     /**
-     * Get channel statistics
+     * Get comprehensive channel statistics.
+     *
+     * @returns Statistics object containing total clients, channels, and per-channel subscriber counts
      */
     getStats(): {
         totalClients: number;

package/dist/ripple/src/drivers/LocalDriver.d.ts

@@ -1,29 +1,61 @@
 /**
  * @fileoverview Local (in-memory) driver for @gravito/ripple
  *
- * Suitable for single-instance deployments. For horizontal scaling,
- * use the Redis driver.
- *
  * @module @gravito/ripple/drivers
  */
-import type { RippleDriver } from '../types';
+import type { DriverStatus, RippleDriver } from '../types';
 /**
- * In-memory driver for single-instance deployments
+ * Local (in-memory) driver for Ripple.
+ *
+ * This driver is intended for development and single-server deployments.
+ * It distributes messages directly within the current process memory.
  *
- * This driver keeps all state in memory and is suitable for:
- * - Development
- * - Single-server deployments
- * - Serverless functions (with caveats)
+ * @example
+ * ```typescript
+ * import { RippleServer, LocalDriver } from '@gravito/ripple'
  *
- * For multi-server deployments, use RedisDriver instead.
+ * const server = new RippleServer({
+ *   driver: 'local' // Uses LocalDriver internally
+ * })
+ * ```
  */
 export declare class LocalDriver implements RippleDriver {
+    /** Driver name identifier */
     readonly name = "local";
-    /** Event callbacks per channel */
+    /** In-memory map of channel subscribers: channel -> set of callbacks */
     private listeners;
+    private _initialized;
+    /**
+     * Publish a message to a channel within the current process.
+     *
+     * @param channel - Target channel name
+     * @param event - Event name
+     * @param data - Event payload
+     */
     publish(channel: string, event: string, data: unknown): Promise<void>;
+    /**
+     * Subscribe to a channel in memory.
+     *
+     * @param channel - Channel name
+     * @param callback - Function called when a message is published to this channel
+     */
     subscribe(channel: string, callback: (event: string, data: unknown) => void): Promise<void>;
+    /**
+     * Unsubscribe from a channel in memory.
+     *
+     * @param channel - Channel name
+     */
     unsubscribe(channel: string): Promise<void>;
+    /**
+     * Initialize the local driver.
+     */
     init(): Promise<void>;
+    /**
+     * Shutdown the local driver and clear all listeners.
+     */
     shutdown(): Promise<void>;
+    /**
+     * Get the current status of the local driver.
+     */
+    getStatus(): DriverStatus;
 }

package/dist/ripple/src/drivers/NATSDriver.d.ts

@@ -0,0 +1,87 @@
+/**
+ * @fileoverview NATS driver for @gravito/ripple
+ *
+ * @module @gravito/ripple/drivers
+ */
+import type { ConnectionOptions } from 'nats';
+import type { RippleLogger } from '../logging/Logger';
+import type { DriverStatus, PresenceUserInfo, RippleDriver } from '../types';
+/**
+ * Configuration for the NATSDriver.
+ */
+export interface NATSDriverConfig {
+    /** NATS server URL (default: 'nats://localhost:4222') */
+    servers?: string | string[];
+    /** Credentials for authentication */
+    user?: string;
+    password?: string;
+    token?: string;
+    /** Prefix for Ripple NATS subjects (default: 'ripple.') */
+    subjectPrefix?: string;
+    /** Custom logger instance */
+    logger?: RippleLogger;
+    /** Optional NATS connection options */
+    connectionOptions?: ConnectionOptions;
+}
+/**
+ * NATS driver for Ripple, offering high-performance distributed broadcasting.
+ *
+ * @example
+ * ```typescript
+ * import { RippleServer, NATSDriver } from '@gravito/ripple'
+ *
+ * const server = new RippleServer({
+ *   driver: 'nats',
+ *   nats: {
+ *     servers: 'nats://localhost:4222'
+ *   }
+ * })
+ * ```
+ */
+export declare class NATSDriver implements RippleDriver {
+    private config;
+    readonly name = "nats";
+    private nats?;
+    private subjectPrefix;
+    private subscriptions;
+    private callbacks;
+    private _initialized;
+    private _connected;
+    private _lastError?;
+    private logger;
+    constructor(config?: NATSDriverConfig);
+    get isInitialized(): boolean;
+    init(): Promise<void>;
+    publish(channel: string, event: string, data: unknown): Promise<void>;
+    subscribe(channel: string, callback: (event: string, data: unknown) => void): Promise<void>;
+    unsubscribe(channel: string): Promise<void>;
+    shutdown(): Promise<void>;
+    getStatus(): DriverStatus;
+    /**
+     * Track presence member using NATS KV Store.
+     *
+     * Creates or updates a bucket for the channel and stores user info with TTL.
+     *
+     * @param channel - Presence channel name
+     * @param userInfo - User information to store
+     * @since 4.0.0-alpha
+     */
+    trackPresence(channel: string, userInfo: PresenceUserInfo): Promise<void>;
+    /**
+     * Remove presence member from NATS KV Store.
+     *
+     * @param channel - Presence channel name
+     * @param userId - User ID to remove
+     * @since 4.0.0-alpha
+     */
+    untrackPresence(channel: string, userId: string | number): Promise<void>;
+    /**
+     * Get all presence members from NATS KV Store.
+     *
+     * @param channel - Presence channel name
+     * @returns Array of presence user information
+     * @since 4.0.0-alpha
+     */
+    getPresenceMembers(channel: string): Promise<PresenceUserInfo[]>;
+    private handleError;
+}