@rvncom/socket-bun-engine 1.0.0

package/dist/socket.js

@@ -0,0 +1,281 @@
+import { EventEmitter } from "./event-emitter";
+import {} from "./parser";
+import { Transport, TransportError } from "./transport";
+import {} from "./server";
+import { debuglog } from "node:util";
+const debug = debuglog("engine.io:socket");
+const FAST_UPGRADE_INTERVAL_MS = 100;
+export class Socket extends EventEmitter {
+    id;
+    readyState = "opening";
+    transport;
+    request;
+    opts;
+    upgradeState = "not_upgraded";
+    writeBuffer = [];
+    /*
+     * Note: using a single timer for all sockets seems to result in a higher CPU consumption than using one timer for each socket
+     */
+    pingIntervalTimer;
+    pingTimeoutTimer;
+    constructor(id, opts, transport, req) {
+        super();
+        this.id = id;
+        this.opts = opts;
+        this.transport = transport;
+        this.bindTransport(transport);
+        this.request = req;
+        this.onOpen();
+    }
+    /**
+     * Called upon transport considered open.
+     *
+     * @private
+     */
+    onOpen() {
+        this.readyState = "open";
+        this.sendPacket("open", JSON.stringify({
+            sid: this.id,
+            upgrades: this.transport.upgradesTo,
+            pingInterval: this.opts.pingInterval,
+            pingTimeout: this.opts.pingTimeout,
+            maxPayload: this.opts.maxHttpBufferSize,
+        }));
+        this.emitReserved("open");
+        this.schedulePing();
+    }
+    /**
+     * Called upon transport packet.
+     *
+     * @param packet
+     * @private
+     */
+    onPacket(packet) {
+        if (this.readyState !== "open") {
+            debug("packet received with closed socket");
+            return;
+        }
+        debug(`received packet ${packet.type}`);
+        this.emitReserved("packet", packet);
+        switch (packet.type) {
+            case "pong":
+                debug("got pong");
+                clearTimeout(this.pingTimeoutTimer);
+                this.schedulePing();
+                this.emitReserved("heartbeat");
+                break;
+            case "message":
+                this.emitReserved("data", packet.data);
+                break;
+            case "error":
+            default:
+                this.onClose("parse error");
+                break;
+        }
+    }
+    /**
+     * Called upon transport error.
+     *
+     * @param err
+     * @private
+     */
+    onError(err) {
+        debug(`transport error: ${err.message}`);
+        this.onClose("transport error");
+    }
+    /**
+     * Pings client every `pingInterval` and expects response
+     * within `pingTimeout` or closes connection.
+     *
+     * @private
+     */
+    schedulePing() {
+        if (this.pingTimeoutTimer) {
+            this.pingIntervalTimer?.refresh();
+            return;
+        }
+        this.pingIntervalTimer = setTimeout(() => {
+            debug(`writing ping packet - expecting pong within ${this.opts.pingTimeout} ms`);
+            this.sendPacket("ping");
+            this.resetPingTimeout();
+        }, this.opts.pingInterval);
+    }
+    /**
+     * Resets ping timeout.
+     *
+     * @private
+     */
+    resetPingTimeout() {
+        clearTimeout(this.pingTimeoutTimer);
+        this.pingTimeoutTimer = setTimeout(() => {
+            this.onClose("ping timeout");
+        }, this.opts.pingTimeout);
+    }
+    /**
+     * Attaches handlers for the given transport.
+     *
+     * @param transport
+     * @private
+     */
+    bindTransport(transport) {
+        this.transport = transport;
+        this.transport.once("error", (err) => this.onError(err));
+        this.transport.on("packet", (packet) => this.onPacket(packet));
+        this.transport.on("drain", () => this.flush());
+        this.transport.on("close", () => this.onClose("transport close"));
+    }
+    /**
+     * Upgrades socket to the given transport
+     *
+     * @param transport
+     * @private
+     */
+    /* private */ _maybeUpgrade(transport) {
+        if (this.upgradeState === "upgrading") {
+            debug("transport has already been trying to upgrade");
+            return transport.close();
+        }
+        else if (this.upgradeState === "upgraded") {
+            debug("transport has already been upgraded");
+            return transport.close();
+        }
+        debug("upgrading existing transport");
+        this.upgradeState = "upgrading";
+        const timeoutId = setTimeout(() => {
+            debug("client did not complete upgrade - closing transport");
+            transport.close();
+        }, this.opts.upgradeTimeout);
+        let fastUpgradeTimerId;
+        transport.on("close", () => {
+            clearInterval(fastUpgradeTimerId);
+            transport.off();
+        });
+        // we need to make sure that no packets gets lost during the upgrade, so the client does not cancel the HTTP
+        // long-polling request itself, instead the server sends a "noop" packet to cleanly end any ongoing polling request
+        const sendNoopPacket = () => {
+            if (this.transport.name === "polling" && this.transport.writable) {
+                debug("writing a noop packet to polling for fast upgrade");
+                this.transport.send([{ type: "noop" }]);
+            }
+        };
+        transport.on("packet", (packet) => {
+            if (packet.type === "ping" && packet.data === "probe") {
+                debug("got probe ping packet, sending pong");
+                transport.send([{ type: "pong", data: "probe" }]);
+                sendNoopPacket();
+                fastUpgradeTimerId = setInterval(sendNoopPacket, FAST_UPGRADE_INTERVAL_MS);
+                this.emitReserved("upgrading", transport);
+            }
+            else if (packet.type === "upgrade" && this.readyState !== "closed") {
+                debug("got upgrade packet - upgrading");
+                this.upgradeState = "upgraded";
+                clearTimeout(timeoutId);
+                clearInterval(fastUpgradeTimerId);
+                transport.off();
+                this.closeTransport();
+                this.bindTransport(transport);
+                this.emitReserved("upgrade", transport);
+                this.flush();
+            }
+            else {
+                debug("invalid upgrade packet");
+                clearTimeout(timeoutId);
+                transport.close();
+            }
+        });
+    }
+    /**
+     * Called upon transport considered closed.
+     *
+     * @param reason
+     * @private
+     */
+    onClose(reason) {
+        if (this.readyState === "closed") {
+            return;
+        }
+        debug(`socket closed due to ${reason}`);
+        this.readyState = "closed";
+        clearTimeout(this.pingIntervalTimer);
+        clearTimeout(this.pingTimeoutTimer);
+        this.closeTransport();
+        this.emitReserved("close", reason);
+    }
+    /**
+     * Sends a "message" packet.
+     *
+     * @param data
+     */
+    write(data) {
+        this.sendPacket("message", data);
+        return this;
+    }
+    /**
+     * Sends a packet.
+     *
+     * @param type
+     * @param data
+     * @private
+     */
+    sendPacket(type, data) {
+        if (["closing", "closed"].includes(this.readyState)) {
+            return;
+        }
+        debug(`sending packet ${type} (${data})`);
+        const packet = {
+            type,
+            data,
+        };
+        this.emitReserved("packetCreate", packet);
+        this.writeBuffer.push(packet);
+        this.flush();
+    }
+    /**
+     * Attempts to flush the packets buffer.
+     *
+     * @private
+     */
+    flush() {
+        const shouldFlush = this.readyState !== "closed" &&
+            this.transport.writable &&
+            this.writeBuffer.length > 0;
+        if (!shouldFlush) {
+            return;
+        }
+        debug(`[socket] flushing buffer with ${this.writeBuffer.length} packet(s) to transport`);
+        this.emitReserved("flush", this.writeBuffer);
+        const buffer = this.writeBuffer;
+        this.writeBuffer = [];
+        this.transport.send(buffer);
+        this.emitReserved("drain");
+    }
+    /**
+     * Closes the socket and underlying transport.
+     */
+    close() {
+        if (this.readyState !== "open") {
+            return;
+        }
+        this.readyState = "closing";
+        const close = () => {
+            this.closeTransport();
+            this.onClose("forced close");
+        };
+        if (this.writeBuffer.length) {
+            debug(`buffer not empty, waiting for the drain event`);
+            this.once("drain", close);
+        }
+        else {
+            close();
+        }
+    }
+    /**
+     * Closes the underlying transport.
+     *
+     * @private
+     */
+    closeTransport() {
+        this.transport.off();
+        this.transport.close();
+    }
+}

