@rvncom/socket-bun-engine 1.0.1 → 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/).
 
@@ -96,6 +97,50 @@ Default: `0` (unlimited)
 
 Maximum number of concurrent clients. New connections are rejected with HTTP 503 when the limit is reached.
 
+### `backpressureThreshold`
+
+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:
@@ -146,6 +191,68 @@ const engine = new Engine({
 });
 ```
 
+## Metrics
+
+Built-in server metrics with zero dependencies:
+
+```ts
+const snapshot = engine.metrics;
+// {
+//   connections: 150,        // total opened (cumulative)
+//   disconnections: 12,      // total closed
+//   activeConnections: 138,  // currently connected
+//   upgrades: 130,           // polling → websocket
+//   bytesReceived: 524288,
+//   bytesSent: 1048576,
+//   errors: 2,
+//   avgRtt: 14               // average round-trip time (ms)
+// }
+```
+
+Per-socket RTT is also available:
+
+```ts
+engine.on("connection", (socket) => {
+  socket.on("heartbeat", () => {
+    console.log(`RTT: ${socket.rtt}ms`);
+  });
+});
+```
+
+## API
+
+### `server.clientsCount`
+
+Number of currently connected clients.
+
+### `server.metrics`
+
+Returns a `MetricsSnapshot` object with server-wide counters.
+
+### `server.sockets`
+
+Iterator over all connected `Socket` instances.
+
+### `server.getSocket(id)`
+
+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.
+
 ## License
 
 [MIT](/LICENSE)

package/dist/index.d.ts

@@ -1,4 +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

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

package/dist/metrics.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Built-in server metrics — lightweight counters with zero external dependencies.
+ */
+export interface MetricsSnapshot {
+    connections: number;
+    disconnections: number;
+    activeConnections: number;
+    upgrades: number;
+    bytesReceived: number;
+    bytesSent: number;
+    errors: number;
+    avgRtt: number;
+}
+export declare class ServerMetrics {
+    connections: number;
+    disconnections: number;
+    upgrades: number;
+    bytesReceived: number;
+    bytesSent: number;
+    errors: number;
+    private rttSum;
+    private rttCount;
+    onConnection(): void;
+    onDisconnection(): void;
+    onUpgrade(): void;
+    onBytesReceived(bytes: number): void;
+    onBytesSent(bytes: number): void;
+    onError(): void;
+    onRtt(rtt: number): void;
+    snapshot(): MetricsSnapshot;
+}

package/dist/metrics.js

@@ -0,0 +1,47 @@
+/**
+ * Built-in server metrics — lightweight counters with zero external dependencies.
+ */
+export class ServerMetrics {
+    connections = 0;
+    disconnections = 0;
+    upgrades = 0;
+    bytesReceived = 0;
+    bytesSent = 0;
+    errors = 0;
+    rttSum = 0;
+    rttCount = 0;
+    onConnection() {
+        this.connections++;
+    }
+    onDisconnection() {
+        this.disconnections++;
+    }
+    onUpgrade() {
+        this.upgrades++;
+    }
+    onBytesReceived(bytes) {
+        this.bytesReceived += bytes;
+    }
+    onBytesSent(bytes) {
+        this.bytesSent += bytes;
+    }
+    onError() {
+        this.errors++;
+    }
+    onRtt(rtt) {
+        this.rttSum += rtt;
+        this.rttCount++;
+    }
+    snapshot() {
+        return {
+            connections: this.connections,
+            disconnections: this.disconnections,
+            activeConnections: this.connections - this.disconnections,
+            upgrades: this.upgrades,
+            bytesReceived: this.bytesReceived,
+            bytesSent: this.bytesSent,
+            errors: this.errors,
+            avgRtt: this.rttCount > 0 ? Math.round(this.rttSum / this.rttCount) : 0,
+        };
+    }
+}

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

@@ -3,6 +3,8 @@ import { Socket } from "./socket";
 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
@@ -34,6 +36,21 @@ export interface ServerOptions {
      * @default 0
      */
     maxClients: number;
+    /**
+     * WebSocket send buffer threshold in bytes for backpressure. Set to 0 to disable.
+     * @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.
@@ -58,14 +75,25 @@ 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.
+     */
+    get metrics(): MetricsSnapshot;
     constructor(opts?: Partial<ServerOptions>);
     /**
      * Handles an HTTP request.
@@ -103,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

@@ -5,6 +5,8 @@ import { WS, } from "./transports/websocket";
 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"];
@@ -28,9 +30,17 @@ const ERROR_MESSAGES = new Map([
 export class Server extends EventEmitter {
     opts;
     clients = new Map();
+    _metrics = new ServerMetrics();
+    _degraded = false;
     get clientsCount() {
         return this.clients.size;
     }
+    /**
+     * Returns a snapshot of server metrics.
+     */
+    get metrics() {
+        return this._metrics.snapshot();
+    }
     constructor(opts = {}) {
         super();
         this.opts = Object.assign({
@@ -40,6 +50,8 @@ export class Server extends EventEmitter {
             upgradeTimeout: 10000,
             maxHttpBufferSize: 1e6,
             maxClients: 0,
+            backpressureThreshold: 1_048_576,
+            degradationThreshold: 0,
         }, opts);
     }
     /**
@@ -67,6 +79,7 @@ export class Server extends EventEmitter {
         catch (err) {
             const { code, context } = err;
             const message = ERROR_MESSAGES.get(code);
+            this._metrics.onError();
             this.emitReserved("connection_error", {
                 req,
                 code,
@@ -236,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);
@@ -257,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()),
@@ -266,9 +299,32 @@ export class Server extends EventEmitter {
             },
         });
         this.clients.set(id, socket);
+        this._metrics.onConnection();
+        socket.on("data", (data) => {
+            this._metrics.onBytesReceived(typeof data === "string"
+                ? data.length
+                : data.byteLength);
+        });
+        socket.on("packetCreate", (packet) => {
+            if (packet.data != null) {
+                this._metrics.onBytesSent(typeof packet.data === "string"
+                    ? packet.data.length
+                    : packet.data.byteLength);
+            }
+        });
+        socket.on("heartbeat", () => {
+            if (socket.rtt > 0) {
+                this._metrics.onRtt(socket.rtt);
+            }
+        });
+        socket.on("upgrade", () => {
+            this._metrics.onUpgrade();
+        });
         socket.once("close", (reason) => {
             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);
@@ -290,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;
@@ -34,6 +35,9 @@ export declare class Socket extends EventEmitter<Record<never, never>, Record<ne
     private writeBuffer;
     private pingIntervalTimer?;
     private pingTimeoutTimer?;
+    private _pingSentAt;
+    private rateLimiter?;
+    rtt: number;
     constructor(id: string, opts: ServerOptions, transport: Transport, req: HandshakeRequestReference);
     /**
      * Called upon transport considered open.

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;
@@ -18,6 +19,9 @@ export class Socket extends EventEmitter {
      */
     pingIntervalTimer;
     pingTimeoutTimer;
+    _pingSentAt = 0;
+    rateLimiter;
+    rtt = 0;
     constructor(id, opts, transport, req) {
         super();
         this.id = id;
@@ -25,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();
     }
     /**
@@ -60,11 +67,20 @@ export class Socket extends EventEmitter {
         switch (packet.type) {
             case "pong":
                 debug("got pong");
+                if (this._pingSentAt > 0) {
+                    this.rtt = Date.now() - this._pingSentAt;
+                    this._pingSentAt = 0;
+                }
                 clearTimeout(this.pingTimeoutTimer);
                 this.schedulePing();
                 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":
@@ -96,6 +112,7 @@ export class Socket extends EventEmitter {
         }
         this.pingIntervalTimer = setTimeout(() => {
             debug(`writing ping packet - expecting pong within ${this.opts.pingTimeout} ms`);
+            this._pingSentAt = Date.now();
             this.sendPacket("ping");
             this.resetPingTimeout();
         }, this.opts.pingInterval);

package/dist/transports/websocket.js

@@ -11,19 +11,28 @@ export class WS extends Transport {
         return [];
     }
     send(packets) {
-        if (!this.writable || !this.socket || this.socket.readyState !== WebSocket.OPEN) {
+        if (!this.writable ||
+            !this.socket ||
+            this.socket.readyState !== WebSocket.OPEN) {
             return;
         }
+        const threshold = this.opts.backpressureThreshold;
         if (packets.length === 1) {
             this.socket.send(Parser.encodePacket(packets[0], true));
-            return;
         }
-        // Batch multiple packets into a single syscall via cork()
-        this.socket.cork(() => {
-            for (const packet of packets) {
-                this.socket.send(Parser.encodePacket(packet, true));
-            }
-        });
+        else {
+            // Batch multiple packets into a single syscall via cork()
+            this.socket.cork(() => {
+                for (const packet of packets) {
+                    this.socket.send(Parser.encodePacket(packet, true));
+                }
+            });
+        }
+        // Check backpressure after send
+        if (threshold > 0 && this.socket.getBufferedAmount() > threshold) {
+            debug("backpressure: buffer full after send, pausing writes");
+            this.writable = false;
+        }
     }
     doClose() {
         this.socket?.close();
@@ -35,6 +44,15 @@ export class WS extends Transport {
     }
     onMessage(message) {
         debug("on message");
+        // Resume writes if backpressure cleared (client consuming data)
+        if (!this.writable && this.socket) {
+            const threshold = this.opts.backpressureThreshold;
+            if (threshold > 0 && this.socket.getBufferedAmount() <= threshold) {
+                debug("backpressure: buffer drained, resuming writes");
+                this.writable = true;
+                this.emitReserved("drain");
+            }
+        }
         this.onPacket(Parser.decodePacket(message));
     }
     onCloseEvent(_code, _message) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rvncom/socket-bun-engine",
-  "version": "1.0.1",
+  "version": "1.0.3",
   "description": "Engine.IO server implementation for Bun runtime",
   "type": "module",
   "main": "./dist/index.js",
@@ -24,13 +24,13 @@
     "format:fix": "prettier --write \"lib/**/*.ts\" \"test/**/*.ts\""
   },
   "devDependencies": {
-    "@types/bun": "^1.3.0",
+    "@types/bun": "^1.3.10",
     "oxlint": "latest",
-    "prettier": "^3.6.2",
-    "socket.io": "^4.8.1"
+    "prettier": "^3.8.1",
+    "socket.io": "^4.8.3"
   },
   "peerDependencies": {
-    "typescript": "^5"
+    "typescript": "^5.9.2"
   },
   "license": "MIT",
   "homepage": "https://github.com/rvncom/socket-bun-engine#readme",