@gravito/ripple 3.1.0 → 4.0.1

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

@@ -68,3 +68,22 @@ export * from './middleware/binary';
  * @public
  */
 export * from './middleware/htmx';
+/**
+ * Rate limiting middleware for Photon.
+ *
+ * Provides built-in rate limiting with token bucket and sliding window strategies.
+ * Supports both memory-based and custom storage backends.
+ *
+ * @public
+ */
+export * from './middleware/ratelimit';
+/**
+ * Redis-based rate limiting storage.
+ * @public
+ */
+export * from './middleware/ratelimit-redis';
+/**
+ * OpenAPI utilities
+ * @public
+ */
+export * from './openapi';

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

@@ -0,0 +1,161 @@
+/**
+ * @fileoverview Rate Limiting Middleware for Photon
+ *
+ * Provides token bucket and sliding window rate limiting strategies.
+ * Supports memory-based and Redis-based storage backends.
+ *
+ * @module @gravito/photon/middleware/ratelimit
+ * @since 1.0.0
+ */
+import type { Context, MiddlewareHandler } from '@gravito/photon';
+export interface RateLimitConfig {
+    /**
+     * Maximum number of requests allowed within the time window
+     * @default 100
+     */
+    maxRequests: number;
+    /**
+     * Time window in milliseconds
+     * @default 60000 (1 minute)
+     */
+    windowMs: number;
+    /**
+     * Strategy for rate limiting
+     * - 'token-bucket': Smooth rate limiting with token refill
+     * - 'sliding-window': Time-based window that slides continuously
+     * @default 'token-bucket'
+     */
+    strategy?: 'token-bucket' | 'sliding-window';
+    /**
+     * Custom key generator function
+     * @default (c) => c.req.header('x-forwarded-for') || c.req.header('x-real-ip') || 'unknown'
+     */
+    keyGenerator?: (c: Context) => string | Promise<string>;
+    /**
+     * Storage backend for rate limit state
+     * @default new MemoryStore()
+     */
+    store?: RateLimitStore;
+    /**
+     * Custom handler for rate-limited requests
+     * @default (c) => c.json({ error: 'Too Many Requests', retryAfter: <seconds> }, 429)
+     */
+    onRateLimitExceeded?: (c: Context, retryAfter: number) => Response | Promise<Response>;
+    /**
+     * Skip rate limiting for certain requests
+     * @default undefined
+     */
+    skip?: (c: Context) => boolean | Promise<boolean>;
+    /**
+     * Custom headers to include in responses
+     * @default true
+     */
+    standardHeaders?: boolean;
+    /**
+     * Include draft RateLimit headers (RateLimit-*)
+     * @default false
+     */
+    draftHeaders?: boolean;
+}
+export interface RateLimitStore {
+    /**
+     * Increment request count and return current state
+     */
+    increment(key: string): Promise<RateLimitState>;
+    /**
+     * Reset the rate limit for a key
+     */
+    reset(key: string): Promise<void>;
+    /**
+     * Get current state without incrementing
+     */
+    get(key: string): Promise<RateLimitState | null>;
+}
+export interface RateLimitState {
+    /**
+     * Number of requests made in current window
+     */
+    count: number;
+    /**
+     * Timestamp when the window expires (ms)
+     */
+    resetTime: number;
+    /**
+     * Remaining requests allowed
+     */
+    remaining: number;
+}
+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>;
+    /**
+     * Cleanup resources
+     */
+    destroy(): void;
+}
+/**
+ * Create a rate limiting middleware
+ *
+ * @example
+ * ```typescript
+ * import { Photon } from '@gravito/photon'
+ * import { rateLimit } from '@gravito/photon/middleware'
+ *
+ * const app = new Photon()
+ *
+ * // Basic usage: 100 requests per minute
+ * app.use('*', rateLimit({ maxRequests: 100, windowMs: 60000 }))
+ *
+ * // Per-user rate limiting
+ * app.use('/api/*', rateLimit({
+ *   maxRequests: 50,
+ *   windowMs: 60000,
+ *   keyGenerator: (c) => {
+ *     const userId = c.get('userId')
+ *     return userId || c.req.header('x-forwarded-for') || 'anonymous'
+ *   }
+ * }))
+ * ```
+ */
+export declare function rateLimit(config: RateLimitConfig): MiddlewareHandler;
+/**
+ * Convenience factory: Create rate limiter with common presets
+ */
+export declare const createRateLimiter: {
+    /**
+     * Strict: 10 requests per minute
+     */
+    strict: (overrides?: Partial<RateLimitConfig>) => MiddlewareHandler;
+    /**
+     * Moderate: 60 requests per minute
+     */
+    moderate: (overrides?: Partial<RateLimitConfig>) => MiddlewareHandler;
+    /**
+     * Lenient: 100 requests per minute
+     */
+    lenient: (overrides?: Partial<RateLimitConfig>) => MiddlewareHandler;
+    /**
+     * API: 1000 requests per hour
+     */
+    api: (overrides?: Partial<RateLimitConfig>) => MiddlewareHandler;
+    /**
+     * Auth: 5 attempts per 15 minutes (for login endpoints)
+     */
+    auth: (overrides?: Partial<RateLimitConfig>) => MiddlewareHandler;
+};
+/**
+ * Export convenience preset
+ */
+export { createRateLimiter as rateLimiter };

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