package/dist/transport.d.ts

@@ -0,0 +1,64 @@
+import { EventEmitter } from "./event-emitter";
+import { type Packet } from "./parser";
+import { type ServerOptions } from "./server";
+interface TransportEvents {
+    packet: (packet: Packet) => void;
+    error: (error: TransportError) => void;
+    drain: () => void;
+    close: () => void;
+}
+type ReadyState = "open" | "closing" | "closed";
+export declare abstract class Transport extends EventEmitter<Record<never, never>, Record<never, never>, TransportEvents> {
+    writable: boolean;
+    protected readyState: ReadyState;
+    protected readonly opts: ServerOptions;
+    constructor(opts: ServerOptions);
+    /**
+     * The name of the transport
+     */
+    abstract get name(): string;
+    /**
+     * The list of transports to upgrade to
+     */
+    abstract get upgradesTo(): string[];
+    /**
+     * Writes an array of packets.
+     *
+     * @param packets
+     */
+    abstract send(packets: Packet[]): void;
+    /**
+     * Closes the transport.
+     *
+     * @protected
+     */
+    protected abstract doClose(): void;
+    /**
+     * Manually closes the transport.
+     */
+    close(): void;
+    /**
+     * Called when the transport encounters a fatal error.
+     *
+     * @param message
+     * @protected
+     */
+    protected onError(message: string): void;
+    /**
+     * Called with a parsed packet from the data stream.
+     *
+     * @param packet
+     * @protected
+     */
+    protected onPacket(packet: Packet): void;
+    /**
+     * Called upon transport close.
+     *
+     * @protected
+     */
+    protected onClose(): void;
+}
+export declare class TransportError extends Error {
+    readonly type = "TransportError";
+}
+export {};

