@rvncom/socket-bun-engine 1.0.0

package/LICENSE

@@ -0,0 +1,22 @@
+The MIT License (MIT)
+
+Copyright (c) 2025-present Guillermo Rauch and Socket.IO contributors
+Copyright (c) 2026 RVNcom
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,148 @@
+# @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.
+
+## Installation
+
+```bash
+bun add @rvn/bun-engine
+```
+
+## Usage
+
+```ts
+import { Server as Engine } from "@rvn/bun-engine";
+import { Server } from "socket.io";
+
+const engine = new Engine({
+  path: "/socket.io/",
+});
+
+const io = new Server();
+io.bind(engine);
+
+io.on("connection", (socket) => {
+  // ...
+});
+
+export default {
+  port: 3000,
+  ...engine.handler(),
+};
+```
+
+You can also use `engine.handleRequest()` directly for custom routing:
+
+```ts
+Bun.serve({
+  port: 3000,
+
+  fetch(req, server) {
+    const url = new URL(req.url);
+
+    if (url.pathname === "/health") {
+      return new Response(JSON.stringify({ status: "ok", connections: engine.clientsCount }), {
+        headers: { "Content-Type": "application/json" },
+      });
+    }
+
+    return engine.handleRequest(req, server);
+  },
+
+  websocket: engine.handler().websocket,
+});
+```
+
+## Options
+
+### `path`
+
+Default: `/engine.io/`
+
+The path to handle on the server side. Must match the client configuration.
+
+### `pingTimeout`
+
+Default: `20000`
+
+Milliseconds without a pong packet before considering the connection closed.
+
+### `pingInterval`
+
+Default: `25000`
+
+Milliseconds between ping packets sent by the server.
+
+### `upgradeTimeout`
+
+Default: `10000`
+
+Milliseconds before an uncompleted transport upgrade is cancelled.
+
+### `maxHttpBufferSize`
+
+Default: `1e6` (1 MB)
+
+Maximum message size in bytes before closing the session.
+
+### `maxClients`
+
+Default: `0` (unlimited)
+
+Maximum number of concurrent clients. New connections are rejected with HTTP 503 when the limit is reached.
+
+### `allowRequest`
+
+A function that receives the handshake/upgrade request and can reject it:
+
+```ts
+const engine = new Engine({
+  allowRequest: (req, server) => {
+    return Promise.reject("not allowed");
+  },
+});
+```
+
+### `cors`
+
+Cross-Origin Resource Sharing options:
+
+```ts
+const engine = new Engine({
+  cors: {
+    origin: ["https://example.com"],
+    allowedHeaders: ["my-header"],
+    credentials: true,
+  },
+});
+```
+
+### `editHandshakeHeaders`
+
+Edit response headers for the handshake request:
+
+```ts
+const engine = new Engine({
+  editHandshakeHeaders: (responseHeaders, req, server) => {
+    responseHeaders.set("set-cookie", "sid=1234");
+  },
+});
+```
+
+### `editResponseHeaders`
+
+Edit response headers for all requests:
+
+```ts
+const engine = new Engine({
+  editResponseHeaders: (responseHeaders, req, server) => {
+    responseHeaders.set("my-header", "abcd");
+  },
+});
+```
+
+## License
+
+[MIT](/LICENSE)

package/dist/cors.d.ts

@@ -0,0 +1,11 @@
+type OriginOption = boolean | string | RegExp | (string | RegExp)[];
+export interface CorsOptions {
+    origin?: OriginOption;
+    methods?: string | string[];
+    allowedHeaders?: string | string[];
+    exposedHeaders?: string | string[];
+    credentials?: boolean;
+    maxAge?: number;
+}
+export declare function addCorsHeaders(headers: Headers, opts: CorsOptions, req: Request): void;
+export {};

package/dist/cors.js

