https://github.com/socketio/bun-engine
The Socket.IO low-level engine for Bun
https://github.com/socketio/bun-engine
Last synced: 5 months ago
JSON representation
The Socket.IO low-level engine for Bun
- Host: GitHub
- URL: https://github.com/socketio/bun-engine
- Owner: socketio
- License: mit
- Created: 2025-08-16T07:19:49.000Z (6 months ago)
- Default Branch: main
- Last Pushed: 2025-08-25T06:35:01.000Z (5 months ago)
- Last Synced: 2025-08-25T09:22:41.788Z (5 months ago)
- Language: TypeScript
- Homepage:
- Size: 29.3 KB
- Stars: 29
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
# @socket.io/bun-engine
A highly efficient, Bun-powered engine for Socket.IO, designed to enhance real-time communication performance.
This package provides a custom engine for Socket.IO that leverages the speed and scalability of Bun to handle WebSocket
connections seamlessly.
Reference: https://socket.io/
**Table of contents**
* [How to use](#how-to-use)
* [With Bun's HTTP server](#with-buns-http-server)
* [With Hono](#with-hono)
* [Options](#options)
* [`path`](#path)
* [`pingTimeout`](#pingtimeout)
* [`pingInterval`](#pinginterval)
* [`upgradeTimeout`](#upgradetimeout)
* [`maxHttpBufferSize`](#maxhttpbuffersize)
* [`allowRequest`](#allowrequest)
* [`cors`](#cors)
* [`editHandshakeHeaders`](#edithandshakeheaders)
* [`editResponseHeaders`](#editresponseheaders)
* [License](#license)
## How to use
### With Bun's HTTP server
```js
import { Server as Engine } from "@socket.io/bun-engine";
import { Server } from "socket.io";
const io = new Server();
const engine = new Engine({
path: "/socket.io/",
});
io.bind(engine);
io.on("connection", (socket) => {
// ...
});
export default {
port: 3000,
idleTimeout: 30, // must be greater than the "pingInterval" option of the engine, which defaults to 25 seconds
...engine.handler(),
};
```
### With Hono
```js
import { Server as Engine } from "@socket.io/bun-engine";
import { Server } from "socket.io";
import { Hono } from "hono";
const io = new Server();
const engine = new Engine();
io.bind(engine);
io.on("connection", (socket) => {
// ...
});
const app = new Hono();
const { websocket } = engine.handler();
export default {
port: 3000,
idleTimeout: 30, // must be greater than the "pingInterval" option of the engine, which defaults to 25 seconds
fetch(req, server) {
const url = new URL(req.url);
if (url.pathname === "/socket.io/") {
return engine.handleRequest(req, server);
} else {
return app.fetch(req, server);
}
},
websocket
}
```
Reference: https://hono.dev/docs/
## Options
### `path`
Default value: `/engine.io/`
It is the name of the path that is captured on the server side.
Caution! The server and the client values must match (unless you are using a
path-rewriting proxy in between).
Example:
```ts
const engine = new Server(httpServer, {
path: "/my-custom-path/",
});
```
### `pingTimeout`
Default value: `20000`
This value is used in the heartbeat mechanism, which periodically checks if the
connection is still alive between the server and the client.
The server sends a ping, and if the client does not answer with a pong within
`pingTimeout` ms, the server considers that the connection is closed.
Similarly, if the client does not receive a ping from the server within
`pingInterval + pingTimeout` ms, the client also considers that the connection
is closed.
### `pingInterval`
Default value: `25000`
See [`pingTimeout`](#pingtimeout) for more explanation.
### `upgradeTimeout`
Default value: `10000`
This is the delay in milliseconds before an uncompleted transport upgrade is
cancelled.
### `maxHttpBufferSize`
Default value: `1e6` (1 MB)
This defines how many bytes a single message can be, before closing the socket.
You may increase or decrease this value depending on your needs.
### `allowRequest`
Default value: `-`
A function that receives a given handshake or upgrade request as its first
parameter, and can decide whether to continue or not.
Example:
```ts
const engine = new Server({
allowRequest: (req, connInfo) => {
return Promise.reject("thou shall not pass");
},
});
```
### `cors`
Default value: `-`
A set of options related to
[Cross-Origin Resource Sharing](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS)
(CORS).
Example:
```ts
const engine = new Server({
cors: {
origin: ["https://example.com"],
allowedHeaders: ["my-header"],
credentials: true,
},
});
```
### `editHandshakeHeaders`
Default value: `-`
A function that allows to edit the response headers of the handshake request.
Example:
```ts
const engine = new Server({
editHandshakeHeaders: (responseHeaders, req, connInfo) => {
responseHeaders.set("set-cookie", "sid=1234");
},
});
```
### `editResponseHeaders`
Default value: `-`
A function that allows to edit the response headers of all requests.
Example:
```ts
const engine = new Server({
editResponseHeaders: (responseHeaders, req, connInfo) => {
responseHeaders.set("my-header", "abcd");
},
});
```
## License
[MIT](/LICENSE)