@gravito/ripple 3.1.0 → 4.0.1

package/dist/ripple/src/reliability/AckManager.d.ts

@@ -0,0 +1,48 @@
+import type { RippleLogger } from '../logging/Logger';
+/**
+ * Interface for a message that is pending acknowledgement.
+ */
+export interface PendingAck {
+    clientId: string;
+    seq: number;
+    timer: ReturnType<typeof setTimeout>;
+    resolve: (value: boolean) => void;
+    reject: (reason: any) => void;
+}
+/**
+ * Manages message acknowledgements for Ripple.
+ *
+ * @since 3.7.0
+ */
+export declare class AckManager {
+    private pendingAcks;
+    private nextSeq;
+    private logger;
+    constructor(logger: RippleLogger);
+    /**
+     * Register a message that requires acknowledgement.
+     *
+     * @param clientId - The ID of the client the message was sent to
+     * @param timeout - How long to wait for ACK in ms
+     * @returns A promise that resolves to true when ACKed, or false if timed out
+     */
+    register(clientId: string, timeout?: number): {
+        seq: number;
+        promise: Promise<boolean>;
+    };
+    /**
+     * Confirm receipt of a message.
+     *
+     * @param clientId - The ID of the client that sent the ACK
+     * @param seq - The sequence number being confirmed
+     */
+    confirm(clientId: string, seq: number): boolean;
+    /**
+     * Clear all pending ACKs for a client (e.g., on disconnect).
+     */
+    clearClient(clientId: string): void;
+    /**
+     * Get the number of pending ACKs.
+     */
+    getPendingCount(): number;
+}

package/dist/ripple/src/serializers/ISerializer.d.ts

@@ -0,0 +1,39 @@
+import type { ClientMessage, ServerMessage } from '../types';
+/**
+ * Interface for message serialization strategies.
+ *
+ * Defines how messages are converted between objects and wire format.
+ * Supports different serialization formats (e.g., JSON, Protobuf).
+ */
+export interface ISerializer {
+    /** The content type this serializer handles */
+    readonly contentType: 'json' | 'protobuf';
+    /**
+     * Serialize a server message for transmission.
+     *
+     * @param message - The message to serialize
+     * @returns Serialized data (string for text, Buffer/Uint8Array for binary)
+     */
+    serialize(message: ServerMessage): string | Buffer | Uint8Array;
+    /**
+     * Deserialize a client message from wire format.
+     *
+     * @param data - The raw data received from the client
+     * @returns Parsed ClientMessage object
+     */
+    deserialize(data: string | Buffer | ArrayBuffer | Uint8Array): ClientMessage;
+    /**
+     * Serialize message for broadcasting with caching optimization.
+     *
+     * @param message - The message to broadcast
+     */
+    serializeForBroadcast(message: ServerMessage): string | Buffer | Uint8Array;
+    /**
+     * Clear any broadcast-related caches.
+     */
+    clearBroadcastCache(): void;
+    /**
+     * Get a pre-serialized PONG message for efficient heartbeats.
+     */
+    getPongMessage(): string | Buffer | Uint8Array;
+}

package/dist/ripple/src/serializers/JsonSerializer.d.ts

@@ -0,0 +1,19 @@
+import type { ClientMessage, ServerMessage } from '../types';
+import type { ISerializer } from './ISerializer';
+/**
+ * Default JSON serializer implementation.
+ *
+ * Handles standard JSON serialization with optimizations for broadcasting.
+ */
+export declare class JsonSerializer implements ISerializer {
+    readonly contentType = "json";
+    /** Pre-serialized pong message */
+    private static readonly PONG_MESSAGE;
+    /** Cached serialized string for the current broadcast operation */
+    private broadcastCache;
+    serialize(message: ServerMessage): string;
+    deserialize(data: string | Buffer | ArrayBuffer | Uint8Array): ClientMessage;
+    serializeForBroadcast(message: ServerMessage): string;
+    clearBroadcastCache(): void;
+    getPongMessage(): string;
+}

package/dist/ripple/src/serializers/ProtobufSerializer.d.ts