@@ -0,0 +1,83 @@
+export function addCorsHeaders(headers, opts, req) {
+    addOrigin(opts, headers, req);
+    addCredentials(opts, headers);
+    addExposedHeaders(opts, headers);
+    if (req.method === "OPTIONS") {
+        addMethods(opts, headers);
+        addAllowedHeaders(opts, headers, req);
+        addMaxAge(opts, headers);
+    }
+}
+function join(arg) {
+    return Array.isArray(arg) ? arg.join(",") : arg;
+}
+function isOriginAllowed(allowedOrigin, origin) {
+    if (Array.isArray(allowedOrigin)) {
+        for (let i = 0; i < allowedOrigin.length; i++) {
+            if (isOriginAllowed(allowedOrigin[i], origin)) {
+                return true;
+            }
+        }
+        return false;
+    }
+    else if (typeof allowedOrigin === "string") {
+        return allowedOrigin === origin;
+    }
+    else if (allowedOrigin instanceof RegExp) {
+        return allowedOrigin.test(origin);
+    }
+    else {
+        return !!allowedOrigin;
+    }
+}
+function addOrigin(opts, headers, req) {
+    const origin = req.headers.get("origin");
+    const allowedOrigin = opts.origin;
+    if (!allowedOrigin || allowedOrigin === "*") {
+        headers.set("Access-Control-Allow-Origin", "*");
+    }
+    else if (typeof allowedOrigin === "string") {
+        headers.set("Access-Control-Allow-Origin", allowedOrigin);
+        headers.append("Vary", "Origin");
+    }
+    else if (origin) {
+        const isAllowed = isOriginAllowed(allowedOrigin, origin);
+        headers.set("Access-Control-Allow-Origin", isAllowed ? origin : "false");
+        headers.append("Vary", "Origin");
+    }
+    else {
+        headers.set("Access-Control-Allow-Origin", "false");
+        headers.append("Vary", "Origin");
+    }
+}
+function addMethods(opts, headers) {
+    if (opts.methods) {
+        headers.set("Access-Control-Allow-Methods", join(opts.methods));
+    }
+}
+function addAllowedHeaders(opts, headers, req) {
+    if (opts.allowedHeaders) {
+        headers.set("Access-Control-Allow-Headers", join(opts.allowedHeaders));
+        return;
+    }
+    const requestedHeaders = req.headers.get("access-control-request-headers");
+    if (requestedHeaders) {
+        headers.append("Vary", "Access-Control-Request-Headers");
+        headers.set("Access-Control-Allow-Headers", requestedHeaders);
+    }
+}
+function addExposedHeaders(opts, headers) {
+    if (opts.exposedHeaders) {
+        headers.set("Access-Control-Expose-Headers", join(opts.exposedHeaders));
+    }
+}
+function addCredentials(opts, headers) {
+    if (opts.credentials) {
+        headers.set("Access-Control-Allow-Credentials", "true");
+    }
+}
+function addMaxAge(opts, headers) {
+    if (opts.maxAge) {
+        headers.set("Access-Control-Max-Age", opts.maxAge.toString());
+    }
+}

package/dist/event-emitter.d.ts

