@rvncom/socket-bun-engine 1.0.0 → 1.0.2

package/README.md

@@ -1,5 +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 downloads](https://img.shields.io/npm/dm/@rvncom/socket-bun-engine.svg)](https://www.npmjs.com/package/@rvncom/socket-bun-engine)
+
 Engine.IO server implementation for the Bun runtime. Provides native WebSocket and HTTP long-polling transports for [Socket.IO](https://socket.io/).
 
 Fork of `@socket.io/bun-engine` with bug fixes, improved API, and active maintenance.
@@ -7,13 +10,13 @@ Fork of `@socket.io/bun-engine` with bug fixes, improved API, and active mainten
 ## Installation
 
 ```bash
-bun add @rvn/bun-engine
+bun add @rvncom/socket-bun-engine
 ```
 
 ## Usage
 
 ```ts
-import { Server as Engine } from "@rvn/bun-engine";
+import { Server as Engine } from "@rvncom/socket-bun-engine";
 import { Server } from "socket.io";
 
 const engine = new Engine({
@@ -93,6 +96,12 @@ 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.
+
 ### `allowRequest`
 
 A function that receives the handshake/upgrade request and can reject it:
@@ -143,6 +152,56 @@ 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.close()`
+
+Returns a `Promise<void>` that resolves when all clients have disconnected.
+
 ## License
 
 [MIT](/LICENSE)

package/dist/index.d.ts

@@ -1,3 +1,5 @@
 export { Server, type ServerOptions } 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";

package/dist/index.js

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

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/server.d.ts

@@ -3,6 +3,7 @@ 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";
 export interface ServerOptions {
     /**
      * Name of the request path to handle
@@ -34,6 +35,11 @@ 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;
     /**
      * A function that receives a given handshake or upgrade request as its first parameter,
      * and can decide whether to continue or not.
@@ -65,7 +71,12 @@ interface ServerReservedEvents {
 export declare class Server extends EventEmitter<Record<never, never>, Record<never, never>, ServerReservedEvents> {
     readonly opts: ServerOptions;
     private clients;
+    private _metrics;
     get clientsCount(): number;
+    /**
+     * Returns a snapshot of server metrics.
+     */
+    get metrics(): MetricsSnapshot;
     constructor(opts?: Partial<ServerOptions>);
     /**
      * Handles an HTTP request.
@@ -73,7 +84,7 @@ export declare class Server extends EventEmitter<Record<never, never>, Record<ne
      * @param req
      * @param server
      */
-    handleRequest(req: Request, server: Bun.Server<WebSocketData>): Promise<Response>;
+    handleRequest(req: Request, server: Bun.Server<WebSocketData>, _url?: URL): Promise<Response>;
     onWebSocketOpen(ws: BunWebSocket): void;
     onWebSocketMessage(ws: BunWebSocket, message: RawData): void;
     onWebSocketClose(ws: BunWebSocket, code: number, message: string): void;
@@ -96,9 +107,17 @@ export declare class Server extends EventEmitter<Record<never, never>, Record<ne
      */
     private handshake;
     /**
-     * Closes all clients.
+     * Returns an iterator over all connected sockets.
+     */
+    get sockets(): IterableIterator<Socket>;
+    /**
+     * Returns the socket with the given id, if any.
+     */
+    getSocket(id: string): Socket | undefined;
+    /**
+     * Closes all clients and returns a Promise that resolves when all are closed.
      */
-    close(): void;
+    close(): Promise<void>;
     /**
      * Creates a request handler.
      *

package/dist/server.js

@@ -5,6 +5,7 @@ import { WS, } from "./transports/websocket";
 import { addCorsHeaders } from "./cors";
 import { Transport } from "./transport";
 import { generateId } from "./util";
+import { ServerMetrics } from "./metrics";
 import { debuglog } from "node:util";
 const debug = debuglog("engine.io");
 const TRANSPORTS = ["polling", "websocket"];
@@ -28,9 +29,16 @@ const ERROR_MESSAGES = new Map([
 export class Server extends EventEmitter {
     opts;
     clients = new Map();
+    _metrics = new ServerMetrics();
     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 +48,7 @@ export class Server extends EventEmitter {
             upgradeTimeout: 10000,
             maxHttpBufferSize: 1e6,
             maxClients: 0,
+            backpressureThreshold: 1_048_576,
         }, opts);
     }
     /**
@@ -48,8 +57,8 @@ export class Server extends EventEmitter {
      * @param req
      * @param server
      */
-    async handleRequest(req, server) {
-        const url = new URL(req.url);
+    async handleRequest(req, server, _url) {
+        const url = _url ?? new URL(req.url);
         debug(`handling ${req.method} ${req.url}`);
         const responseHeaders = new Headers();
         if (this.opts.cors) {
@@ -67,6 +76,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,
@@ -266,9 +276,31 @@ 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();
         });
         if (isUpgrade) {
             this.emitReserved("connection", socket, req, server);
@@ -279,11 +311,37 @@ export class Server extends EventEmitter {
         return promise;
     }
     /**
-     * Closes all clients.
+     * Returns an iterator over all connected sockets.
+     */
+    get sockets() {
+        return this.clients.values();
+    }
+    /**
+     * Returns the socket with the given id, if any.
+     */
+    getSocket(id) {
+        return this.clients.get(id);
+    }
+    /**
+     * Closes all clients and returns a Promise that resolves when all are closed.
      */
     close() {
         debug("closing all open clients");
-        this.clients.forEach((client) => client.close());
+        if (this.clients.size === 0) {
+            return Promise.resolve();
+        }
+        return new Promise((resolve) => {
+            let remaining = this.clients.size;
+            const onClose = () => {
+                if (--remaining === 0) {
+                    resolve();
+                }
+            };
+            this.clients.forEach((client) => {
+                client.once("close", onClose);
+                client.close();
+            });
+        });
     }
     /**
      * Creates a request handler.
@@ -323,7 +381,7 @@ export class Server extends EventEmitter {
             fetch: (req, server) => {
                 const url = new URL(req.url);
                 if (url.pathname === this.opts.path) {
-                    return this.handleRequest(req, server);
+                    return this.handleRequest(req, server, url);
                 }
                 else {
                     return new Response(null, { status: 404 });

package/dist/socket.d.ts

@@ -34,6 +34,8 @@ export declare class Socket extends EventEmitter<Record<never, never>, Record<ne
     private writeBuffer;
     private pingIntervalTimer?;
     private pingTimeoutTimer?;
+    private _pingSentAt;
+    rtt: number;
     constructor(id: string, opts: ServerOptions, transport: Transport, req: HandshakeRequestReference);
     /**
      * Called upon transport considered open.

package/dist/socket.js

@@ -18,6 +18,8 @@ export class Socket extends EventEmitter {
      */
     pingIntervalTimer;
     pingTimeoutTimer;
+    _pingSentAt = 0;
+    rtt = 0;
     constructor(id, opts, transport, req) {
         super();
         this.id = id;
@@ -60,6 +62,10 @@ 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");
@@ -96,6 +102,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,12 +11,33 @@ export class WS extends Transport {
         return [];
     }
     send(packets) {
-        for (const packet of packets) {
-            const data = Parser.encodePacket(packet, true);
-            if (this.writable && this.socket?.readyState === WebSocket.OPEN) {
-                // TODO use ws.cork() once https://github.com/oven-sh/bun/issues/21588 is resolved
-                this.socket.send(data);
-            }
+        if (!this.writable ||
+            !this.socket ||
+            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));
+        }
+        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() {
@@ -29,6 +50,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.0",
+  "version": "1.0.2",
   "description": "Engine.IO server implementation for Bun runtime",
   "type": "module",
   "main": "./dist/index.js",
@@ -24,13 +24,18 @@
     "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"
+  "license": "MIT",
+  "homepage": "https://github.com/rvncom/socket-bun-engine#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/rvncom/socket-bun-engine.git"
+  }
 }