@gravito/ripple 4.0.0 → 4.0.1

package/dist/photon/src/index.d.ts

@@ -77,6 +77,11 @@ export * from './middleware/htmx';
  * @public
  */
 export * from './middleware/ratelimit';
+/**
+ * Redis-based rate limiting storage.
+ * @public
+ */
+export * from './middleware/ratelimit-redis';
 /**
  * OpenAPI utilities
  * @public

package/dist/photon/src/middleware/ratelimit-redis.d.ts

@@ -0,0 +1,50 @@
+import type { RateLimitState, RateLimitStore } from './ratelimit';
+/**
+ * Redis-based storage for Rate Limiting.
+ *
+ * Implements atomic rate limiting using Lua scripts to prevent race conditions
+ * in distributed environments.
+ *
+ * @remarks
+ * This store is recommended for production environments with multiple application
+ * instances. It requires a Redis client (like ioredis or node-redis).
+ *
+ * @example
+ * ```typescript
+ * import Redis from 'ioredis'
+ * import { rateLimit } from '@gravito/photon/middleware'
+ * import { RedisStore } from '@gravito/photon/middleware/ratelimit-redis'
+ *
+ * const redis = new Redis()
+ * const app = new Photon()
+ *
+ * app.use(rateLimit({
+ *   maxRequests: 100,
+ *   windowMs: 60000,
+ *   store: new RedisStore(redis, { maxRequests: 100, windowMs: 60000 })
+ * }))
+ * ```
+ * @public
+ */
+export declare class RedisStore implements RateLimitStore {
+    private client;
+    private config;
+    /**
+     * Create a new RedisStore.
+     *
+     * @param client - Redis client instance (must support .eval())
+     * @param config - Rate limit configuration
+     */
+    constructor(client: any, config: {
+        maxRequests: number;
+        windowMs: number;
+        prefix?: string;
+    });
+    private get prefix();
+    /**
+     * Atomic increment and TTL management using Lua.
+     */
+    increment(key: string): Promise<RateLimitState>;
+    reset(key: string): Promise<void>;
+    get(key: string): Promise<RateLimitState | null>;
+}

package/dist/photon/src/middleware/ratelimit.d.ts