@@ -0,0 +1,105 @@
+/**
+ * An events map is an interface that maps event names to their value, which represents the type of the `on` listener.
+ */
+export interface EventsMap {
+    [event: string]: any;
+}
+/**
+ * The default events map, used if no EventsMap is given. Using this EventsMap is equivalent to accepting all event
+ * names, and any data.
+ */
+export interface DefaultEventsMap {
+    [event: string]: (...args: any[]) => void;
+}
+/**
+ * Returns a union type containing all the keys of an event map.
+ */
+export type EventNames<Map extends EventsMap> = keyof Map & (string | symbol);
+/** The tuple type representing the parameters of an event listener */
+export type EventParams<Map extends EventsMap, Ev extends EventNames<Map>> = Parameters<Map[Ev]>;
+/**
+ * The event names that are either in ReservedEvents or in UserEvents
+ */
+export type ReservedOrUserEventNames<ReservedEventsMap extends EventsMap, UserEvents extends EventsMap> = EventNames<ReservedEventsMap> | EventNames<UserEvents>;
+/**
+ * Type of a listener of a user event or a reserved event. If `Ev` is in `ReservedEvents`, the reserved event listener
+ * is returned.
+ */
+export type ReservedOrUserListener<ReservedEvents extends EventsMap, UserEvents extends EventsMap, Ev extends ReservedOrUserEventNames<ReservedEvents, UserEvents>> = FallbackToUntypedListener<Ev extends EventNames<ReservedEvents> ? ReservedEvents[Ev] : Ev extends EventNames<UserEvents> ? UserEvents[Ev] : never>;
+/**
+ * Returns an untyped listener type if `T` is `never`; otherwise, returns `T`.
+ *
+ * Needed because of https://github.com/microsoft/TypeScript/issues/41778
+ */
+type FallbackToUntypedListener<T> = [T] extends [never] ? (...args: any[]) => void | Promise<void> : T;
+/**
+ * Strictly typed version of an `EventEmitter`. A `TypedEventEmitter` takes type parameters for mappings of event names
+ * to event data types, and strictly types method calls to the `EventEmitter` according to these event maps.
+ *
+ * @typeParam ListenEvents - `EventsMap` of user-defined events that can be listened to with `on` or `once`
+ * @typeParam EmitEvents - `EventsMap` of user-defined events that can be emitted with `emit`
+ * @typeParam ReservedEvents - `EventsMap` of reserved events, that can be emitted with `emitReserved`, and can be
+ * listened to with `listen`.
+ */
+declare abstract class BaseEventEmitter<ListenEvents extends EventsMap, EmitEvents extends EventsMap, ReservedEvents extends EventsMap = never> {
+    private _listeners;
+    /**
+     * Adds the `listener` function as an event listener for `ev`.
+     *
+     * @param event - Name of the event
+     * @param listener - Callback function
+     */
+    on<Ev extends ReservedOrUserEventNames<ReservedEvents, ListenEvents>>(event: Ev, listener: ReservedOrUserListener<ReservedEvents, ListenEvents, Ev>): this;
+    /**
+     * Adds a one-time `listener` function as an event listener for `ev`.
+     *
+     * @param event - Name of the event
+     * @param listener - Callback function
+     */
+    once<Ev extends ReservedOrUserEventNames<ReservedEvents, ListenEvents>>(event: Ev, listener: ReservedOrUserListener<ReservedEvents, ListenEvents, Ev>): this;
+    /**
+     * Removes the `listener` function as an event listener for `ev`.
+     *
+     * @param event - Name of the event
+     * @param listener - Callback function
+     */
+    off<Ev extends ReservedOrUserEventNames<ReservedEvents, ListenEvents>>(event?: Ev, listener?: ReservedOrUserListener<ReservedEvents, ListenEvents, Ev>): this;
+    /**
+     * Removes the `listener` function as an event listener for `ev`.
+     *
+     * @param event - Name of the event
+     * @param listener - Callback function
+     */
+    removeListener<Ev extends ReservedOrUserEventNames<ReservedEvents, ListenEvents>>(event?: Ev, listener?: ReservedOrUserListener<ReservedEvents, ListenEvents, Ev>): this;
+    /**
+     * Emits an event.
+     *
+     * @param event - Name of the event
+     * @param args - Values to send to listeners of this event
+     */
+    emit<Ev extends EventNames<EmitEvents>>(event: Ev, ...args: EventParams<EmitEvents, Ev>): boolean;
+    /**
+     * Returns the listeners listening to an event.
+     *
+     * @param event - Event name
+     * @returns Array of listeners subscribed to `event`
+     */
+    listeners<Ev extends ReservedOrUserEventNames<ReservedEvents, ListenEvents>>(event: Ev): ReservedOrUserListener<ReservedEvents, ListenEvents, Ev>[];
+}
+/**
+ * This class extends the BaseEventEmitter abstract class, so a class extending `EventEmitter` can override the `emit`
+ * method and still call `emitReserved()` (since it uses `super.emit()`)
+ */
+export declare class EventEmitter<ListenEvents extends EventsMap, EmitEvents extends EventsMap, ReservedEvents extends EventsMap = never> extends BaseEventEmitter<ListenEvents, EmitEvents, ReservedEvents> {
+    /**
+     * Emits a reserved event.
+     *
+     * This method is `protected`, so that only a class extending `EventEmitter` can emit its own reserved events.
+     *
+     * @param event - Reserved event name
+     * @param args - Arguments to emit along with the event
+     * @protected
+     */
+    protected emitReserved<Ev extends EventNames<ReservedEvents>>(event: Ev, ...args: EventParams<ReservedEvents, Ev>): boolean;
+}
+export {};

