@rvncom/socket-bun-engine 1.0.0

package/dist/server.d.ts

@@ -0,0 +1,146 @@
+import { EventEmitter } from "./event-emitter";
+import { Socket } from "./socket";
+import { type BunWebSocket, type WebSocketData } from "./transports/websocket";
+import { type CorsOptions } from "./cors";
+import type { RawData } from "./parser";
+export interface ServerOptions {
+    /**
+     * Name of the request path to handle
+     * @default "/engine.io/"
+     */
+    path: string;
+    /**
+     * Duration in milliseconds without a pong packet to consider the connection closed
+     * @default 20000
+     */
+    pingTimeout: number;
+    /**
+     * Duration in milliseconds before sending a new ping packet
+     * @default 25000
+     */
+    pingInterval: number;
+    /**
+     * Duration in milliseconds before an uncompleted transport upgrade is cancelled
+     * @default 10000
+     */
+    upgradeTimeout: number;
+    /**
+     * Maximum size in bytes or number of characters a message can be, before closing the session (to avoid DoS).
+     * @default 1e6 (1 MB)
+     */
+    maxHttpBufferSize: number;
+    /**
+     * Maximum number of concurrent clients. Set to 0 for unlimited.
+     * @default 0
+     */
+    maxClients: number;
+    /**
+     * A function that receives a given handshake or upgrade request as its first parameter,
+     * and can decide whether to continue or not.
+     */
+    allowRequest?: (req: Request, server: Bun.Server<WebSocketData>) => Promise<void>;
+    /**
+     * The options related to Cross-Origin Resource Sharing (CORS)
+     */
+    cors?: CorsOptions;
+    /**
+     * A function that allows to edit the response headers of the handshake request
+     */
+    editHandshakeHeaders?: (responseHeaders: Headers, req: Request, server: Bun.Server<WebSocketData>) => void | Promise<void>;
+    /**
+     * A function that allows to edit the response headers of all requests
+     */
+    editResponseHeaders?: (responseHeaders: Headers, req: Request, server: Bun.Server<WebSocketData>) => void | Promise<void>;
+}
+interface ConnectionError {
+    req: Request;
+    code: number;
+    message: string;
+    context: Record<string, unknown>;
+}
+interface ServerReservedEvents {
+    connection: (socket: Socket, request: Request, server: Bun.Server<WebSocketData>) => void;
+    connection_error: (err: ConnectionError) => void;
+}
+export declare class Server extends EventEmitter<Record<never, never>, Record<never, never>, ServerReservedEvents> {
+    readonly opts: ServerOptions;
+    private clients;
+    get clientsCount(): number;
+    constructor(opts?: Partial<ServerOptions>);
+    /**
+     * Handles an HTTP request.
+     *
+     * @param req
+     * @param server
+     */
+    handleRequest(req: Request, server: Bun.Server<WebSocketData>): Promise<Response>;
+    onWebSocketOpen(ws: BunWebSocket): void;
+    onWebSocketMessage(ws: BunWebSocket, message: RawData): void;
+    onWebSocketClose(ws: BunWebSocket, code: number, message: string): void;
+    /**
+     * Verifies a request.
+     *
+     * @param req
+     * @param url
+     * @private
+     */
+    private verify;
+    /**
+     * Handshakes a new client.
+     *
+     * @param req
+     * @param server
+     * @param url
+     * @param responseHeaders
+     * @private
+     */
+    private handshake;
+    /**
+     * Closes all clients.
+     */
+    close(): void;
+    /**
+     * Creates a request handler.
+     *
+     * @example
+     * Bun.serve({
+     *   port: 3000,
+     *   ...engine.handler()
+     * });
+     *
+     * // expanded
+     * Bun.serve({
+     *   port: 3000,
+     *
+     *   fetch(req, server) {
+     *     return engine.handleRequest(req, server);
+     *   },
+     *
+     *   websocket: {
+     *     open(ws: BunWebSocket) {
+     *       engine.onWebSocketOpen(ws);
+     *     },
+     *
+     *     message(ws: BunWebSocket, message: RawData) {
+     *       engine.onWebSocketMessage(ws, message);
+     *     },
+     *
+     *     close(ws: BunWebSocket, code: number, message: string) {
+     *       engine.onWebSocketClose(ws, code, message);
+     *     },
+     *   },
+     * });
+     */
+    handler(): {
+        fetch: (req: Request, server: Bun.Server<WebSocketData>) => Response | Promise<Response>;
+        websocket: {
+            open: (ws: BunWebSocket) => void;
+            message: (ws: BunWebSocket, message: RawData) => void;
+            close: (ws: BunWebSocket, code: number, message: string) => void;
+            maxPayloadLength: number;
+        };
+        idleTimeout: number;
+        maxRequestBodySize: number;
+    };
+}
+export {};

