@hedystia/ws 2.3.2 → 2.3.4

package/dist/server.cjs

@@ -1,18 +1,245 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-let ws = require("ws");
+let node_crypto = require("node:crypto");
 //#region src/server.ts
 /**
-* Runtime-agnostic WebSocket server.
+* WebSocket magic GUID defined in RFC 6455 section 4.2.2.
+*
+* @internal
+*/
+const WS_GUID = "258EAFA5-E914-47DA-95CA-C5AB0DC85B11";
+const OP_CONTINUATION = 0;
+const OP_TEXT = 1;
+const OP_BINARY = 2;
+const OP_CLOSE = 8;
+const OP_PING = 9;
+const OP_PONG = 10;
+/**
+* Compute the `Sec-WebSocket-Accept` response header per RFC 6455 §4.2.2.
+*
+* @param clientKey - Value of the `Sec-WebSocket-Key` request header
+* @returns Base-64 encoded SHA-1 digest
+*
+* @internal
+*/
+function computeAccept(clientKey) {
+	return (0, node_crypto.createHash)("sha1").update(clientKey + WS_GUID).digest("base64");
+}
+/**
+* Write a single unmasked (server-to-client) WebSocket data frame to a raw
+* duplex socket per RFC 6455 §5.2.
+*
+* @param socket  - Underlying duplex transport
+* @param opcode  - WebSocket opcode (text, binary, close, ping, pong …)
+* @param payload - Payload bytes to encapsulate
+*
+* @internal
+*/
+function writeFrame(socket, opcode, payload) {
+	const len = payload.length;
+	let header;
+	if (len < 126) {
+		header = Buffer.allocUnsafe(2);
+		header[0] = 128 | opcode;
+		header[1] = len;
+	} else if (len < 65536) {
+		header = Buffer.allocUnsafe(4);
+		header[0] = 128 | opcode;
+		header[1] = 126;
+		header.writeUInt16BE(len, 2);
+	} else {
+		header = Buffer.allocUnsafe(10);
+		header[0] = 128 | opcode;
+		header[1] = 127;
+		header.writeUInt32BE(0, 2);
+		header.writeUInt32BE(len >>> 0, 6);
+	}
+	if (payload.length === 0) socket.write(header);
+	else socket.write(Buffer.concat([header, payload]));
+}
+/**
+* Incremental streaming RFC 6455 frame parser for masked client→server frames.
+* Handles fragmentation, ping/pong, and close frames internally.
+*
+* @internal
+*/
+var FrameParser = class {
+	buf = Buffer.alloc(0);
+	fragments = [];
+	fragmentOpcode = 0;
+	maxPayload;
+	/** Callback fired when a complete data frame is assembled. */
+	onMessage;
+	/** Callback fired when a close frame is received. */
+	onClose;
+	/** Callback fired when a ping frame is received. */
+	onPing;
+	/** Callback fired on parse errors or protocol violations. */
+	onError;
+	/**
+	* @param maxPayload - Maximum allowed frame payload in bytes (default 100 MiB)
+	*/
+	constructor(maxPayload = 100 * 1024 * 1024) {
+		this.maxPayload = maxPayload;
+	}
+	/**
+	* Feed a new chunk of raw socket data into the parser.
+	*
+	* @param chunk - Incoming bytes from the transport
+	*/
+	push(chunk) {
+		this.buf = this.buf.length === 0 ? chunk : Buffer.concat([this.buf, chunk]);
+		this.drain();
+	}
+	/**
+	* Consume as many complete frames as possible from the internal buffer.
+	*
+	* @internal
+	*/
+	drain() {
+		for (;;) {
+			if (this.buf.length < 2) return;
+			const b0 = this.buf[0];
+			const b1 = this.buf[1];
+			const fin = (b0 & 128) !== 0;
+			const rsv = b0 & 112;
+			const opcode = b0 & 15;
+			const masked = (b1 & 128) !== 0;
+			let payloadLen = b1 & 127;
+			let offset = 2;
+			if (rsv !== 0) {
+				this.onError?.(/* @__PURE__ */ new Error("WebSocket: RSV bits must be 0 (no extensions negotiated)"));
+				return;
+			}
+			if (payloadLen === 126) {
+				if (this.buf.length < 4) return;
+				payloadLen = this.buf.readUInt16BE(2);
+				offset = 4;
+			} else if (payloadLen === 127) {
+				if (this.buf.length < 10) return;
+				const hi = this.buf.readUInt32BE(2);
+				const lo = this.buf.readUInt32BE(6);
+				payloadLen = hi * 4294967296 + lo;
+				offset = 10;
+			}
+			if (payloadLen > this.maxPayload) {
+				this.onError?.(/* @__PURE__ */ new Error(`WebSocket: payload length ${payloadLen} exceeds maxPayload ${this.maxPayload}`));
+				return;
+			}
+			const frameEnd = offset + (masked ? 4 : 0) + payloadLen;
+			if (this.buf.length < frameEnd) return;
+			let payload;
+			if (masked) {
+				const mask = this.buf.subarray(offset, offset + 4);
+				payload = Buffer.allocUnsafe(payloadLen);
+				for (let i = 0; i < payloadLen; i++) payload[i] = this.buf[offset + 4 + i] ^ mask[i & 3];
+			} else payload = Buffer.from(this.buf.subarray(offset, frameEnd));
+			this.buf = this.buf.subarray(frameEnd);
+			this.handleFrame(fin, opcode, payload);
+		}
+	}
+	/**
+	* Route a parsed frame to the appropriate callback based on opcode.
+	*
+	* @param fin     - Whether this is the final fragment
+	* @param opcode  - WebSocket frame opcode
+	* @param payload - Unmasked payload bytes
+	*
+	* @internal
+	*/
+	handleFrame(fin, opcode, payload) {
+		switch (opcode) {
+			case OP_PING:
+				this.onPing?.(payload);
+				return;
+			case OP_PONG: return;
+			case OP_CLOSE: {
+				const code = payload.length >= 2 ? payload.readUInt16BE(0) : 1e3;
+				const reason = payload.length > 2 ? payload.subarray(2).toString("utf8") : "";
+				this.onClose?.(code, reason);
+				return;
+			}
+			case OP_CONTINUATION:
+			case OP_TEXT:
+			case OP_BINARY:
+				if (opcode !== OP_CONTINUATION) this.fragmentOpcode = opcode;
+				this.fragments.push(payload);
+				if (fin) {
+					const full = Buffer.concat(this.fragments);
+					this.fragments = [];
+					const isBinary = this.fragmentOpcode === OP_BINARY;
+					this.onMessage?.(isBinary ? full : full.toString("utf8"), isBinary);
+				}
+				return;
+			default: this.onError?.(/* @__PURE__ */ new Error(`WebSocket: unknown opcode 0x${opcode.toString(16)}`));
+		}
+	}
+};
+/**
+* Thin wrapper around a raw `Duplex` that exposes a minimal frame-aware
+* WebSocket interface used internally by {@link WebSocketServer}.
+*
+* @internal
+*/
+var NativeSocket = class {
+	/** Underlying duplex transport stream. */
+	duplex;
+	/** Incremental frame parser attached to this transport. */
+	parser;
+	/** WHATWG-compatible ready-state: `1` open · `2` closing · `3` closed. */
+	readyState = 1;
+	/**
+	* @param duplex     - Raw duplex transport
+	* @param maxPayload - Maximum allowed payload in bytes
+	*/
+	constructor(duplex, maxPayload) {
+		this.duplex = duplex;
+		this.parser = new FrameParser(maxPayload);
+	}
+	/**
+	* Send a data frame to the peer.
+	*
+	* @param data - Payload to transmit
+	*/
+	send(data) {
+		if (this.readyState !== 1) return;
+		const isBuf = Buffer.isBuffer(data);
+		const buf = typeof data === "string" ? Buffer.from(data, "utf8") : isBuf ? data : Buffer.from(data);
+		writeFrame(this.duplex, typeof data === "string" ? OP_TEXT : OP_BINARY, buf);
+	}
+	/**
+	* Initiate the close handshake.
+	*
+	* @param code   - Close status code (default `1000`)
+	* @param reason - Optional UTF-8 reason phrase
+	*/
+	close(code = 1e3, reason = "") {
+		if (this.readyState !== 1) return;
+		this.readyState = 2;
+		const reasonBuf = Buffer.from(reason, "utf8");
+		const payload = Buffer.allocUnsafe(2 + reasonBuf.length);
+		payload.writeUInt16BE(code, 0);
+		reasonBuf.copy(payload, 2);
+		writeFrame(this.duplex, OP_CLOSE, payload);
+	}
+	/**
+	* Hard-terminate the underlying transport without a close handshake.
+	*/
+	terminate() {
+		this.readyState = 3;
+		this.duplex.destroy();
+	}
+};
+/**
+* Runtime-agnostic WebSocket server built entirely on Node.js built-ins
+* (`node:crypto`, `node:stream`) — no third-party dependencies.
 *
 * @remarks
-* Internally backed by the [`ws`](https://github.com/websockets/ws) package
-* which runs on Bun, Node.js and Deno (via `npm:` specifiers). The class
-* does **not** create or own an HTTP server — callers feed it raw upgrade
-* tuples coming from any HTTP runtime they prefer.
+* The class does **not** create or own an HTTP server. Callers feed it raw
+* upgrade tuples coming from any HTTP runtime (Node.js `http`, Bun, Deno,
+* Hono, Fastify's upgrade hook, etc.).
 *
-* It implements topic-based pub/sub on top of the per-connection
-* `subscribe` / `unsubscribe` / `publish` API expected by Hedystia,
-* matching the shape of `Bun.ServerWebSocket`.
+* Topic-based pub/sub is implemented in user-space, matching the shape of
+* `Bun.ServerWebSocket` so the same handler code runs on every runtime.
 *
 * @typeParam Data - Shape of the user-attached `data` field
 *
@@ -22,8 +249,9 @@ let ws = require("ws");
 * import { WebSocketServer } from "@hedystia/ws/server";
 *
 * const wss = new WebSocketServer({
-*   open: (ws) => ws.send("welcome"),
+*   open:    (ws) => ws.send("welcome"),
 *   message: (ws, msg) => ws.publish("room", msg),
+*   close:   (ws, code) => console.log("closed", code),
 * });
 *
 * const http = createServer((_req, res) => res.end("ok"));
@@ -35,7 +263,8 @@ let ws = require("ws");
 */
 var WebSocketServer = class {
 	handlers;
-	wss;
+	maxPayload;
+	resolveData;
 	topics = /* @__PURE__ */ new Map();
 	socketTopics = /* @__PURE__ */ new WeakMap();
 	allSockets = /* @__PURE__ */ new Set();
@@ -43,7 +272,7 @@ var WebSocketServer = class {
 	* Build a new WebSocket server.
 	*
 	* @param handlers - Lifecycle handlers ({@link WebSocketHandlers})
-	* @param options - Optional behavioural overrides ({@link WebSocketServerOptions})
+	* @param options  - Optional behavioural overrides ({@link WebSocketServerOptions})
 	*
 	* @example
 	* ```ts
@@ -55,24 +284,23 @@ var WebSocketServer = class {
 	*/
 	constructor(handlers, options = {}) {
 		this.handlers = handlers;
-		this.wss = new ws.WebSocketServer({
-			noServer: true,
-			maxPayload: options.maxPayload,
-			perMessageDeflate: options.perMessageDeflate ?? false
-		});
+		this.maxPayload = options.maxPayload;
+		this.resolveData = options.resolveData;
 	}
 	/**
 	* Upgrade a raw HTTP upgrade tuple to a WebSocket connection.
 	*
 	* @remarks
-	* The returned promise resolves to the connected {@link ServerWebSocket}
-	* once the handshake completes; rejection means the handshake failed.
+	* Performs the RFC 6455 handshake synchronously on the duplex socket,
+	* then wires up frame parsing and lifecycle handlers. The returned
+	* promise resolves to the {@link ServerWebSocket} wrapper immediately
+	* after the handshake bytes are written.
 	*
-	* @param req - Upgrade tuple emitted by `node:http`'s `'upgrade'` event
+	* @param req     - Upgrade tuple emitted by `node:http`'s `'upgrade'` event
 	* @param options - Optional initial `data` for the new connection
 	* @returns Promise that resolves with the established socket wrapper
 	*
-	* @throws {Error} When the underlying handshake throws synchronously
+	* @throws {Error} When `Sec-WebSocket-Key` is absent from the request headers
 	*
 	* @example
 	* ```ts
@@ -89,12 +317,27 @@ var WebSocketServer = class {
 	upgrade(req, options) {
 		return new Promise((resolve, reject) => {
 			try {
-				this.wss.handleUpgrade(req.rawRequest, req.socket, req.head, (socket) => {
-					const data = options?.data ?? {};
-					const wrapped = this.wrap(socket, data, req.rawRequest);
-					this.bind(socket, wrapped);
-					resolve(wrapped);
-				});
+				const rawReq = req.rawRequest;
+				const duplex = req.socket;
+				const clientKey = rawReq.headers?.["sec-websocket-key"];
+				if (!clientKey) {
+					duplex.destroy();
+					return reject(/* @__PURE__ */ new Error("WebSocket upgrade: missing Sec-WebSocket-Key header"));
+				}
+				const accept = computeAccept(clientKey);
+				const protocol = (rawReq.headers?.["sec-websocket-protocol"])?.split(",")[0]?.trim();
+				let response = `HTTP/1.1 101 Switching Protocols\r
+Upgrade: websocket\r
+Connection: Upgrade\r
+Sec-WebSocket-Accept: ${accept}\r\n`;
+				if (protocol) response += `Sec-WebSocket-Protocol: ${protocol}\r\n`;
+				response += "\r\n";
+				duplex.write(response);
+				const native = new NativeSocket(duplex, this.maxPayload);
+				const data = options?.data ?? {};
+				const wrapped = this.wrap(native, data, rawReq);
+				this.bind(native, wrapped, req.head);
+				resolve(wrapped);
 			} catch (err) {
 				reject(err);
 			}
@@ -103,10 +346,10 @@ var WebSocketServer = class {
 	/**
 	* Publish a message to all sockets currently subscribed to `topic`.
 	*
-	* @param topic - Topic name
-	* @param message - Payload to broadcast
-	* @param _compress - Reserved for future use; ignored under the `ws` adapter
-	* @returns Number of sockets that received the message.
+	* @param topic      - Topic name
+	* @param message    - Payload to broadcast
+	* @param _compress  - Reserved for future use
+	* @returns Number of sockets that received the message
 	*
 	* @example
 	* ```ts
@@ -118,8 +361,8 @@ var WebSocketServer = class {
 		if (!set || set.size === 0) return 0;
 		const payload = toSendable(message);
 		let count = 0;
-		for (const socket of set) if (socket.readyState === 1) {
-			socket.send(payload);
+		for (const native of set) if (native.readyState === 1) {
+			native.send(payload);
 			count++;
 		}
 		return count;
@@ -127,49 +370,100 @@ var WebSocketServer = class {
 	/**
 	* Close the server and optionally terminate all live sockets.
 	*
-	* @param closeActiveConnections - When `true`, calls `socket.terminate()`
-	*  on every live connection before shutting down.
+	* @param closeActiveConnections - When `true`, immediately terminates
+	*   every live connection before clearing internal state
 	*/
 	close(closeActiveConnections = false) {
 		if (closeActiveConnections) {
-			for (const socket of this.allSockets) try {
-				socket.terminate();
+			for (const native of this.allSockets) try {
+				if (typeof native.terminate === "function") native.terminate();
+				else if (typeof native.close === "function") native.close(1001, "Server shutdown");
 			} catch {}
 			this.allSockets.clear();
 		}
-		this.wss.close();
+		this.topics.clear();
 	}
 	/**
-	* Attach the per-socket lifecycle listeners (`message`, `close`, `error`).
+	* Wire up the duplex transport listeners (`data`, `close`, `error`) and
+	* invoke the user's `open` handler.
+	*
+	* @param native  - Wrapped transport socket
+	* @param wrapped - Public {@link ServerWebSocket} wrapper
+	* @param head    - Buffered bytes captured by the HTTP parser (re-fed into the parser)
 	*
 	* @internal
 	*/
-	bind(socket, wrapped) {
-		this.allSockets.add(socket);
-		if (this.handlers.open) Promise.resolve(this.handlers.open(wrapped)).catch((err) => console.error("[ws] open handler error:", err));
-		socket.on("message", (raw, isBinary) => {
-			const message = isBinary ? raw instanceof ArrayBuffer ? new Uint8Array(raw) : Array.isArray(raw) ? Buffer.concat(raw) : raw : raw.toString();
+	bind(native, wrapped, head) {
+		this.allSockets.add(native);
+		if (head && head.length > 0) native.parser.push(Buffer.isBuffer(head) ? head : Buffer.from(head));
+		native.parser.onMessage = (raw, isBinary) => {
+			const message = isBinary ? raw instanceof Buffer ? raw : Buffer.from(raw) : raw;
 			Promise.resolve(this.handlers.message(wrapped, message)).catch((err) => console.error("[ws] message handler error:", err));
+		};
+		native.parser.onClose = (code, reason) => {
+			if (native.readyState === 1) native.close(code, reason);
+			this.cleanup(native);
+			if (this.handlers.close) Promise.resolve(this.handlers.close(wrapped, code, reason)).catch((err) => console.error("[ws] close handler error:", err));
+		};
+		native.parser.onPing = (data) => {
+			if (native.readyState === 1) writeFrame(native.duplex, OP_PONG, data);
+		};
+		native.parser.onError = (err) => {
+			native.terminate();
+			this.cleanup(native);
+			if (this.handlers.error) Promise.resolve(this.handlers.error(wrapped, err)).catch((e) => console.error("[ws] error handler error:", e));
+		};
+		native.duplex.on("data", (chunk) => {
+			try {
+				native.parser.push(chunk);
+			} catch (err) {
+				console.error("[ws] frame parsing error:", err);
+				native.terminate();
+				this.cleanup(native);
+			}
 		});
-		socket.on("close", (code, reason) => {
-			const owned = this.socketTopics.get(socket);
-			if (owned) {
-				for (const topic of owned) this.topics.get(topic)?.delete(socket);
-				this.socketTopics.delete(socket);
+		native.duplex.on("close", () => {
+			if (native.readyState !== 3) {
+				native.readyState = 3;
+				this.cleanup(native);
+				if (this.handlers.close) Promise.resolve(this.handlers.close(wrapped, 1006, "")).catch((err) => console.error("[ws] close handler error:", err));
 			}
-			this.allSockets.delete(socket);
-			if (this.handlers.close) Promise.resolve(this.handlers.close(wrapped, code, reason?.toString() ?? "")).catch((err) => console.error("[ws] close handler error:", err));
 		});
-		socket.on("error", (err) => {
+		native.duplex.on("error", (err) => {
+			native.readyState = 3;
+			this.cleanup(native);
 			if (this.handlers.error) Promise.resolve(this.handlers.error(wrapped, err)).catch((e) => console.error("[ws] error handler error:", e));
 		});
+		if (this.handlers.open) Promise.resolve(this.handlers.open(wrapped)).catch((err) => console.error("[ws] open handler error:", err));
+	}
+	/**
+	* Remove a socket from every topic it had joined and from the global
+	* tracking set.
+	*
+	* @param native - Socket being cleaned up
+	*
+	* @internal
+	*/
+	cleanup(native) {
+		const owned = this.socketTopics.get(native);
+		if (owned) {
+			for (const topic of owned) this.topics.get(topic)?.delete(native);
+			this.socketTopics.delete(native);
+		}
+		this.allSockets.delete(native);
 	}
 	/**
-	* Build the {@link ServerWebSocket} wrapper exposed to user handlers.
+	* Build the {@link ServerWebSocket} wrapper exposed to user handlers,
+	* embedding topic-based pub/sub backed by the server's internal maps.
+	*
+	* @param native - Wrapped transport socket
+	* @param data   - User-supplied `data` payload attached on upgrade
+	* @param rawReq - Raw incoming message used to extract the remote address
+	* @returns The fully-featured public wrapper
 	*
 	* @internal
 	*/
-	wrap(socket, data, rawReq) {
+	wrap(native, data, rawReq) {
 		const remoteAddress = rawReq?.socket?.remoteAddress || rawReq?.headers?.["x-forwarded-for"] || "";
 		const subscribe = (topic) => {
 			let set = this.topics.get(topic);
@@ -177,52 +471,262 @@ var WebSocketServer = class {
 				set = /* @__PURE__ */ new Set();
 				this.topics.set(topic, set);
 			}
-			set.add(socket);
-			let owned = this.socketTopics.get(socket);
+			set.add(native);
+			let owned = this.socketTopics.get(native);
 			if (!owned) {
 				owned = /* @__PURE__ */ new Set();
-				this.socketTopics.set(socket, owned);
+				this.socketTopics.set(native, owned);
 			}
 			owned.add(topic);
 		};
 		const unsubscribe = (topic) => {
-			this.topics.get(topic)?.delete(socket);
-			this.socketTopics.get(socket)?.delete(topic);
+			this.topics.get(topic)?.delete(native);
+			this.socketTopics.get(native)?.delete(topic);
 		};
 		const publishToPeers = (topic, message) => {
 			const set = this.topics.get(topic);
 			if (!set) return;
 			const payload = toSendable(message);
-			for (const peer of set) if (peer !== socket && peer.readyState === 1) peer.send(payload);
+			for (const peer of set) if (peer !== native && peer.readyState === 1) peer.send(payload);
 		};
 		const wrapper = {
 			data,
 			get readyState() {
-				return socket.readyState;
+				return native.readyState;
 			},
 			remoteAddress,
 			send: (message, _compress) => {
 				const payload = toSendable(message);
-				socket.send(payload);
+				native.send(payload);
 				return typeof payload === "string" ? Buffer.byteLength(payload) : payload.byteLength;
 			},
 			close: (code, reason) => {
-				socket.close(code, reason);
+				native.close(code, reason);
 			},
 			subscribe,
 			unsubscribe,
 			publish: publishToPeers,
-			isSubscribed: (topic) => !!this.socketTopics.get(socket)?.has(topic),
+			isSubscribed: (topic) => !!this.socketTopics.get(native)?.has(topic),
 			cork: (cb) => cb(wrapper)
 		};
 		return wrapper;
 	}
 };
 /**
-* Coerce a {@link WSMessage} into something the `ws` package can transmit.
+* Start a standalone WebSocket server on the given port.
+*
+* @remarks
+* Auto-detects the runtime and uses the native implementation:
+* - **Bun:** delegates to `Bun.serve()` with native WebSocket support
+* - **Node/Deno:** creates a `node:http` server with the built-in
+*   {@link WebSocketServer} upgrade handler
+*
+* @typeParam Data - Shape of the user-attached `data` field
+*
+* @param handlers - Lifecycle handlers ({@link WebSocketHandlers})
+* @param options  - Server options including `port` and `hostname`
+* @returns A promise resolving to {@link ServeInfo}
+*
+* @example
+* ```ts
+* import { serve } from "@hedystia/ws";
+*
+* const server = await serve({
+*   open:    (ws) => ws.subscribe("global"),
+*   message: (ws, msg) => ws.publish("global", msg),
+* });
+*
+* console.log(`Listening on ${server.url}`);
+* ```
+*/
+async function serve(handlers, options) {
+	const { detectRuntime } = await Promise.resolve().then(() => require("./runtime.cjs"));
+	if (detectRuntime() === "bun") return serveBun(handlers, options);
+	return serveNode(handlers, options);
+}
+/**
+* Start a WebSocket server using Bun's native `Bun.serve()`.
+*
+* @typeParam Data - Shape of the user-attached `data` field
+* @param handlers - Lifecycle handlers
+* @param options  - Server options including `port` and `hostname`
+* @returns A promise resolving to {@link ServeInfo}
+*
+* @internal
+*/
+async function serveBun(handlers, options) {
+	const topics = /* @__PURE__ */ new Map();
+	const socketTopics = /* @__PURE__ */ new WeakMap();
+	const allSockets = /* @__PURE__ */ new Set();
+	const nativeToWrapped = /* @__PURE__ */ new WeakMap();
+	function cleanup(ws) {
+		const owned = socketTopics.get(ws);
+		if (owned) {
+			for (const topic of owned) topics.get(topic)?.delete(ws);
+			socketTopics.delete(ws);
+		}
+		allSockets.delete(ws);
+	}
+	const server = globalThis.Bun.serve({
+		port: options?.port ?? 0,
+		hostname: options?.hostname ?? "0.0.0.0",
+		fetch: (req) => {
+			if (req.headers.get("upgrade") === "websocket") {
+				const data = options?.resolveData ? options.resolveData(req) : {};
+				return server.upgrade(req, { data }) ? void 0 : new Response("upgrade failed", { status: 400 });
+			}
+			return new Response("Not found", { status: 404 });
+		},
+		websocket: {
+			open: (ws) => {
+				const wrapped = createBunWrapper(ws, ws.data ?? {}, topics, socketTopics);
+				nativeToWrapped.set(ws, wrapped);
+				allSockets.add(wrapped);
+				if (handlers.open) Promise.resolve(handlers.open(wrapped)).catch((err) => console.error("[ws] open handler error:", err));
+			},
+			message: (ws, msg) => {
+				const wrapped = nativeToWrapped.get(ws);
+				if (wrapped) Promise.resolve(handlers.message(wrapped, msg)).catch((err) => console.error("[ws] message handler error:", err));
+			},
+			close: (ws, code, reason) => {
+				const wrapped = nativeToWrapped.get(ws);
+				if (wrapped) {
+					cleanup(wrapped);
+					if (handlers.close) Promise.resolve(handlers.close(wrapped, code, reason)).catch((err) => console.error("[ws] close handler error:", err));
+				}
+			},
+			drain: handlers.drain ? (ws) => {
+				const wrapped = nativeToWrapped.get(ws);
+				if (wrapped && handlers.drain) Promise.resolve(handlers.drain(wrapped)).catch((err) => console.error("[ws] drain handler error:", err));
+			} : void 0
+		}
+	});
+	return {
+		port: server.port,
+		hostname: server.hostname,
+		url: new URL(`http://${server.hostname}:${server.port}/`),
+		publish: (topic, message, _compress) => {
+			const set = topics.get(topic);
+			if (!set || set.size === 0) return 0;
+			const payload = toSendable(message);
+			let count = 0;
+			for (const ws of set) if (ws.readyState === 1) {
+				ws.send(payload);
+				count++;
+			}
+			return count;
+		},
+		stop: (closeActiveConnections) => {
+			if (closeActiveConnections) {
+				for (const ws of allSockets) try {
+					ws.close(1001, "Server shutdown");
+				} catch {}
+				allSockets.clear();
+			}
+			server.stop(closeActiveConnections);
+		}
+	};
+}
+/**
+* Wrap a native Bun WebSocket into a {@link ServerWebSocket} compatible with
+* the public handler interface.
+*
+* @typeParam Data - Shape of the user-attached `data` field
+* @param ws           - Raw Bun WebSocket
+* @param data         - User-supplied data payload
+* @param topics       - Global topic → socket set map
+* @param socketTopics - Reverse lookup for per-socket topic membership
+* @returns A {@link ServerWebSocket} wrapper
+*
+* @internal
+*/
+function createBunWrapper(ws, data, topics, socketTopics) {
+	const wrapper = {
+		data,
+		get readyState() {
+			return ws.readyState;
+		},
+		get remoteAddress() {
+			return ws.remoteAddress || "";
+		},
+		send: (message, _compress) => {
+			ws.send(message);
+			return typeof message === "string" ? Buffer.byteLength(message) : message.byteLength;
+		},
+		close: (code, reason) => ws.close(code, reason),
+		subscribe: (topic) => {
+			let set = topics.get(topic);
+			if (!set) {
+				set = /* @__PURE__ */ new Set();
+				topics.set(topic, set);
+			}
+			set.add(wrapper);
+			let owned = socketTopics.get(wrapper);
+			if (!owned) {
+				owned = /* @__PURE__ */ new Set();
+				socketTopics.set(wrapper, owned);
+			}
+			owned.add(topic);
+		},
+		unsubscribe: (topic) => {
+			topics.get(topic)?.delete(wrapper);
+			socketTopics.get(wrapper)?.delete(topic);
+		},
+		publish: (topic, message, _compress) => {
+			const set = topics.get(topic);
+			if (!set) return;
+			const payload = toSendable(message);
+			for (const peer of set) if (peer !== wrapper && peer.readyState === 1) peer.send(payload);
+		},
+		isSubscribed: (topic) => !!socketTopics.get(wrapper)?.has(topic),
+		cork: (cb) => cb(wrapper)
+	};
+	return wrapper;
+}
+/**
+* Start a WebSocket server using Node.js `node:http` + the built-in
+* {@link WebSocketServer} upgrade handler.
+*
+* @typeParam Data - Shape of the user-attached `data` field
+* @param handlers - Lifecycle handlers
+* @param options  - Server options including `port` and `hostname`
+* @returns A promise resolving to {@link ServeInfo}
+*
+* @internal
+*/
+async function serveNode(handlers, options) {
+	const { createServer: createHttpServer } = await import("node:http");
+	const wss = new WebSocketServer(handlers, options);
+	const httpServer = createHttpServer((_req, res) => {
+		res.writeHead(404);
+		res.end("Not found");
+	});
+	httpServer.on("upgrade", (req, socket, head) => {
+		const data = options?.resolveData ? options.resolveData(req) : void 0;
+		wss.upgrade({
+			rawRequest: req,
+			socket,
+			head
+		}, data ? { data } : void 0).catch(() => socket.destroy());
+	});
+	await new Promise((resolve) => httpServer.listen(options?.port ?? 0, options?.hostname ?? "0.0.0.0", resolve));
+	const port = httpServer.address()?.port ?? 0;
+	return {
+		port,
+		hostname: options?.hostname ?? "0.0.0.0",
+		url: new URL(`http://${options?.hostname ?? "0.0.0.0"}:${port}/`),
+		publish: (topic, message, _compress) => wss.publish(topic, message, _compress),
+		stop: (closeActiveConnections) => {
+			wss.close(closeActiveConnections);
+			httpServer.close();
+		}
+	};
+}
+/**
+* Coerce a {@link WSMessage} into a form that {@link NativeSocket.send} accepts.
 *
 * @param message - User-supplied payload
-* @returns A `string`, `Buffer` or `Uint8Array` ready to be sent
+* @returns A `string`, `Buffer` or `Uint8Array` ready to be framed
 *
 * @internal
 */
@@ -233,5 +737,6 @@ function toSendable(message) {
 }
 //#endregion
 exports.WebSocketServer = WebSocketServer;
+exports.serve = serve;
 
 //# sourceMappingURL=server.cjs.map