@@ -0,0 +1,41 @@
+import type { ClientMessage, ServerMessage } from '../types';
+import type { ISerializer } from './ISerializer';
+/**
+ * Protobuf Serializer implementation.
+ *
+ * Uses 'ripple.proto' to serialize messages.
+ * Requires 'protobufjs' to be installed.
+ */
+export declare class ProtobufSerializer implements ISerializer {
+    private options;
+    readonly contentType = "protobuf";
+    private broadcastCache;
+    private initialized;
+    constructor(options?: {
+        protoPath?: string;
+        pure?: boolean;
+    });
+    /**
+     * Resolves the proto file path using a multi-level fallback strategy.
+     *
+     * Search order:
+     * 1. Relative to current file (ESM: import.meta.url)
+     * 2. From cwd as package root (common in test environments)
+     * 3. From cwd as monorepo root
+     */
+    private resolveProtoPath;
+    /**
+     * Initialize the serializer by loading the .proto file
+     */
+    init(): Promise<void>;
+    serialize(message: ServerMessage): Uint8Array;
+    deserialize(data: string | Buffer | ArrayBuffer | Uint8Array): ClientMessage;
+    serializeForBroadcast(message: ServerMessage): Uint8Array;
+    clearBroadcastCache(): void;
+    getPongMessage(): Uint8Array;
+    private checkInitialized;
+    private toProtoPayload;
+    private fromProtoPayload;
+    private encodeData;
+    private decodeData;
+}

package/dist/ripple/src/serializers/index.d.ts

@@ -0,0 +1,3 @@
+export * from './ISerializer';
+export * from './JsonSerializer';
+export * from './ProtobufSerializer';

package/dist/ripple/src/tracking/SessionManager.d.ts

@@ -0,0 +1,104 @@
+/**
+ * @fileoverview Session Manager for reconnection support
+ *
+ * @module @gravito/ripple/tracking
+ */
+import type { RippleLogger } from '../logging/Logger';
+/**
+ * Session data stored for reconnection.
+ */
+export interface SessionData {
+    /** Client ID */
+    clientId: string;
+    /** User ID if authenticated */
+    userId?: string | number;
+    /** Channels the client was subscribed to */
+    channels: string[];
+    /** User info for presence channels */
+    userInfo?: Record<string, unknown>;
+    /** Session expiry timestamp */
+    expiresAt: number;
+}
+/**
+ * Manages disconnected client sessions for reconnection support.
+ *
+ * When a client disconnects, their session is stored temporarily to allow
+ * them to reconnect and resume their subscriptions without re-authorization.
+ *
+ * @example
+ * ```typescript
+ * const sessionManager = new SessionManager({
+ *   sessionTTL: 60000, // 1 minute
+ *   maxSessions: 10000
+ * })
+ *
+ * // On disconnect
+ * const token = sessionManager.createSession({
+ *   clientId: 'client-123',
+ *   userId: 'user-456',
+ *   channels: ['news', 'presence-lobby'],
+ *   userInfo: { name: 'John' }
+ * })
+ *
+ * // On reconnect
+ * const session = sessionManager.getSession(token)
+ * if (session) {
+ *   // Restore subscriptions
+ *   for (const channel of session.channels) {
+ *     await subscribe(session.clientId, channel)
+ *   }
+ * }
+ * ```
+ */
+export declare class SessionManager {
+    private config;
+    private sessions;
+    private cleanupInterval?;
+    private logger;
+    constructor(config: {
+        sessionTTL: number;
+        maxSessions: number;
+        logger?: RippleLogger;
+    });
+    /**
+     * Create a new session for a disconnected client.
+     *
+     * @param data - Session data to store
+     * @param token - Optional specific token to use (otherwise generates new UUID)
+     * @returns Reconnection token
+     */
+    createSession(data: Omit<SessionData, 'expiresAt'>, token?: string): string;
+    /**
+     * Get a session by reconnection token.
+     *
+     * @param token - Reconnection token
+     * @returns Session data if found and not expired, undefined otherwise
+     */
+    getSession(token: string): SessionData | undefined;
+    /**
+     * Remove a session by token.
+     *
+     * @param token - Reconnection token
+     */
+    removeSession(token: string): void;
+    /**
+     * Get the number of active sessions.
+     */
+    getSessionCount(): number;
+    /**
+     * Start periodic cleanup of expired sessions.
+     */
+    private startCleanup;
+    /**
+     * Clean up expired sessions.
+     */
+    private cleanupExpiredSessions;
+    /**
+     * Remove the oldest session to make room for new ones.
+     */
+    private removeOldestSession;
+    /**
+     * Shutdown the session manager and clear all sessions.
+     */
+    shutdown(): void;
+}

package/dist/ripple/src/tracking/index.d.ts

@@ -1 +1,2 @@
 export * from './ConnectionTracker';
+export * from './SessionManager';

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

@@ -3,6 +3,8 @@
  * @module @gravito/ripple
  */
 import type { Server, ServerWebSocket } from 'bun';
