@rvncom/socket-bun-engine 1.0.2 → 1.0.3

package/README.md

@@ -1,7 +1,8 @@
 # @rvncom/socket-bun-engine
 
-[![npm version](https://img.shields.io/npm/v/@rvncom/socket-bun-engine.svg)](https://www.npmjs.com/package/@rvncom/socket-bun-engine)
+[![npm version](https://img.shields.io/npm/v/@rvncom/socket-bun-engine?style=flat-square&color=blue&label=version)](https://www.npmjs.com/package/@rvncom/socket-bun-engine)
 [![npm downloads](https://img.shields.io/npm/dm/@rvncom/socket-bun-engine.svg)](https://www.npmjs.com/package/@rvncom/socket-bun-engine)
+[![license](https://img.shields.io/npm/l/@rvncom/socket-bun-engine?style=flat-square&color=orange)](https://github.com/rvncom/socket-bun-engine/blob/main/LICENSE)
 
 Engine.IO server implementation for the Bun runtime. Provides native WebSocket and HTTP long-polling transports for [Socket.IO](https://socket.io/).
 
@@ -102,6 +103,44 @@ Default: `1048576` (1 MB)
 
 WebSocket send buffer threshold in bytes. When `getBufferedAmount()` exceeds this value, writes are paused automatically and resumed when the buffer drains. Set to `0` to disable.
 
+### `rateLimit`
+
+Per-socket message rate limiting. Disabled by default.
+
+```ts
+const engine = new Engine({
+  rateLimit: {
+    maxMessages: 100,   // max messages per window
+    windowMs: 1000,     // window duration in ms
+  },
+});
+
+engine.on("connection", (socket) => {
+  socket.on("rateLimited", () => {
+    console.log(`Socket ${socket.id} rate limited`);
+  });
+});
+```
+
+### `degradationThreshold`
+
+Default: `0` (disabled)
+
+Fraction (0–1) of `maxClients` at which graceful degradation activates. Requires `maxClients > 0`. When active:
+- New polling connections are rejected (WebSocket only, returns 503)
+- New connections get doubled `pingInterval` to reduce heartbeat overhead
+
+```ts
+const engine = new Engine({
+  maxClients: 10000,
+  degradationThreshold: 0.8, // degrade at 8000+ clients
+});
+
+engine.on("degradation", ({ active, clients }) => {
+  console.log(`Degradation ${active ? "ON" : "OFF"} at ${clients} clients`);
+});
+```
+
 ### `allowRequest`
 
 A function that receives the handshake/upgrade request and can reject it:
@@ -198,6 +237,18 @@ Iterator over all connected `Socket` instances.
 
 Look up a specific socket by session ID.
 
+### `server.broadcast(data)`
+
+Sends a message to all connected sockets.
+
+### `server.broadcastExcept(excludeId, data)`
+
+Sends a message to all connected sockets except the one with the given id.
+
+### `server.degraded`
+
+Returns `true` if the server is currently in degraded mode.
+
 ### `server.close()`
 
 Returns a `Promise<void>` that resolves when all clients have disconnected.

package/dist/index.d.ts

@@ -1,5 +1,6 @@
-export { Server, type ServerOptions } from "./server";
+export { Server, type ServerOptions, type DegradationEvent } from "./server";
 export { Socket, type CloseReason } from "./socket";
 export { type RawData } from "./parser";
 export { type BunWebSocket, type WebSocketData } from "./transports/websocket";
 export { type MetricsSnapshot } from "./metrics";
+export { type RateLimitOptions } from "./rate-limiter";

package/dist/index.js

@@ -3,3 +3,4 @@ export { Socket } from "./socket";
 export {} from "./parser";
 export {} from "./transports/websocket";
 export {} from "./metrics";
+export {} from "./rate-limiter";

package/dist/parser.d.ts

@@ -4,11 +4,9 @@ export interface Packet {
     type: PacketType;
     data?: RawData;
 }
-type BinaryType = "arraybuffer" | "blob";
 export declare const Parser: {
     encodePacket({ type, data }: Packet, supportsBinary: boolean): RawData;
-    decodePacket(encodedPacket: RawData, _binaryType?: BinaryType): Packet;
+    decodePacket(encodedPacket: RawData): Packet;
     encodePayload(packets: Packet[]): string;
-    decodePayload(encodedPayload: string, binaryType?: BinaryType): Packet[];
+    decodePayload(encodedPayload: string): Packet[];
 };
-export {};

package/dist/parser.js

@@ -23,7 +23,7 @@ export const Parser = {
             return PACKET_TYPES.get(type) + (data || "");
         }
     },
-    decodePacket(encodedPacket, _binaryType) {
+    decodePacket(encodedPacket) {
         if (typeof encodedPacket !== "string") {
             return {
                 type: "message",
@@ -58,11 +58,11 @@ export const Parser = {
         }
         return encodedPackets.join(SEPARATOR);
     },
-    decodePayload(encodedPayload, binaryType) {
+    decodePayload(encodedPayload) {
         const encodedPackets = encodedPayload.split(SEPARATOR);
         const packets = [];
         for (let i = 0; i < encodedPackets.length; i++) {
-            const decodedPacket = this.decodePacket(encodedPackets[i], binaryType);
+            const decodedPacket = this.decodePacket(encodedPackets[i]);
             packets.push(decodedPacket);
             if (decodedPacket.type === "error") {
                 break;

package/dist/rate-limiter.d.ts

@@ -0,0 +1,23 @@
+export interface RateLimitOptions {
+    /**
+     * Maximum number of messages allowed per window.
+     */
+    maxMessages: number;
+    /**
+     * Time window in milliseconds.
+     */
+    windowMs: number;
+}
+/**
+ * Simple token bucket rate limiter — no timers, lazy window reset.
+ */
+export declare class RateLimiter {
+    private remaining;
+    private windowStart;
+    private readonly opts;
+    constructor(opts: RateLimitOptions);
+    /**
+     * Attempt to consume one token. Returns `true` if allowed, `false` if rate limited.
+     */
+    consume(): boolean;
+}

package/dist/rate-limiter.js

@@ -0,0 +1,28 @@
+/**
+ * Simple token bucket rate limiter — no timers, lazy window reset.
+ */
+export class RateLimiter {
+    remaining;
+    windowStart;
+    opts;
+    constructor(opts) {
+        this.opts = opts;
+        this.remaining = opts.maxMessages;
+        this.windowStart = Date.now();
+    }
+    /**
+     * Attempt to consume one token. Returns `true` if allowed, `false` if rate limited.
+     */
+    consume() {
+        const now = Date.now();
+        if (now - this.windowStart >= this.opts.windowMs) {
+            this.windowStart = now;
+            this.remaining = this.opts.maxMessages;
+        }
+        if (this.remaining <= 0) {
+            return false;
+        }
+        this.remaining--;
+        return true;
+    }
+}

package/dist/server.d.ts

@@ -4,6 +4,7 @@ import { type BunWebSocket, type WebSocketData } from "./transports/websocket";
 import { type CorsOptions } from "./cors";
 import type { RawData } from "./parser";
 import { type MetricsSnapshot } from "./metrics";
+import { type RateLimitOptions } from "./rate-limiter";
 export interface ServerOptions {
     /**
      * Name of the request path to handle
@@ -40,6 +41,16 @@ export interface ServerOptions {
      * @default 1048576 (1 MB)
      */
     backpressureThreshold: number;
+    /**
+     * Per-socket message rate limiting. Disabled by default.
+     */
+    rateLimit?: RateLimitOptions;
+    /**
+     * Fraction (0–1) of maxClients at which graceful degradation activates.
+     * Requires maxClients > 0. Set to 0 to disable (default).
+     * @default 0
+     */
+    degradationThreshold: number;
     /**
      * A function that receives a given handshake or upgrade request as its first parameter,
      * and can decide whether to continue or not.
@@ -64,14 +75,20 @@ interface ConnectionError {
     message: string;
     context: Record<string, unknown>;
 }
+export interface DegradationEvent {
+    active: boolean;
+    clients: number;
+}
 interface ServerReservedEvents {
     connection: (socket: Socket, request: Request, server: Bun.Server<WebSocketData>) => void;
     connection_error: (err: ConnectionError) => void;
+    degradation: (event: DegradationEvent) => void;
 }
 export declare class Server extends EventEmitter<Record<never, never>, Record<never, never>, ServerReservedEvents> {
     readonly opts: ServerOptions;
     private clients;
     private _metrics;
+    private _degraded;
     get clientsCount(): number;
     /**
      * Returns a snapshot of server metrics.
@@ -114,6 +131,20 @@ export declare class Server extends EventEmitter<Record<never, never>, Record<ne
      * Returns the socket with the given id, if any.
      */
     getSocket(id: string): Socket | undefined;
+    /**
+     * Returns whether the server is currently in degraded mode.
+     */
+    get degraded(): boolean;
+    /**
+     * Sends a message to all connected sockets.
+     */
+    broadcast(data: RawData): void;
+    /**
+     * Sends a message to all connected sockets except the one with the given id.
+     */
+    broadcastExcept(excludeId: string, data: RawData): void;
+    private isDegraded;
+    private updateDegradationState;
     /**
      * Closes all clients and returns a Promise that resolves when all are closed.
      */

package/dist/server.js

@@ -6,6 +6,7 @@ import { addCorsHeaders } from "./cors";
 import { Transport } from "./transport";
 import { generateId } from "./util";
 import { ServerMetrics } from "./metrics";
+import {} from "./rate-limiter";
 import { debuglog } from "node:util";
 const debug = debuglog("engine.io");
 const TRANSPORTS = ["polling", "websocket"];
@@ -30,6 +31,7 @@ export class Server extends EventEmitter {
     opts;
     clients = new Map();
     _metrics = new ServerMetrics();
+    _degraded = false;
     get clientsCount() {
         return this.clients.size;
     }
@@ -49,6 +51,7 @@ export class Server extends EventEmitter {
             maxHttpBufferSize: 1e6,
             maxClients: 0,
             backpressureThreshold: 1_048_576,
+            degradationThreshold: 0,
         }, opts);
     }
     /**
@@ -246,10 +249,27 @@ export class Server extends EventEmitter {
             }), { status: 503, headers: responseHeaders });
         }
         const id = generateId();
+        // Graceful degradation check
+        const degraded = this.isDegraded();
+        this.updateDegradationState(degraded);
         if (this.opts.editHandshakeHeaders) {
             await this.opts.editHandshakeHeaders(responseHeaders, req, server);
         }
         let isUpgrade = req.headers.has("upgrade");
+        // Under degradation, reject new polling connections (WebSocket only)
+        if (degraded && !isUpgrade) {
+            this.emitReserved("connection_error", {
+                req,
+                code: ERROR_CODES.FORBIDDEN,
+                message: "Degraded mode: only WebSocket connections accepted",
+                context: { degraded: true },
+            });
+            responseHeaders.set("Content-Type", "application/json");
+            return new Response(JSON.stringify({
+                code: ERROR_CODES.FORBIDDEN,
+                message: "Degraded mode: only WebSocket connections accepted",
+            }), { status: 503, headers: responseHeaders });
+        }
         let transport;
         if (isUpgrade) {
             transport = new WS(this.opts);
@@ -267,7 +287,10 @@ export class Server extends EventEmitter {
             transport = new Polling(this.opts);
         }
         debug(`new socket ${id}`);
-        const socket = new Socket(id, this.opts, transport, {
+        const socketOpts = degraded
+            ? { ...this.opts, pingInterval: this.opts.pingInterval * 2 }
+            : this.opts;
+        const socket = new Socket(id, socketOpts, transport, {
             url: req.url,
             headers: Object.fromEntries(req.headers.entries()),
             _query: Object.fromEntries(url.searchParams.entries()),
@@ -301,6 +324,7 @@ export class Server extends EventEmitter {
             debug(`socket ${id} closed due to ${reason}`);
             this.clients.delete(id);
             this._metrics.onDisconnection();
+            this.updateDegradationState(this.isDegraded());
         });
         if (isUpgrade) {
             this.emitReserved("connection", socket, req, server);
@@ -322,6 +346,45 @@ export class Server extends EventEmitter {
     getSocket(id) {
         return this.clients.get(id);
     }
+    /**
+     * Returns whether the server is currently in degraded mode.
+     */
+    get degraded() {
+        return this._degraded;
+    }
+    /**
+     * Sends a message to all connected sockets.
+     */
+    broadcast(data) {
+        for (const socket of this.clients.values()) {
+            socket.write(data);
+        }
+    }
+    /**
+     * Sends a message to all connected sockets except the one with the given id.
+     */
+    broadcastExcept(excludeId, data) {
+        for (const [id, socket] of this.clients) {
+            if (id !== excludeId) {
+                socket.write(data);
+            }
+        }
+    }
+    isDegraded() {
+        const { degradationThreshold, maxClients } = this.opts;
+        if (degradationThreshold <= 0 || maxClients <= 0)
+            return false;
+        return this.clients.size / maxClients >= degradationThreshold;
+    }
+    updateDegradationState(degraded) {
+        if (degraded !== this._degraded) {
+            this._degraded = degraded;
+            this.emitReserved("degradation", {
+                active: degraded,
+                clients: this.clients.size,
+            });
+        }
+    }
     /**
      * Closes all clients and returns a Promise that resolves when all are closed.
      */

package/dist/socket.d.ts

@@ -23,6 +23,7 @@ interface SocketEvents {
     upgrading: (transport: Transport) => void;
     upgrade: (transport: Transport) => void;
     close: (reason: CloseReason) => void;
+    rateLimited: () => void;
 }
 export declare class Socket extends EventEmitter<Record<never, never>, Record<never, never>, SocketEvents> {
     readonly id: string;
@@ -35,6 +36,7 @@ export declare class Socket extends EventEmitter<Record<never, never>, Record<ne
     private pingIntervalTimer?;
     private pingTimeoutTimer?;
     private _pingSentAt;
+    private rateLimiter?;
     rtt: number;
     constructor(id: string, opts: ServerOptions, transport: Transport, req: HandshakeRequestReference);
     /**

package/dist/socket.js

@@ -2,6 +2,7 @@ import { EventEmitter } from "./event-emitter";
 import {} from "./parser";
 import { Transport, TransportError } from "./transport";
 import {} from "./server";
+import { RateLimiter } from "./rate-limiter";
 import { debuglog } from "node:util";
 const debug = debuglog("engine.io:socket");
 const FAST_UPGRADE_INTERVAL_MS = 100;
@@ -19,6 +20,7 @@ export class Socket extends EventEmitter {
     pingIntervalTimer;
     pingTimeoutTimer;
     _pingSentAt = 0;
+    rateLimiter;
     rtt = 0;
     constructor(id, opts, transport, req) {
         super();
@@ -27,6 +29,9 @@ export class Socket extends EventEmitter {
         this.transport = transport;
         this.bindTransport(transport);
         this.request = req;
+        if (opts.rateLimit) {
+            this.rateLimiter = new RateLimiter(opts.rateLimit);
+        }
         this.onOpen();
     }
     /**
@@ -71,6 +76,11 @@ export class Socket extends EventEmitter {
                 this.emitReserved("heartbeat");
                 break;
             case "message":
+                if (this.rateLimiter && !this.rateLimiter.consume()) {
+                    debug("message dropped: rate limited");
+                    this.emitReserved("rateLimited");
+                    break;
+                }
                 this.emitReserved("data", packet.data);
                 break;
             case "error":

package/dist/transports/websocket.js

@@ -16,13 +16,7 @@ export class WS extends Transport {
             this.socket.readyState !== WebSocket.OPEN) {
             return;
         }
-        // Backpressure: pause if send buffer is overloaded
         const threshold = this.opts.backpressureThreshold;
-        if (threshold > 0 && this.socket.getBufferedAmount() > threshold) {
-            debug("backpressure: send buffer exceeded threshold, pausing writes");
-            this.writable = false;
-            return;
-        }
         if (packets.length === 1) {
             this.socket.send(Parser.encodePacket(packets[0], true));
         }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rvncom/socket-bun-engine",
-  "version": "1.0.2",
+  "version": "1.0.3",
   "description": "Engine.IO server implementation for Bun runtime",
   "type": "module",
   "main": "./dist/index.js",