package/dist/transport.js

@@ -0,0 +1,59 @@
+import { EventEmitter } from "./event-emitter";
+import {} from "./parser";
+import {} from "./server";
+import { debuglog } from "node:util";
+const debug = debuglog("engine.io:transport");
+export class Transport extends EventEmitter {
+    writable = false;
+    readyState = "open";
+    opts;
+    constructor(opts) {
+        super();
+        this.opts = opts;
+    }
+    /**
+     * Manually closes the transport.
+     */
+    close() {
+        if (["closing", "closed"].includes(this.readyState)) {
+            return;
+        }
+        debug("closing transport");
+        this.readyState = "closing";
+        this.doClose();
+    }
+    /**
+     * Called when the transport encounters a fatal error.
+     *
+     * @param message
+     * @protected
+     */
+    onError(message) {
+        this.emitReserved("error", new TransportError(message));
+    }
+    /**
+     * Called with a parsed packet from the data stream.
+     *
+     * @param packet
+     * @protected
+     */
+    onPacket(packet) {
+        if (packet.type === "close") {
+            debug("received 'close' packet");
+            return this.doClose();
+        }
+        this.emitReserved("packet", packet);
+    }
+    /**
+     * Called upon transport close.
+     *
+     * @protected
+     */
+    onClose() {
+        this.readyState = "closed";
+        this.emitReserved("close");
+    }
+}
+export class TransportError extends Error {
+    type = "TransportError";
+}

package/dist/transports/polling.d.ts

@@ -0,0 +1,32 @@
+import { Transport } from "../transport";
+import { type Packet } from "../parser";
+export declare class Polling extends Transport {
+    private pollingPromise?;
+    get name(): string;
+    get upgradesTo(): string[];
+    onRequest(req: Request, responseHeaders: Headers): Promise<Response>;
+    /**
+     * The client sends a long-polling request awaiting the server to send data.
+     *
+     * @param req
+     * @param responseHeaders
+     * @private
+     */
+    private onPollRequest;
+    /**
+     * The client sends a request with data.
+     *
+     * @param req
+     * @param responseHeaders
+     */
+    private onDataRequest;
+    send(packets: Packet[]): void;
+    /**
+     * Writes data as response to long-polling request
+     *
+     * @param data
+     * @private
+     */
+    private write;
+    protected doClose(): void;
+}

package/dist/transports/polling.js