+import type { NATSDriverConfig } from './drivers/NATSDriver';
+import type { RedisDriverConfig } from './drivers/RedisDriver';
 /**
  * Data attached to each WebSocket connection.
  *
@@ -28,6 +30,12 @@ export interface ClientData {
     channels: Set<string>;
     /** Additional user info for presence channels */
     userInfo?: Record<string, unknown>;
+    /** Reconnection token for session recovery (v3.6+) */
+    reconnectionToken?: string;
+    /** Session expiry timestamp (v3.6+) */
+    sessionExpiry?: number;
+    /** Remote IP address (v5.0+) */
+    remoteAddress?: string;
 }
 /**
  * Supported WebSocket channel types.
@@ -172,7 +180,7 @@ export interface PresenceUserInfo {
  * }
  * ```
  */
-export type ChannelAuthorizer = (channelName: string, userId: string | number | undefined, socketId: string) => boolean | Promise<boolean> | PresenceUserInfo | Promise<PresenceUserInfo | false>;
+export type ChannelAuthorizer = (channelName: string, userId: string | number | undefined, socketId: string) => boolean | PresenceUserInfo | Promise<boolean | PresenceUserInfo>;
 /**
  * Interface for broadcast event classes.
  *
@@ -260,6 +268,14 @@ export type ClientMessage = {
     data: unknown;
 } | {
     type: 'ping';
+} | {
+    type: 'binary';
+    channel: string;
+    event: string;
+    data: ArrayBuffer;
+} | {
+    type: 'ack';
+    seq: number;
 };
 /**
  * Error codes for Ripple WebSocket protocol.
@@ -349,17 +365,54 @@ export type ServerMessage = {
     channel: string;
     event: string;
     data: unknown;
+    seq?: number;
+    needAck?: boolean;
 } | {
     type: 'presence';
     channel: string;
     event: 'join' | 'leave' | 'members';
     data: unknown;
+    seq?: number;
+    needAck?: boolean;
 } | {
     type: 'pong';
 } | {
     type: 'connected';
     socketId: string;
+} | {
+    type: 'binary';
+    channel: string;
+    event: string;
+    data: ArrayBuffer;
+    seq?: number;
+    needAck?: boolean;
+} | {
+    type: 'ack_received';
+    seq: number;
+} | {
+    type: 'reconnection_token';
+    token: string;
 };
+/**
+ * Context for Ripple Message Interceptors (v4.0+).
+ */
+export interface RippleContext {
+    /** The WebSocket client connection */
+    ws: import('./engines/IRippleEngine').RippleSocket;
+    /** The message being processed */
+    message: ClientMessage | ServerMessage;
+    /** Direction of the message flow */
+    direction: 'incoming' | 'outgoing';
+    /** Channel name (optional) */
+    channel?: string;
+    /** Event name (optional) */
+    event?: string;
+}
+/**
+ * Middleware function for intercepting Ripple messages.
+ * Next function must be called to continue the pipeline.
+ */
+export type RippleInterceptor = (ctx: RippleContext, next: () => Promise<void>) => Promise<void> | void;
 /**
  * Driver health status information.
  *
@@ -410,6 +463,8 @@ export declare const SERVER_MESSAGE_TYPES: {
     readonly PRESENCE: "presence";
     readonly PONG: "pong";
     readonly CONNECTED: "connected";
+    readonly BINARY: "binary";
+    readonly RECONNECTION_TOKEN: "reconnection_token";
 };
 /**
  * Client message type constants.
@@ -432,6 +487,8 @@ export declare const CLIENT_MESSAGE_TYPES: {
     readonly UNSUBSCRIBE: "unsubscribe";
     readonly WHISPER: "whisper";
     readonly PING: "ping";
+    readonly BINARY: "binary";
+    readonly ACK: "ack";
 };
 /**
  * Interface for implementing custom Ripple drivers.
@@ -445,8 +502,10 @@ export declare const CLIENT_MESSAGE_TYPES: {
  * @example
  * ```typescript
  * // Example: Custom NATS driver implementation
- * import { RippleDriver, DriverStatus } from '@gravito/ripple'
- * import { connect, NatsConnection, Subscription } from 'nats'
+ * import type { RedisDriverConfig } from './drivers/RedisDriver'
+import type { NATSDriverConfig } from './drivers/NATSDriver'
+import type { ComponentHealth } from './health/HealthChecker'
+import { connect, NatsConnection, Subscription } from 'nats'
  *
  * export class NatsDriver implements RippleDriver {
  *   readonly name = 'nats'
@@ -549,6 +608,35 @@ export interface RippleDriver {
      * @returns Current driver status
      */
     getStatus?(): DriverStatus;