package/dist/event-emitter.js

@@ -0,0 +1,129 @@
+/**
+ * Strictly typed version of an `EventEmitter`. A `TypedEventEmitter` takes type parameters for mappings of event names
+ * to event data types, and strictly types method calls to the `EventEmitter` according to these event maps.
+ *
+ * @typeParam ListenEvents - `EventsMap` of user-defined events that can be listened to with `on` or `once`
+ * @typeParam EmitEvents - `EventsMap` of user-defined events that can be emitted with `emit`
+ * @typeParam ReservedEvents - `EventsMap` of reserved events, that can be emitted with `emitReserved`, and can be
+ * listened to with `listen`.
+ */
+class BaseEventEmitter {
+    _listeners = new Map();
+    /**
+     * Adds the `listener` function as an event listener for `ev`.
+     *
+     * @param event - Name of the event
+     * @param listener - Callback function
+     */
+    on(event, listener) {
+        const listeners = this._listeners.get(event);
+        if (listeners) {
+            listeners.push(listener);
+        }
+        else {
+            this._listeners.set(event, [listener]);
+        }
+        return this;
+    }
+    /**
+     * Adds a one-time `listener` function as an event listener for `ev`.
+     *
+     * @param event - Name of the event
+     * @param listener - Callback function
+     */
+    once(event, listener) {
+        const onceListener = ((...args) => {
+            this.off(event, onceListener);
+            listener.apply(this, args);
+        });
+        onceListener.fn = listener;
+        return this.on(event, onceListener);
+    }
+    /**
+     * Removes the `listener` function as an event listener for `ev`.
+     *
+     * @param event - Name of the event
+     * @param listener - Callback function
+     */
+    off(event, listener) {
+        if (!event) {
+            this._listeners.clear();
+            return this;
+        }
+        if (!listener) {
+            this._listeners.delete(event);
+            return this;
+        }
+        const listeners = this._listeners.get(event);
+        if (!listeners) {
+            return this;
+        }
+        for (let i = 0; i < listeners.length; i++) {
+            if (listeners[i] === listener || listeners[i].fn === listener) {
+                listeners.splice(i, 1);
+                break;
+            }
+        }
+        if (listeners.length === 0) {
+            this._listeners.delete(event);
+        }
+        return this;
+    }
+    /**
+     * Removes the `listener` function as an event listener for `ev`.
+     *
+     * @param event - Name of the event
+     * @param listener - Callback function
+     */
+    removeListener(event, listener) {
+        return this.off(event, listener);
+    }
+    /**
+     * Emits an event.
+     *
+     * @param event - Name of the event
+     * @param args - Values to send to listeners of this event
+     */
+    emit(event, ...args) {
+        const listeners = this._listeners.get(event);
+        if (!listeners) {
+            return false;
+        }
+        if (listeners.length === 1) {
+            listeners[0].apply(this, args);
+        }
+        else {
+            for (const listener of listeners.slice()) {
+                listener.apply(this, args);
+            }
+        }
+        return true;
+    }
+    /**
+     * Returns the listeners listening to an event.
+     *
+     * @param event - Event name
+     * @returns Array of listeners subscribed to `event`
+     */
+    listeners(event) {
+        return this._listeners.get(event) || [];
+    }
+}
+/**
+ * This class extends the BaseEventEmitter abstract class, so a class extending `EventEmitter` can override the `emit`
+ * method and still call `emitReserved()` (since it uses `super.emit()`)
+ */
+export class EventEmitter extends BaseEventEmitter {
+    /**
+     * Emits a reserved event.
+     *
+     * This method is `protected`, so that only a class extending `EventEmitter` can emit its own reserved events.
+     *
+     * @param event - Reserved event name
+     * @param args - Arguments to emit along with the event
+     * @protected
+     */
+    emitReserved(event, ...args) {
+        return super.emit(event, ...args);
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export { Server, type ServerOptions } from "./server";
+export { type RawData } from "./parser";
+export { type BunWebSocket, type WebSocketData } from "./transports/websocket";

package/dist/index.js

@@ -0,0 +1,3 @@
+export { Server } from "./server";
+export {} from "./parser";
+export {} from "./transports/websocket";

package/dist/parser.d.ts

@@ -0,0 +1,14 @@
+export type PacketType = "open" | "close" | "ping" | "pong" | "message" | "upgrade" | "noop" | "error";
+export type RawData = string | Buffer;
+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;
+    encodePayload(packets: Packet[]): string;
+    decodePayload(encodedPayload: string, binaryType?: BinaryType): Packet[];
+};
+export {};

package/dist/parser.js

@@ -0,0 +1,73 @@
+const SEPARATOR = String.fromCharCode(30); // see https://en.wikipedia.org/wiki/Delimiter#ASCII_delimited_text
+const PACKET_TYPES = new Map();
+const PACKET_TYPES_REVERSE = new Map();
+[
+    "open",
+    "close",
+    "ping",
+    "pong",
+    "message",
+    "upgrade",
+    "noop",
+].forEach((type, index) => {
+    PACKET_TYPES.set(type, "" + index);
+    PACKET_TYPES_REVERSE.set("" + index, type);
+});
+const ERROR_PACKET = { type: "error", data: "parser error" };
+export const Parser = {
+    encodePacket({ type, data }, supportsBinary) {
+        if (Buffer.isBuffer(data)) {
+            return supportsBinary ? data : "b" + data.toString("base64");
+        }
+        else {
+            return PACKET_TYPES.get(type) + (data || "");
+        }
+    },
+    decodePacket(encodedPacket, _binaryType) {
+        if (typeof encodedPacket !== "string") {
+            return {
+                type: "message",
+                data: encodedPacket,
+            };
+        }
+        const typeChar = encodedPacket.charAt(0);
+        if (typeChar === "b") {
+            const buffer = Buffer.from(encodedPacket.substring(1), "base64");
+            return {
+                type: "message",
+                data: buffer,
+            };
+        }
+        if (!PACKET_TYPES_REVERSE.has(typeChar)) {
+            return ERROR_PACKET;
+        }
+        const type = PACKET_TYPES_REVERSE.get(typeChar);
+        return encodedPacket.length > 1
+            ? {
+                type,
+                data: encodedPacket.substring(1),
+            }
+            : {
+                type,
+            };
+    },
+    encodePayload(packets) {
+        const encodedPackets = [];
+        for (const packet of packets) {
+            encodedPackets.push(this.encodePacket(packet, false));
+        }
+        return encodedPackets.join(SEPARATOR);
+    },
+    decodePayload(encodedPayload, binaryType) {
+        const encodedPackets = encodedPayload.split(SEPARATOR);
+        const packets = [];
+        for (let i = 0; i < encodedPackets.length; i++) {
+            const decodedPacket = this.decodePacket(encodedPackets[i], binaryType);
+            packets.push(decodedPacket);
+            if (decodedPacket.type === "error") {
+                break;
+            }
+        }
+        return packets;
+    },
+};