@@ -0,0 +1,19 @@
+/**
+ * @file packages/photon/src/openapi.ts
+ * @module @gravito/photon/openapi
+ * @description OpenAPI (Swagger) integration for Photon
+ */
+import type { RouteConfig } from '@hono/zod-openapi';
+import { createRoute, OpenAPIHono } from '@hono/zod-openapi';
+import { z } from 'zod';
+/**
+ * Photon Open API Class
+ * Extends OpenAPIHono to provide a seamless OpenAPI integration.
+ */
+export declare class PhotonOpenAPI extends OpenAPIHono {
+    /**
+     * Helper to create a fully typed route definition.
+     */
+    static route(config: RouteConfig): RouteConfig;
+}
+export { createRoute, z };

package/dist/proto/ripple.proto

@@ -0,0 +1,120 @@
+syntax = "proto3";
+
+package ripple;
+
+// -------------------------------------------------------------------
+// Client -> Server Messages
+// -------------------------------------------------------------------
+
+message ClientMessage {
+  string req_id = 1; // Optional request ID for troubleshooting
+
+  oneof payload {
+    SubscribeRequest subscribe = 10;
+    UnsubscribeRequest unsubscribe = 11;
+    WhisperRequest whisper = 12;
+    PingRequest ping = 13;
+    BinaryRequest binary = 14;
+    AckRequest ack = 15;
+  }
+}
+
+message SubscribeRequest {
+  string channel = 1;
+  optional AuthData auth = 2;
+}
+
+message UnsubscribeRequest {
+  string channel = 1;
+}
+
+message WhisperRequest {
+  string channel = 1;
+  string event = 2;
+  // Payload is generic bytes, application needs to decode based on event
+  bytes data = 3; 
+}
+
+message PingRequest {}
+
+message BinaryRequest {
+  string channel = 1;
+  string event = 2;
+  bytes data = 3;
+}
+
+message AckRequest {
+  int32 seq = 1;
+}
+
+message AuthData {
+  string socket_id = 1;
+  string signature = 2;
+}
+
+// -------------------------------------------------------------------
+// Server -> Client Messages
+// -------------------------------------------------------------------
+
+message ServerMessage {
+  oneof payload {
+    ConnectedResponse connected = 10;
+    SubscribedResponse subscribed = 11;
+    UnsubscribedResponse unsubscribed = 12;
+    ErrorResponse error = 13;
+    EventMessage event = 14;
+    PresenceMessage presence = 15;
+    PongResponse pong = 16;
+    BinaryMessage binary = 17;
+    AckReceivedResponse ack_received = 18;
+    ReconnectionTokenMessage reconnection_token = 19;
+  }
+}
+
+message ConnectedResponse {
+  string socket_id = 1;
+}
+
+message SubscribedResponse {
+  string channel = 1;
+}
+
+message UnsubscribedResponse {
+  string channel = 1;
+}
+
+message ErrorResponse {
+  string code = 1;
+  string message = 2;
+  optional string channel = 3;
+}
+
+message EventMessage {
+  string channel = 1;
+  string event = 2;
+  bytes data = 3; // JSON encoded string or raw bytes
+  optional int32 seq = 4;
+  optional bool need_ack = 5;
+}
+
+message PresenceMessage {
+  string channel = 1;
+  string event = 2; // "join", "leave", "members"
+  bytes data = 3;   // JSON encoded user info
+}
+
+message PongResponse {}
+
+message BinaryMessage {
+  string channel = 1;
+  string event = 2;
+  bytes data = 3;
+}
+
+message AckReceivedResponse {
+  int32 seq = 1;
+}
+
+message ReconnectionTokenMessage {
+  string token = 1;
+}