+    /**
+     * Track a presence member in a channel (optional).
+     *
+     * For distributed drivers like Redis, this stores presence information
+     * in a shared backend so all server instances can see the same members.
+     *
+     * @param channel - Presence channel name
+     * @param userInfo - User information to track
+     * @since 3.6.0
+     */
+    trackPresence?(channel: string, userInfo: PresenceUserInfo): Promise<void>;
+    /**
+     * Remove a presence member from a channel (optional).
+     *
+     * @param channel - Presence channel name
+     * @param userId - User ID to remove
+     * @since 3.6.0
+     */
+    untrackPresence?(channel: string, userId: string | number): Promise<void>;
+    /**
+     * Get all presence members for a channel (optional).
+     *
+     * For distributed drivers, this retrieves members from the shared backend.
+     *
+     * @param channel - Presence channel name
+     * @returns Array of presence user information
+     * @since 3.6.0
+     */
+    getPresenceMembers?(channel: string): Promise<PresenceUserInfo[]>;
 }
 /**
  * Ripple server configuration.
@@ -631,15 +719,12 @@ export interface RippleConfig {
     path?: string;
     /** Authentication endpoint for private/presence channels */
     authEndpoint?: string;
-    /** Driver to use ('local' | 'redis') */
-    driver?: 'local' | 'redis';
-    /** Redis configuration (if using redis driver) */
-    redis?: {
-        host?: string;
-        port?: number;
-        password?: string;
-        db?: number;
-    };
+    /** Driver to use for scaling ('local' | 'redis' | 'nats') */
+    driver?: 'local' | 'redis' | 'nats';
+    /** Configuration for Redis driver */
+    redis?: RedisDriverConfig;
+    /** Configuration for NATS driver (v4.0+) */
+    nats?: NATSDriverConfig;
     /** Channel authorizer function */
     authorizer?: ChannelAuthorizer;
     /** Ping interval in milliseconds (default: 30000) */
@@ -655,6 +740,97 @@ export interface RippleConfig {
         enabled: boolean;
         path?: string;
     };
+    /**
+     * Rate limiting configuration.
+     */
+    rateLimit?: {
+        /** Max whispers per interval */
+        whisperMax?: number;
+        /** Interval in milliseconds for whisper limit (default: 1000) */
+        whisperInterval?: number;
+    };
+    /**
+     * Reconnection configuration (v3.6+).
+     */
+    reconnection?: {
+        /** Enable server-assisted reconnection (default: false) */
+        enabled?: boolean;
+        /** Session TTL in milliseconds (default: 60000 = 1 minute) */
+        sessionTTL?: number;
+        /** Maximum number of stored sessions (default: 10000) */
+        maxSessions?: number;
+    };
+    /**
+     * Serializer to use for messages (default: 'json').
+     *
+     * 'json': Recommended for most use cases. Zero configuration,
+     *         browser-native, easy debugging. No additional dependencies.
+     *
+     * 'protobuf': For specialized use cases (IoT, bandwidth-constrained networks).
+     *             Requires 'protobufjs' peer dependency to be installed.
+     *             Install with: npm install protobufjs
+     */
+    serializer?: 'json' | 'protobuf';
+    /**
+     * Configuration for the serializer (v5.0+).
+     */
+    serializerOptions?: {
+        /** Path to custom .proto file (Protobuf only) */
+        protoPath?: string;
+        /** Enable pure binary mode (no JSON envelope for payload) - Protobuf only (default: false) */
+        pure?: boolean;
+    };
+    /**
+     * Performance & Backpressure (v3.7+).
+     */
+    backpressure?: {
+        /** High Water Mark in bytes. Force disconnect if reached. (default: 5,242,880 = 5MB) */
+        hwmHigh?: number;
+        /** Low Water Mark in bytes. Skip non-critical events if reached. (default: 1,048,576 = 1MB) */
+        hwmLow?: number;
+        /** Whether to enable automatic slow client isolation (default: false) */
+        enabled?: boolean;
+    };
+    /**
+     * Prometheus Metrics (v3.7+).
+     */
+    metrics?: {
+        /** Enable Prometheus metrics (default: false) */
+        enabled?: boolean;
+        /** Metric name prefix (default: 'ripple') */
+        prefix?: string;
+    };
+    /**
+     * Message Interceptors (v4.0+).
+     */
+    interceptors?: RippleInterceptor[];
+    /**
+     * WebSocket runtime/engine to use (v5.0+).
+     *
+     * - 'bun': Bun native WebSocket (default, highest performance)
+     * - 'node-uws': uWebSockets.js for Node.js (high performance, requires peer dep)
+     * - 'node-ws': ws package for Node.js (standard, best compatibility)
+     *
+     * If not specified, Ripple will auto-detect the runtime.
+     *
+     * @since 5.0.0
+     */
+    runtime?: 'bun' | 'node-uws' | 'node-ws';
+    /**
+     * Server port to listen on (v5.0+).
+     *
+     * Required when using the engine-based architecture.
+     *
+     * @since 5.0.0
+     */
+    port?: number;
+    /**
+     * Hostname to bind to (v5.0+).
+     *
+     * @default '0.0.0.0'
+     * @since 5.0.0
+     */
+    hostname?: string;
 }
 /**
  * Strongly-typed Bun ServerWebSocket for Ripple.

package/dist/ripple/src/utils/MessageSerializer.d.ts

@@ -1,44 +1,54 @@
-import type { ServerMessage } from '../types';
+import type { ISerializer } from '../serializers/ISerializer';
+import type { ClientMessage, ServerMessage } from '../types';
 /**
- * Utility class for serializing server-to-client messages.
+ * 訊息序列化器，用於 JSON 格式的訊息序列化與反序列化。
  *
- * Provides performance optimizations like pre-serialized common messages
- * and a per-broadcast cache to reduce JSON.stringify overhead during
- * multi-channel broadcasting.
+ * 實現了廣播消息的緩存優化，確保相同的訊息只被序列化一次，
+ * 然後發送給所有客戶端，從而減少 CPU 開銷。
  */