package/dist/server.js

@@ -0,0 +1,348 @@
+import { EventEmitter } from "./event-emitter";
+import { Socket } from "./socket";
+import { Polling } from "./transports/polling";
+import { WS, } from "./transports/websocket";
+import { addCorsHeaders } from "./cors";
+import { Transport } from "./transport";
+import { generateId } from "./util";
+import { debuglog } from "node:util";
+const debug = debuglog("engine.io");
+const TRANSPORTS = ["polling", "websocket"];
+var ERROR_CODES;
+(function (ERROR_CODES) {
+    ERROR_CODES[ERROR_CODES["UNKNOWN_TRANSPORT"] = 0] = "UNKNOWN_TRANSPORT";
+    ERROR_CODES[ERROR_CODES["UNKNOWN_SID"] = 1] = "UNKNOWN_SID";
+    ERROR_CODES[ERROR_CODES["BAD_HANDSHAKE_METHOD"] = 2] = "BAD_HANDSHAKE_METHOD";
+    ERROR_CODES[ERROR_CODES["BAD_REQUEST"] = 3] = "BAD_REQUEST";
+    ERROR_CODES[ERROR_CODES["FORBIDDEN"] = 4] = "FORBIDDEN";
+    ERROR_CODES[ERROR_CODES["UNSUPPORTED_PROTOCOL_VERSION"] = 5] = "UNSUPPORTED_PROTOCOL_VERSION";
+})(ERROR_CODES || (ERROR_CODES = {}));
+const ERROR_MESSAGES = new Map([
+    [ERROR_CODES.UNKNOWN_TRANSPORT, "Transport unknown"],
+    [ERROR_CODES.UNKNOWN_SID, "Session ID unknown"],
+    [ERROR_CODES.BAD_HANDSHAKE_METHOD, "Bad handshake method"],
+    [ERROR_CODES.BAD_REQUEST, "Bad request"],
+    [ERROR_CODES.FORBIDDEN, "Forbidden"],
+    [ERROR_CODES.UNSUPPORTED_PROTOCOL_VERSION, "Unsupported protocol version"],
+]);
+export class Server extends EventEmitter {
+    opts;
+    clients = new Map();
+    get clientsCount() {
+        return this.clients.size;
+    }
+    constructor(opts = {}) {
+        super();
+        this.opts = Object.assign({
+            path: "/engine.io/",
+            pingTimeout: 20000,
+            pingInterval: 25000,
+            upgradeTimeout: 10000,
+            maxHttpBufferSize: 1e6,
+            maxClients: 0,
+        }, opts);
+    }
+    /**
+     * Handles an HTTP request.
+     *
+     * @param req
+     * @param server
+     */
+    async handleRequest(req, server) {
+        const url = new URL(req.url);
+        debug(`handling ${req.method} ${req.url}`);
+        const responseHeaders = new Headers();
+        if (this.opts.cors) {
+            addCorsHeaders(responseHeaders, this.opts.cors, req);
+            if (req.method === "OPTIONS") {
+                return new Response(null, { status: 204, headers: responseHeaders });
+            }
+        }
+        if (this.opts.editResponseHeaders) {
+            await this.opts.editResponseHeaders(responseHeaders, req, server);
+        }
+        try {
+            await this.verify(req, url);
+        }
+        catch (err) {
+            const { code, context } = err;
+            const message = ERROR_MESSAGES.get(code);
+            this.emitReserved("connection_error", {
+                req,
+                code,
+                message,
+                context,
+            });
+            const body = JSON.stringify({
+                code,
+                message,
+            });
+            responseHeaders.set("Content-Type", "application/json");
+            return new Response(body, {
+                status: 400,
+                headers: responseHeaders,
+            });
+        }
+        if (this.opts.allowRequest) {
+            try {
+                await this.opts.allowRequest(req, server);
+            }
+            catch (reason) {
+                this.emitReserved("connection_error", {
+                    req,
+                    code: ERROR_CODES.FORBIDDEN,
+                    message: ERROR_MESSAGES.get(ERROR_CODES.FORBIDDEN),
+                    context: {
+                        message: reason,
+                    },
+                });
+                const body = JSON.stringify({
+                    code: ERROR_CODES.FORBIDDEN,
+                    message: reason,
+                });
+                responseHeaders.set("Content-Type", "application/json");
+                return new Response(body, {
+                    status: 403,
+                    headers: responseHeaders,
+                });
+            }
+        }
+        const sid = url.searchParams.get("sid");
+        if (sid) {
+            // the client must exist since we have checked it in the verify method
+            const socket = this.clients.get(sid);
+            if (req.headers.has("upgrade")) {
+                const transport = new WS(this.opts);
+                const isSuccess = server.upgrade(req, {
+                    headers: responseHeaders,
+                    data: {
+                        transport,
+                    },
+                });
+                debug(`upgrade was successful: ${isSuccess}`);
+                if (!isSuccess) {
+                    return new Response(null, { status: 500 });
+                }
+                socket._maybeUpgrade(transport);
+                return new Response(null);
+            }
+            debug("setting new request for existing socket");
+            return socket.transport.onRequest(req, responseHeaders);
+        }
+        else {
+            return this.handshake(req, server, url, responseHeaders);
+        }
+    }
+    onWebSocketOpen(ws) {
+        debug("on ws open");
+        ws.data.transport.onOpen(ws);
+    }
+    onWebSocketMessage(ws, message) {
+        debug("on ws message");
+        ws.data.transport.onMessage(message);
+    }
+    onWebSocketClose(ws, code, message) {
+        debug("on ws close");
+        ws.data.transport.onCloseEvent(code, message);
+    }
+    /**
+     * Verifies a request.
+     *
+     * @param req
+     * @param url
+     * @private
+     */
+    verify(req, url) {
+        const transport = url.searchParams.get("transport") || "";
+        if (!TRANSPORTS.includes(transport)) {
+            debug(`unknown transport "${transport}"`);
+            return Promise.reject({
+                code: ERROR_CODES.UNKNOWN_TRANSPORT,
+                context: {
+                    transport,
+                },
+            });
+        }
+        const sid = url.searchParams.get("sid");
+        if (sid) {
+            const client = this.clients.get(sid);
+            if (!client) {
+                debug(`unknown client with sid ${sid}`);
+                return Promise.reject({
+                    code: ERROR_CODES.UNKNOWN_SID,
+                    context: {
+                        sid,
+                    },
+                });
+            }
+            const previousTransport = client.transport.name;
+            if (previousTransport === "websocket") {
+                debug("unexpected transport without upgrade");
+                return Promise.reject({
+                    code: ERROR_CODES.BAD_REQUEST,
+                    context: {
+                        name: "TRANSPORT_MISMATCH",
+                        transport,
+                        previousTransport,
+                    },
+                });
+            }
+        }
+        else {
+            // handshake is GET only
+            if (req.method !== "GET") {
+                return Promise.reject({
+                    code: ERROR_CODES.BAD_HANDSHAKE_METHOD,
+                    context: {
+                        method: req.method,
+                    },
+                });
+            }
+            const protocol = url.searchParams.get("EIO") === "4" ? 4 : 3; // 3rd revision by default
+            if (protocol === 3) {
+                return Promise.reject({
+                    code: ERROR_CODES.UNSUPPORTED_PROTOCOL_VERSION,
+                    context: {
+                        protocol,
+                    },
+                });
+            }
+        }
+        return Promise.resolve();
+    }
+    /**
+     * Handshakes a new client.
+     *
+     * @param req
+     * @param server
+     * @param url
+     * @param responseHeaders
+     * @private
+     */
+    async handshake(req, server, url, responseHeaders) {
+        if (this.opts.maxClients > 0 && this.clients.size >= this.opts.maxClients) {
+            this.emitReserved("connection_error", {
+                req,
+                code: ERROR_CODES.FORBIDDEN,
+                message: "Server capacity reached",
+                context: {
+                    maxClients: this.opts.maxClients,
+                },
+            });
+            responseHeaders.set("Content-Type", "application/json");
+            return new Response(JSON.stringify({
+                code: ERROR_CODES.FORBIDDEN,
+                message: "Server capacity reached",
+            }), { status: 503, headers: responseHeaders });
+        }
+        const id = generateId();
+        if (this.opts.editHandshakeHeaders) {
+            await this.opts.editHandshakeHeaders(responseHeaders, req, server);
+        }
+        let isUpgrade = req.headers.has("upgrade");
+        let transport;
+        if (isUpgrade) {
+            transport = new WS(this.opts);
+            const isSuccess = server.upgrade(req, {
+                headers: responseHeaders,
+                data: {
+                    transport: transport,
+                },
+            });
+            if (!isSuccess) {
+                return new Response(null, { status: 500 });
+            }
+        }
+        else {
+            transport = new Polling(this.opts);
+        }
+        debug(`new socket ${id}`);
+        const socket = new Socket(id, this.opts, transport, {
+            url: req.url,
+            headers: Object.fromEntries(req.headers.entries()),
+            _query: Object.fromEntries(url.searchParams.entries()),
+            connection: {
+                encrypted: ["https", "wss"].includes(url.protocol),
+            },
+        });
+        this.clients.set(id, socket);
+        socket.once("close", (reason) => {
+            debug(`socket ${id} closed due to ${reason}`);
+            this.clients.delete(id);
+        });
+        if (isUpgrade) {
+            this.emitReserved("connection", socket, req, server);
+            return new Response(null);
+        }
+        const promise = transport.onRequest(req, responseHeaders);
+        this.emitReserved("connection", socket, req, server);
+        return promise;
+    }
+    /**
+     * Closes all clients.
+     */
+    close() {
+        debug("closing all open clients");
+        this.clients.forEach((client) => client.close());
+    }
+    /**
+     * Creates a request handler.
+     *
+     * @example
+     * Bun.serve({
+     *   port: 3000,
+     *   ...engine.handler()
+     * });
+     *
+     * // expanded
+     * Bun.serve({
+     *   port: 3000,
+     *
+     *   fetch(req, server) {
+     *     return engine.handleRequest(req, server);
+     *   },
+     *
+     *   websocket: {
+     *     open(ws: BunWebSocket) {
+     *       engine.onWebSocketOpen(ws);
+     *     },
+     *
+     *     message(ws: BunWebSocket, message: RawData) {
+     *       engine.onWebSocketMessage(ws, message);
+     *     },
+     *
+     *     close(ws: BunWebSocket, code: number, message: string) {
+     *       engine.onWebSocketClose(ws, code, message);
+     *     },
+     *   },
+     * });
+     */
+    handler() {
+        const idleTimeoutInSeconds = Math.ceil((2 * this.opts.pingInterval) / 1000);
+        return {
+            fetch: (req, server) => {
+                const url = new URL(req.url);
+                if (url.pathname === this.opts.path) {
+                    return this.handleRequest(req, server);
+                }
+                else {
+                    return new Response(null, { status: 404 });
+                }
+            },
+            websocket: {
+                open: (ws) => {
+                    this.onWebSocketOpen(ws);
+                },
+                message: (ws, message) => {
+                    this.onWebSocketMessage(ws, message);
+                },
+                close: (ws, code, message) => {
+                    this.onWebSocketClose(ws, code, message);
+                },
+                maxPayloadLength: this.opts.maxHttpBufferSize,
+            },
+            idleTimeout: idleTimeoutInSeconds,
+            maxRequestBodySize: this.opts.maxHttpBufferSize,
+        };
+    }
+}