@@ -88,11 +88,15 @@ export interface RateLimitState {
 export declare class MemoryStore implements RateLimitStore {
     private config;
     private store;
+    private head?;
+    private tail?;
     private cleanupInterval;
     constructor(config: {
         maxRequests: number;
         windowMs: number;
     }, cleanupIntervalMs?: number);
+    private addNode;
+    private removeNode;
     increment(key: string): Promise<RateLimitState>;
     reset(key: string): Promise<void>;
     get(key: string): Promise<RateLimitState | null>;

package/dist/ripple/src/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;

package/dist/ripple/src/engines/UWebSocketsEngine.d.ts

@@ -0,0 +1,97 @@
+/**
+ * @fileoverview uWebSockets.js engine implementation for Node.js
+ *
+ * Wraps uWebSockets.js API to implement the IRippleEngine interface.
+ * This engine provides high performance on Node.js, close to Bun's native performance.
+ *
+ * @module @gravito/ripple/engines
+ * @since 5.0.0
+ */
+import type { ClientData } from '../types';
+import type { IRippleEngine, RippleSocket } from './IRippleEngine';
+interface WebSocket {
+    send(message: string | ArrayBuffer, isBinary?: boolean, compress?: boolean): number;
+    close(): void;
+    getBufferedAmount(): number;
+    subscribe(topic: string): void;
+    unsubscribe(topic: string): void;
+    publish(topic: string, message: string | ArrayBuffer, isBinary?: boolean, compress?: boolean): boolean;
+    getUserData(): ClientData;
+}
+/**
+ * Wrapper around uWebSockets.js WebSocket to implement RippleSocket interface.
+ *
+ * This is a zero-overhead wrapper that delegates all operations to the uWebSockets.js
+ * WebSocket object.
+ */
+export declare class UWebSocketsRippleSocket implements RippleSocket {
+    private ws;
+    constructor(ws: WebSocket);
+    get id(): string;
+    get data(): ClientData;
+    send(data: string | Uint8Array, compress?: boolean): void;
+    close(_code?: number, _reason?: string): void;
+    getBufferedAmount(): number;
+    subscribe(topic: string): void;
+    unsubscribe(topic: string): void;
+    publish(topic: string, data: string | Uint8Array): void;
+    get raw(): WebSocket;
+}
+/**
+ * Configuration for uWebSocketsEngine.
+ */
+export interface UWebSocketsEngineConfig {
+    /** Port to listen on */
+    port?: number;
+    /** Hostname to bind to */
+    hostname?: string;
+    /** TLS configuration */
+    tls?: {
+        cert: string;
+        key: string;
+    };
+    /** Compression mode (0 = disabled, 1 = shared, 3 = dedicated 3KB) */
+    compression?: number;
+    /** Maximum payload length in bytes (default: 16MB) */
+    maxPayloadLength?: number;
+    /** Idle timeout in seconds (default: 120) */
+    idleTimeout?: number;
+    /** Maximum backpressure in bytes (default: 1MB) */
+    maxBackpressure?: number;
+    /** Development mode (enables verbose logging) */
+    development?: boolean;
+}
+/**
+ * uWebSockets.js engine for Node.js.
+ *
+ * Leverages uWebSockets.js high-performance WebSocket implementation with native pub/sub support.
+ * This engine provides excellent performance on Node.js (~90% of Bun's performance).
+ */
+export declare class UWebSocketsEngine implements IRippleEngine {
+    private config;
+    readonly name = "node-uws";
+    private app?;
+    private uws?;
+    private connectionHandler?;
+    private disconnectionHandler?;
+    private messageHandler?;
+    private sockets;
+    private listenSocket?;
+    constructor(config?: UWebSocketsEngineConfig);
+    onConnection(handler: (socket: RippleSocket) => void): void;
+    onDisconnection(handler: (socket: RippleSocket, code: number, reason: string) => void): void;
+    onMessage(handler: (socket: RippleSocket, message: string | Uint8Array) => void): void;
+    listen(port: number): Promise<void>;
+    close(): Promise<void>;
+    broadcast(topic: string, data: string | Uint8Array, excludeSocketId?: string): void;
+    getConnectedSockets(): RippleSocket[];
+    getSocket(id: string): RippleSocket | undefined;
+    /**
+     * Upgrade an HTTP request to WebSocket.
+     *
+     * Note: This method is not used in the engine-based architecture.
+     * uWebSockets.js handles upgrades internally via the ws() route.
+     */
+    upgrade(_req: Request, _data?: Record<string, unknown>): boolean;
+}
+export {};

package/dist/ripple/src/engines/WsEngine.d.ts

@@ -0,0 +1,69 @@
+/**
+ * @fileoverview Node.js ws engine implementation
+ *
+ * Wraps the 'ws' library to implement the IRippleEngine interface.
+ * Implements in-memory pub/sub since the ws library does not support it natively.
+ *
+ * @module @gravito/ripple/engines
+ * @since 5.0.0
+ */
+import { type WebSocket } from 'ws';
+import type { ClientData } from '../types';
+import type { IRippleEngine, RippleSocket } from './IRippleEngine';
+/**
+ * Wrapper around 'ws' WebSocket to implement RippleSocket interface.
+ */
+export declare class WsRippleSocket implements RippleSocket {
+    private ws;
+    private clientData;
+    private engine;
+    constructor(ws: WebSocket, clientData: ClientData, engine: WsEngine);
+    get id(): string;
+    get data(): ClientData;
+    send(data: string | Uint8Array, compress?: boolean): void;
+    close(code?: number, reason?: string): void;
+    getBufferedAmount(): number;
+    subscribe(topic: string): void;
+    unsubscribe(topic: string): void;
+    publish(topic: string, data: string | Uint8Array): void;
+    get raw(): WebSocket;
+}
+/**
+ * Configuration for WsEngine.
+ */
+export interface WsEngineConfig {
+    /** Port to listen on */
+    port?: number;
+    /** Hostname to bind to */
+    hostname?: string;
+    /** Development mode */
+    development?: boolean;
+    /** WebSocket path */
+    path?: string;
+}
+/**
+ * Node.js ws engine.
+ *
+ * Uses the popular 'ws' library. Provides standard compatibility but
+ * uses application-layer pub/sub.
+ */
+export declare class WsEngine implements IRippleEngine {
+    private config;
+    readonly name = "node-ws";
+    private wss?;
+    private connectionHandler?;
+    private disconnectionHandler?;
+    private messageHandler?;
+    private sockets;
+    private subscriptions;
+    constructor(config?: WsEngineConfig);
+    onConnection(handler: (socket: RippleSocket) => void): void;
+    onDisconnection(handler: (socket: RippleSocket, code: number, reason: string) => void): void;
+    onMessage(handler: (socket: RippleSocket, message: string | Uint8Array) => void): void;
+    listen(port: number): Promise<void>;
+    close(): Promise<void>;
+    subscribe(socketId: string, topic: string): void;
+    unsubscribe(socketId: string, topic: string): void;
+    private cleanupSocket;
+    broadcast(topic: string, data: string | Uint8Array, excludeSocketId?: string): void;
+}

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

@@ -9,3 +9,7 @@
 export type { BunEngineConfig } from './BunEngine';
 export { BunEngine, BunRippleSocket } from './BunEngine';
 export type { EngineFactory, IRippleEngine, RippleSocket } from './IRippleEngine';
+export type { UWebSocketsEngineConfig } from './UWebSocketsEngine';
+export { UWebSocketsEngine, UWebSocketsRippleSocket } from './UWebSocketsEngine';
+export type { WsEngineConfig } from './WsEngine';
+export { WsEngine, WsRippleSocket } from './WsEngine';

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

@@ -21,7 +21,7 @@ export interface ISerializer {
      * @param data - The raw data received from the client
      * @returns Parsed ClientMessage object
      */
-    deserialize(data: string | Buffer | ArrayBuffer): ClientMessage;
+    deserialize(data: string | Buffer | ArrayBuffer | Uint8Array): ClientMessage;
     /**
      * Serialize message for broadcasting with caching optimization.
      *

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

@@ -12,7 +12,7 @@ export declare class JsonSerializer implements ISerializer {
     /** Cached serialized string for the current broadcast operation */
     private broadcastCache;
     serialize(message: ServerMessage): string;
-    deserialize(data: string | Buffer | ArrayBuffer): ClientMessage;
+    deserialize(data: string | Buffer | ArrayBuffer | Uint8Array): ClientMessage;
     serializeForBroadcast(message: ServerMessage): string;
     clearBroadcastCache(): void;
     getPongMessage(): string;

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

@@ -7,11 +7,14 @@ import type { ISerializer } from './ISerializer';
  * Requires 'protobufjs' to be installed.
  */
 export declare class ProtobufSerializer implements ISerializer {
-    private protoPath?;
+    private options;
     readonly contentType = "protobuf";
     private broadcastCache;
     private initialized;
-    constructor(protoPath?: string | undefined);
+    constructor(options?: {
+        protoPath?: string;
+        pure?: boolean;
+    });
     /**
      * Resolves the proto file path using a multi-level fallback strategy.
      *
@@ -26,7 +29,7 @@ export declare class ProtobufSerializer implements ISerializer {
      */
     init(): Promise<void>;
     serialize(message: ServerMessage): Uint8Array;
-    deserialize(data: string | Buffer | ArrayBuffer): ClientMessage;
+    deserialize(data: string | Buffer | ArrayBuffer | Uint8Array): ClientMessage;
     serializeForBroadcast(message: ServerMessage): Uint8Array;
     clearBroadcastCache(): void;
     getPongMessage(): Uint8Array;

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

@@ -34,6 +34,8 @@ export interface ClientData {
     reconnectionToken?: string;
     /** Session expiry timestamp (v3.6+) */
     sessionExpiry?: number;
+    /** Remote IP address (v5.0+) */
+    remoteAddress?: string;
 }
 /**
  * Supported WebSocket channel types.
@@ -769,6 +771,15 @@ export interface RippleConfig {
      *             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+).
      */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gravito/ripple",
-  "version": "4.0.0",
+  "version": "4.0.1",
   "description": "Bun-native WebSocket broadcasting for Gravito. Channel-based real-time communication.",
   "type": "module",
   "main": "./dist/index.cjs",
@@ -44,7 +44,7 @@
   },
   "homepage": "https://github.com/gravito-framework/gravito#readme",
   "peerDependencies": {
-    "@gravito/core": "workspace:*",
+    "@gravito/core": "^1.6.1",
     "ioredis": "^5.0.0",
     "nats": "^2.23.0",
     "protobufjs": "^8.0.0",
@@ -65,6 +65,7 @@
     }
   },
   "devDependencies": {
+    "@types/ws": "^8.18.1",
     "bun-types": "latest",
     "ioredis": "^5.4.2",
     "protobufjs": "^8.0.0",