-export declare class MessageSerializer {
-    /** Pre-serialized pong message for heartbeat responses */
+export declare class MessageSerializer implements ISerializer {
+    readonly contentType = "json";
+    /** 預序列化的 PONG 訊息 */
     private static readonly PONG_MESSAGE;
-    /** Cached serialized string for the current broadcast operation */
+    /** 廣播訊息緩存 */
     private broadcastCache;
     /**
-     * Get the pre-serialized pong message.
+     * 序列化伺服器訊息為 JSON 字符串。
      *
-     * @returns Serialized {"type":"pong"} string
+     * @param message - 要序列化的訊息
+     * @returns JSON 字符串
      */
-    getPongMessage(): string;
+    serialize(message: ServerMessage): string;
     /**
-     * Serialize a server message to a JSON string.
+     * 將訊息反序列化為客戶端訊息物件。
      *
-     * @param message - The server message object to serialize
-     * @returns Serialized JSON string
+     * @param data - 原始數據
+     * @returns 解析後的客戶端訊息
      */
-    serialize(message: ServerMessage): string;
+    deserialize(data: string | Buffer | ArrayBuffer): ClientMessage;
     /**
-     * Serialize a message for broadcasting, with internal caching.
+     * 為廣播序列化訊息，支援緩存優化。
      *
-     * If a broadcast cache already exists, it is returned immediately.
-     * Otherwise, the message is serialized and stored in the cache.
+     * 第一次序列化時會緩存結果，後續相同的訊息會直接返回緩存值，
+     * 避免重複序列化。這在廣播給大量客戶端時可以顯著減少 CPU 使用。
      *
-     * @param message - The server message to serialize and cache
-     * @returns Serialized JSON string
+     * @param message - 要廣播的訊息
+     * @returns 序列化的訊息
      */
     serializeForBroadcast(message: ServerMessage): string;
     /**
-     * Clear the current broadcast cache.
+     * 清除廣播訊息緩存。
      *
-     * Should be called after a broadcast operation is complete to prepare
-     * for the next broadcast.
+     * 應在訊息發送完成後調用，以釋放記憶體。
      */
     clearBroadcastCache(): void;
+    /**
+     * 取得預序列化的 PONG 訊息。
+     *
+     * PONG 訊息是一個常用的心跳訊息，為了效率我們將其預序列化為常數，
+     * 每次都返回相同的字符串引用，無需重複序列化。
+     *
+     * @returns 預序列化的 PONG 訊息
+     */
+    getPongMessage(): string;
 }

package/dist/ripple/src/utils/TokenBucket.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Simple Token Bucket algorithm for rate limiting.
+ *
+ * @internal
+ */
+export declare class TokenBucket {
+    private capacity;
+    private fillRatePerMs;
+    private tokens;
+    private lastRefill;
+    /**
+     * Create a new TokenBucket instance.
+     *
+     * @param capacity - Max tokens in the bucket.
+     * @param fillRatePerMs - Rate at which tokens are added (tokens per millisecond).
+     */
+    constructor(capacity: number, fillRatePerMs: number);
+    /**
+     * Consume a token from the bucket.
+     *
+     * @returns true if token was consumed, false if bucket is empty.
+     */
+    consume(): boolean;
+    private refill;
+}