@@ -0,0 +1,113 @@
+import { Transport } from "../transport";
+import { Parser } from "../parser";
+import { debuglog } from "node:util";
+const debug = debuglog("engine.io:polling");
+export class Polling extends Transport {
+    pollingPromise;
+    get name() {
+        return "polling";
+    }
+    get upgradesTo() {
+        return ["websocket"];
+    }
+    onRequest(req, responseHeaders) {
+        if (req.method === "GET") {
+            return this.onPollRequest(req, responseHeaders);
+        }
+        else if (req.method === "POST") {
+            return this.onDataRequest(req, responseHeaders);
+        }
+        return Promise.resolve(new Response(null, { status: 400, headers: responseHeaders }));
+    }
+    /**
+     * The client sends a long-polling request awaiting the server to send data.
+     *
+     * @param req
+     * @param responseHeaders
+     * @private
+     */
+    onPollRequest(req, responseHeaders) {
+        if (this.pollingPromise) {
+            debug("request overlap");
+            this.onError("overlap from client");
+            return Promise.resolve(new Response(null, { status: 400, headers: responseHeaders }));
+        }
+        debug("new polling request");
+        return new Promise((resolve, reject) => {
+            this.pollingPromise = { resolve, reject, responseHeaders };
+            req.signal.addEventListener("abort", () => {
+                if (this.pollingPromise) {
+                    this.pollingPromise = undefined;
+                    this.writable = false;
+                }
+                this.onError("polling request aborted");
+            });
+            debug("transport is now writable");
+            this.writable = true;
+            this.emitReserved("drain");
+        });
+    }
+    /**
+     * The client sends a request with data.
+     *
+     * @param req
+     * @param responseHeaders
+     */
+    async onDataRequest(req, responseHeaders) {
+        debug("new data request");
+        req.signal.addEventListener("abort", () => {
+            this.onError("data request aborted");
+        });
+        const contentLength = req.headers.get("content-length");
+        if (contentLength &&
+            parseInt(contentLength, 10) > this.opts.maxHttpBufferSize) {
+            this.onError("payload too large");
+            return new Response(null, { status: 413, headers: responseHeaders });
+        }
+        const data = await req.text();
+        if (data.length > this.opts.maxHttpBufferSize) {
+            this.onError("payload too large");
+            return Promise.resolve(new Response(null, { status: 413, headers: responseHeaders }));
+        }
+        const packets = Parser.decodePayload(data);
+        debug(`decoded ${packets.length} packet(s)`);
+        for (const packet of packets) {
+            this.onPacket(packet);
+        }
+        return Promise.resolve(new Response("ok", {
+            status: 200,
+            headers: responseHeaders,
+        }));
+    }
+    send(packets) {
+        this.writable = false;
+        this.write(Parser.encodePayload(packets));
+    }
+    /**
+     * Writes data as response to long-polling request
+     *
+     * @param data
+     * @private
+     */
+    write(data) {
+        debug(`writing ${data}`);
+        if (!this.pollingPromise) {
+            return;
+        }
+        const headers = this.pollingPromise.responseHeaders;
+        headers.set("Content-Type", "text/plain; charset=UTF-8");
+        this.pollingPromise.resolve(new Response(data, {
+            status: 200,
+            headers,
+        }));
+        this.pollingPromise = undefined;
+    }
+    doClose() {
+        if (this.writable) {
+            debug("transport writable - closing right away");
+            // if we have received a "close" packet from the client, then we can just send a "noop" packet back
+            this.send([{ type: this.readyState === "closing" ? "close" : "noop" }]);
+        }
+        this.onClose();
+    }
+}

package/dist/transports/websocket.d.ts

@@ -0,0 +1,16 @@
+import { Transport } from "../transport";
+import { type Packet, type RawData } from "../parser";
+export type WebSocketData = {
+    transport: WS;
+};
+export type BunWebSocket = Bun.ServerWebSocket<WebSocketData>;
+export declare class WS extends Transport {
+    private socket?;
+    get name(): string;
+    get upgradesTo(): string[];
+    send(packets: Packet[]): void;
+    protected doClose(): void;
+    onOpen(socket: BunWebSocket): void;
+    onMessage(message: RawData): void;
+    onCloseEvent(_code: number, _message: string): void;
+}

package/dist/transports/websocket.js

@@ -0,0 +1,38 @@
+import { Transport } from "../transport";
+import { Parser } from "../parser";
+import { debuglog } from "node:util";
+const debug = debuglog("engine.io:websocket");
+export class WS extends Transport {
+    socket;
+    get name() {
+        return "websocket";
+    }
+    get upgradesTo() {
+        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);
+            }
+        }
+    }
+    doClose() {
+        this.socket?.close();
+    }
+    onOpen(socket) {
+        debug("on open");
+        this.socket = socket;
+        this.writable = true;
+    }
+    onMessage(message) {
+        debug("on message");
+        this.onPacket(Parser.decodePacket(message));
+    }
+    onCloseEvent(_code, _message) {
+        debug("on close");
+        this.onClose();
+    }
+}

package/dist/util.d.ts

@@ -0,0 +1 @@
+export declare function generateId(): string;

package/dist/util.js

@@ -0,0 +1,4 @@
+import { randomBytes } from "node:crypto";
+export function generateId() {
+    return randomBytes(15).toString("base64url");
+}

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "@rvncom/socket-bun-engine",
+  "version": "1.0.0",
+  "description": "Engine.IO server implementation for Bun runtime",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist/"
+  ],
+  "engines": {
+    "bun": ">=1.0.0"
+  },
+  "scripts": {
+    "compile": "rm -rf ./dist && tsc",
+    "lint": "oxlint",
+    "format:check": "prettier --check \"lib/**/*.ts\" \"test/**/*.ts\"",
+    "format:fix": "prettier --write \"lib/**/*.ts\" \"test/**/*.ts\""
+  },
+  "devDependencies": {
+    "@types/bun": "^1.3.0",
+    "oxlint": "latest",
+    "prettier": "^3.6.2",
+    "socket.io": "^4.8.1"
+  },
+  "peerDependencies": {
+    "typescript": "^5"
+  },
+  "license": "MIT"
+}