package/dist/socket.d.ts

@@ -0,0 +1,123 @@
+import { EventEmitter } from "./event-emitter";
+import { type Packet, type RawData } from "./parser";
+import { Transport } from "./transport";
+import { type ServerOptions } from "./server";
+type ReadyState = "opening" | "open" | "closing" | "closed";
+export interface HandshakeRequestReference {
+    url: string;
+    headers: Record<string, string>;
+    _query: Record<string, string>;
+    connection: {
+        encrypted: boolean;
+    };
+}
+export type CloseReason = "transport error" | "transport close" | "forced close" | "ping timeout" | "parse error";
+interface SocketEvents {
+    open: () => void;
+    packet: (packet: Packet) => void;
+    packetCreate: (packet: Packet) => void;
+    data: (data: RawData) => void;
+    flush: (writeBuffer: Packet[]) => void;
+    drain: () => void;
+    heartbeat: () => void;
+    upgrading: (transport: Transport) => void;
+    upgrade: (transport: Transport) => void;
+    close: (reason: CloseReason) => void;
+}
+export declare class Socket extends EventEmitter<Record<never, never>, Record<never, never>, SocketEvents> {
+    readonly id: string;
+    readyState: ReadyState;
+    transport: Transport;
+    readonly request: HandshakeRequestReference;
+    private readonly opts;
+    private upgradeState;
+    private writeBuffer;
+    private pingIntervalTimer?;
+    private pingTimeoutTimer?;
+    constructor(id: string, opts: ServerOptions, transport: Transport, req: HandshakeRequestReference);
+    /**
+     * Called upon transport considered open.
+     *
+     * @private
+     */
+    private onOpen;
+    /**
+     * Called upon transport packet.
+     *
+     * @param packet
+     * @private
+     */
+    private onPacket;
+    /**
+     * Called upon transport error.
+     *
+     * @param err
+     * @private
+     */
+    private onError;
+    /**
+     * Pings client every `pingInterval` and expects response
+     * within `pingTimeout` or closes connection.
+     *
+     * @private
+     */
+    private schedulePing;
+    /**
+     * Resets ping timeout.
+     *
+     * @private
+     */
+    private resetPingTimeout;
+    /**
+     * Attaches handlers for the given transport.
+     *
+     * @param transport
+     * @private
+     */
+    private bindTransport;
+    /**
+     * Upgrades socket to the given transport
+     *
+     * @param transport
+     * @private
+     */
+    _maybeUpgrade(transport: Transport): void;
+    /**
+     * Called upon transport considered closed.
+     *
+     * @param reason
+     * @private
+     */
+    private onClose;
+    /**
+     * Sends a "message" packet.
+     *
+     * @param data
+     */
+    write(data: RawData): Socket;
+    /**
+     * Sends a packet.
+     *
+     * @param type
+     * @param data
+     * @private
+     */
+    private sendPacket;
+    /**
+     * Attempts to flush the packets buffer.
+     *
+     * @private
+     */
+    private flush;
+    /**
+     * Closes the socket and underlying transport.
+     */
+    close(): void;
+    /**
+     * Closes the underlying transport.
+     *
+     * @private
+     */
+    private closeTransport;
+}
+export {};