@wooksjs/event-ws 0.7.0

package/dist/index.mjs

@@ -0,0 +1,677 @@
+import { EventContext, current, defineEventKind, defineWook, key, routeParamsKey, run, slot, useLogger, useRouteParams, useRouteParams as useRouteParams$1 } from "@wooksjs/event-core";
+import http from "http";
+import { WooksAdapterBase } from "wooks";
+import { WebSocketServer } from "ws";
+
+//#region packages/event-ws/src/ws-kind.ts
+/** Event kind for WebSocket connections (long-lived, one per client). */
+const wsConnectionKind = defineEventKind("ws:connection", {
+	id: slot(),
+	ws: slot()
+});
+/** Event kind for WebSocket messages (short-lived, one per incoming message). */
+const wsMessageKind = defineEventKind("ws:message", {
+	data: slot(),
+	rawMessage: slot(),
+	messageId: slot(),
+	messagePath: slot(),
+	messageEvent: slot()
+});
+
+//#endregion
+//#region packages/event-ws/src/composables/state.ts
+let state;
+/** Called by the WooksWs adapter to expose state to composables. */
+function setAdapterState(s) {
+	state = s;
+}
+/** Called by composables to access adapter state. Throws if adapter not initialized. */
+function getAdapterState() {
+	if (!state) throw new Error("[event-ws] No active WooksWs adapter");
+	return state;
+}
+
+//#endregion
+//#region packages/event-ws/src/composables/connection.ts
+/**
+* Returns the connection `EventContext` from either connection-level or message-level handlers.
+* Mirrors `current()` from `@wooksjs/event-core`.
+*
+* - In `onConnect` / `onDisconnect`: returns `current()` directly.
+* - In `onMessage`: returns `current().parent` (the connection context).
+*/
+function currentConnection(ctx) {
+	const c = ctx ?? current();
+	return c.parent ?? c;
+}
+/**
+* Provides access to the current WebSocket connection (id, send, close).
+* Works in both connection and message contexts via parent chain traversal.
+*/
+const useWsConnection = defineWook((ctx) => {
+	const id = ctx.get(wsConnectionKind.keys.id);
+	const ws = ctx.get(wsConnectionKind.keys.ws);
+	const state$1 = getAdapterState();
+	const connection = state$1.connections.get(id);
+	return {
+		id,
+		send(event, path, data, params) {
+			connection.send(event, path, data, params);
+		},
+		close(code, reason) {
+			ws.close(code, reason);
+		},
+		context: currentConnection(ctx)
+	};
+});
+
+//#endregion
+//#region packages/event-ws/src/composables/message.ts
+/**
+* Provides access to the current WebSocket message data.
+* Only available in message context (inside `onMessage` handlers).
+*/
+function useWsMessage(ctx) {
+	return useWsMessageInternal(ctx);
+}
+const useWsMessageInternal = defineWook((ctx) => {
+	return {
+		data: ctx.get(wsMessageKind.keys.data),
+		raw: ctx.get(wsMessageKind.keys.rawMessage),
+		id: ctx.get(wsMessageKind.keys.messageId),
+		path: ctx.get(wsMessageKind.keys.messagePath),
+		event: ctx.get(wsMessageKind.keys.messageEvent)
+	};
+});
+
+//#endregion
+//#region packages/event-ws/src/composables/rooms.ts
+/**
+* Provides room management for the current connection.
+* All methods default to the current message path as the room.
+* Only available in message context (inside `onMessage` handlers).
+*/
+const useWsRooms = defineWook((ctx) => {
+	const messagePath = ctx.get(wsMessageKind.keys.messagePath);
+	const connectionId = ctx.get(wsConnectionKind.keys.id);
+	const state$1 = getAdapterState();
+	const connection = state$1.connections.get(connectionId);
+	return {
+		join(room) {
+			state$1.roomManager.join(connection, room ?? messagePath);
+		},
+		leave(room) {
+			state$1.roomManager.leave(connection, room ?? messagePath);
+		},
+		broadcast(event, data, options) {
+			const room = options?.room ?? messagePath;
+			const excludeSelf = options?.excludeSelf ?? true;
+			let params;
+			try {
+				const rp = useRouteParams$1(ctx);
+				const p = rp.params;
+				if (Object.keys(p).length > 0) params = p;
+			} catch {}
+			state$1.roomManager.broadcast(room, event, room, data, params, excludeSelf ? connection : void 0);
+		},
+		rooms() {
+			return [...connection.rooms];
+		}
+	};
+});
+
+//#endregion
+//#region packages/event-ws/src/composables/server.ts
+/**
+* Provides server-wide operations. Available in any context.
+* Not a `defineWook` — reads directly from the adapter state.
+*/
+function useWsServer() {
+	const state$1 = getAdapterState();
+	return {
+		connections() {
+			return state$1.connections;
+		},
+		broadcast(event, path, data, params) {
+			for (const conn of state$1.connections.values()) conn.send(event, path, data, params);
+		},
+		getConnection(id) {
+			return state$1.connections.get(id);
+		},
+		roomConnections(room) {
+			return state$1.roomManager.connections(room);
+		}
+	};
+}
+
+//#endregion
+//#region packages/event-ws/src/adapters/ws-adapter-default.ts
+/** Creates the default WsServerAdapter wrapping the `ws` package (peer dependency). */
+function createDefaultWsServerAdapter() {
+	return { create() {
+		const wss = new WebSocketServer({ noServer: true });
+		return {
+			handleUpgrade: (req, socket, head, cb) => {
+				wss.handleUpgrade(req, socket, head, (ws) => {
+					cb(ws);
+				});
+			},
+			close: () => {
+				wss.close();
+			}
+		};
+	} };
+}
+
+//#endregion
+//#region packages/event-ws/src/ws-connection.ts
+/** Internal class representing a connected WebSocket client. */
+var WsConnection = class {
+	rooms = /* @__PURE__ */ new Set();
+	alive = true;
+	constructor(id, ws, ctx, serializer) {
+		this.id = id;
+		this.ws = ws;
+		this.ctx = ctx;
+		this.serializer = serializer;
+	}
+	/** Send a push message to this connection. */
+	send(event, path, data, params) {
+		if (this.ws.readyState !== 1) return;
+		const msg = {
+			event,
+			path
+		};
+		if (params) msg.params = params;
+		if (data !== void 0) msg.data = data;
+		this.ws.send(this.serializer(msg));
+	}
+	/** Send a reply to a client request. */
+	reply(id, data) {
+		if (this.ws.readyState !== 1) return;
+		const msg = { id };
+		if (data !== void 0) msg.data = data;
+		this.ws.send(this.serializer(msg));
+	}
+	/** Send an error reply to a client request. */
+	replyError(id, code, message) {
+		if (this.ws.readyState !== 1) return;
+		const msg = {
+			id,
+			error: {
+				code,
+				message
+			}
+		};
+		this.ws.send(this.serializer(msg));
+	}
+	/** Close the connection. */
+	close(code, reason) {
+		this.ws.close(code, reason);
+	}
+};
+
+//#endregion
+//#region packages/event-ws/src/ws-error.ts
+/** WebSocket error with a numeric code following HTTP conventions (401, 403, 404, 500, etc.). */
+var WsError = class extends Error {
+	constructor(code, message) {
+		super(message ?? `WsError ${code}`);
+		this.code = code;
+		this.name = "WsError";
+	}
+};
+
+//#endregion
+//#region packages/event-ws/src/ws-room-manager.ts
+/** Manages room → connections mapping with optional distributed broadcast transport. */
+var WsRoomManager = class {
+	rooms = /* @__PURE__ */ new Map();
+	constructor(transport) {
+		this.transport = transport;
+		if (transport) {}
+	}
+	/** Add a connection to a room. */
+	join(connection, room) {
+		connection.rooms.add(room);
+		let set = this.rooms.get(room);
+		if (!set) {
+			set = /* @__PURE__ */ new Set();
+			this.rooms.set(room, set);
+			if (this.transport) this.transport.subscribe(`ws:room:${room}`, (payload) => {
+				this.onTransportMessage(room, payload);
+			});
+		}
+		set.add(connection);
+	}
+	/** Remove a connection from a room. */
+	leave(connection, room) {
+		connection.rooms.delete(room);
+		const set = this.rooms.get(room);
+		if (!set) return;
+		set.delete(connection);
+		if (set.size === 0) {
+			this.rooms.delete(room);
+			if (this.transport) this.transport.unsubscribe(`ws:room:${room}`);
+		}
+	}
+	/** Remove a connection from ALL rooms (called on disconnect). */
+	leaveAll(connection) {
+		for (const room of connection.rooms) {
+			const set = this.rooms.get(room);
+			if (set) {
+				set.delete(connection);
+				if (set.size === 0) {
+					this.rooms.delete(room);
+					if (this.transport) this.transport.unsubscribe(`ws:room:${room}`);
+				}
+			}
+		}
+		connection.rooms.clear();
+	}
+	/** Get all connections in a room. */
+	connections(room) {
+		return this.rooms.get(room) ?? /* @__PURE__ */ new Set();
+	}
+	/** Broadcast to all connections in a room. */
+	broadcast(room, event, path, data, params, exclude) {
+		const set = this.rooms.get(room);
+		if (set) {
+			for (const conn of set) if (conn !== exclude) conn.send(event, path, data, params);
+		}
+		if (this.transport) {
+			const payload = JSON.stringify({
+				event,
+				path,
+				data,
+				params,
+				excludeId: exclude?.id
+			});
+			this.transport.publish(`ws:room:${room}`, payload);
+		}
+	}
+	/** Handle inbound message from broadcast transport (other instances). */
+	onTransportMessage(room, payload) {
+		const set = this.rooms.get(room);
+		if (!set || set.size === 0) return;
+		try {
+			const { event, path, data, params, excludeId } = JSON.parse(payload);
+			for (const conn of set) if (conn.id !== excludeId) conn.send(event, path, data, params);
+		} catch {}
+	}
+};
+
+//#endregion
+//#region packages/event-ws/src/ws-adapter.ts
+const DEFAULT_HEARTBEAT_INTERVAL = 3e4;
+const DEFAULT_MAX_MESSAGE_SIZE = 1024 * 1024;
+const upgradeReqKey = key("ws:upgrade-req");
+const upgradeSocketKey = key("ws:upgrade-socket");
+const upgradeHeadKey = key("ws:upgrade-head");
+/** WebSocket adapter for Wooks. Implements WooksUpgradeHandler for HTTP integration. */
+var WooksWs = class extends WooksAdapterBase {
+	logger;
+	eventContextOptions;
+	connections = /* @__PURE__ */ new Map();
+	roomManager;
+	wsServer;
+	opts;
+	serializer;
+	parser;
+	onConnectHandler;
+	onDisconnectHandler;
+	heartbeatTimer;
+	server;
+	reqKey = upgradeReqKey;
+	socketKey = upgradeSocketKey;
+	headKey = upgradeHeadKey;
+	constructor(wooksOrOpts, opts) {
+		const isWooks = wooksOrOpts instanceof WooksAdapterBase || wooksOrOpts && "getRouter" in wooksOrOpts;
+		const wooks = isWooks ? wooksOrOpts : void 0;
+		const resolvedOpts = isWooks ? opts ?? {} : wooksOrOpts ?? {};
+		super(wooks, resolvedOpts.logger, void 0);
+		if (wooksOrOpts && typeof wooksOrOpts.ws === "function") wooksOrOpts.ws(this);
+		this.opts = resolvedOpts;
+		this.logger = resolvedOpts.logger || this.getLogger(`[wooks-ws]`);
+		this.eventContextOptions = this.getEventContextOptions();
+		this.serializer = resolvedOpts.messageSerializer ?? JSON.stringify;
+		this.parser = resolvedOpts.messageParser ?? defaultParser;
+		this.roomManager = new WsRoomManager(resolvedOpts.broadcastTransport);
+		const adapter = resolvedOpts.wsServerAdapter ?? createDefaultWsServerAdapter();
+		this.wsServer = adapter.create();
+		setAdapterState({
+			connections: this.connections,
+			roomManager: this.roomManager,
+			serializer: this.serializer,
+			wooks: this.wooks
+		});
+	}
+	/** Register a handler that runs when a new WebSocket connection is established. */
+	onConnect(handler) {
+		this.onConnectHandler = handler;
+	}
+	/** Register a handler that runs when a WebSocket connection closes. */
+	onDisconnect(handler) {
+		this.onDisconnectHandler = handler;
+	}
+	/** Register a routed message handler. Uses the standard Wooks router internally. */
+	onMessage(event, path, handler) {
+		return this.on(event, path, handler);
+	}
+	/**
+	* Complete the WebSocket handshake from inside an UPGRADE route handler.
+	* Reads req/socket/head from the current HTTP context (set by the HTTP adapter).
+	* The HTTP context becomes the parent of the WS connection context.
+	*/
+	upgrade() {
+		const httpCtx = current();
+		const req = httpCtx.get(upgradeReqKey);
+		const socket = httpCtx.get(upgradeSocketKey);
+		const head = httpCtx.get(upgradeHeadKey);
+		this.doUpgrade(req, socket, head, httpCtx);
+	}
+	/**
+	* Fallback: called by the HTTP adapter when no UPGRADE route matches.
+	* Also used internally for standalone mode.
+	*/
+	handleUpgrade(req, socket, head) {
+		this.doUpgrade(req, socket, head);
+	}
+	/** Start a standalone server (without event-http). */
+	async listen(port, hostname) {
+		const server = this.server = http.createServer();
+		server.on("upgrade", (req, socket, head) => {
+			this.doUpgrade(req, socket, head);
+		});
+		this.startHeartbeat();
+		return new Promise((resolve, reject) => {
+			server.once("listening", resolve);
+			server.once("error", reject);
+			if (hostname) server.listen(port, hostname);
+			else server.listen(port);
+		});
+	}
+	/** Stop the server and clean up. */
+	close() {
+		this.stopHeartbeat();
+		this.wsServer.close();
+		for (const conn of this.connections.values()) conn.close(1001, "Server shutting down");
+		this.connections.clear();
+	}
+	/** Returns the underlying HTTP server (if any). */
+	getServer() {
+		return this.server;
+	}
+	doUpgrade(req, socket, head, parentCtx) {
+		this.wsServer.handleUpgrade(req, socket, head, (ws) => {
+			const id = crypto.randomUUID();
+			const ctxOptions = {
+				...this.eventContextOptions,
+				...parentCtx ? { parent: parentCtx } : {}
+			};
+			const connectionCtx = new EventContext(ctxOptions);
+			const connection = new WsConnection(id, ws, connectionCtx, this.serializer);
+			connectionCtx.seed(wsConnectionKind, {
+				id,
+				ws
+			});
+			try {
+				if (this.onConnectHandler) {
+					const result = run(connectionCtx, this.onConnectHandler);
+					if (result !== null && result !== void 0 && typeof result.then === "function") {
+						result.then(() => this.acceptConnection(connection)).catch((error) => this.rejectConnection(connection, error));
+						return;
+					}
+				}
+				this.acceptConnection(connection);
+			} catch (error) {
+				this.rejectConnection(connection, error);
+			}
+		});
+	}
+	acceptConnection(connection) {
+		this.connections.set(connection.id, connection);
+		this.logger.debug(`WS connected: ${connection.id}`);
+		const ws = connection.ws;
+		ws.on("message", (raw) => {
+			this.handleMessage(connection, raw);
+		});
+		ws.on("close", () => {
+			this.handleClose(connection);
+		});
+		ws.on("error", (err) => {
+			this.logger.error(`WS error [${connection.id}]:`, err);
+		});
+		ws.on("pong", () => {
+			connection.alive = true;
+		});
+	}
+	rejectConnection(connection, error) {
+		const code = error instanceof WsError ? error.code : 500;
+		const message = error instanceof Error ? error.message : "Connection rejected";
+		this.logger.debug(`WS rejected: ${message}`);
+		const wsCloseCode = code === 401 || code === 403 ? 1008 : 1011;
+		connection.close(wsCloseCode, message);
+	}
+	handleMessage(connection, raw) {
+		const maxSize = this.opts.maxMessageSize ?? DEFAULT_MAX_MESSAGE_SIZE;
+		const size = typeof raw === "string" ? Buffer.byteLength(raw) : raw.length;
+		if (size > maxSize) {
+			this.logger.debug(`WS message too large (${size} > ${maxSize}), dropping`);
+			return;
+		}
+		let msg;
+		try {
+			msg = this.parser(raw);
+		} catch {
+			this.logger.debug("WS message parse failed, dropping");
+			return;
+		}
+		const { event, path, data, id: messageId } = msg;
+		const msgCtx = new EventContext({
+			...this.eventContextOptions,
+			parent: connection.ctx
+		});
+		msgCtx.seed(wsMessageKind, {
+			data,
+			rawMessage: raw,
+			messageId,
+			messagePath: path,
+			messageEvent: event
+		});
+		run(msgCtx, () => {
+			const handlers = this.wooks.lookupHandlers(event, path, msgCtx);
+			if (!handlers) {
+				if (messageId !== void 0) connection.replyError(messageId, 404, "Not found");
+				return;
+			}
+			const result = this.processHandlers(handlers, connection, messageId);
+			if (result !== null && result !== void 0 && typeof result.then === "function") result.catch((error) => {
+				this.handleHandlerError(error, connection, messageId);
+			});
+		});
+	}
+	processHandlers(handlers, connection, messageId) {
+		for (let i = 0; i < handlers.length; i++) {
+			const handler = handlers[i];
+			const isLast = i === handlers.length - 1;
+			try {
+				const result = handler();
+				if (result !== null && result !== void 0 && typeof result.then === "function") return this.processAsyncResult(result, handlers, i, connection, messageId);
+				this.sendReply(connection, messageId, result);
+				return;
+			} catch (error) {
+				if (isLast) {
+					this.handleHandlerError(error, connection, messageId);
+					return;
+				}
+			}
+		}
+	}
+	async processAsyncResult(promise, handlers, startIndex, connection, messageId) {
+		try {
+			const result = await promise;
+			this.sendReply(connection, messageId, result);
+			return;
+		} catch (error) {
+			if (startIndex === handlers.length - 1) {
+				this.handleHandlerError(error, connection, messageId);
+				return;
+			}
+		}
+		for (let i = startIndex + 1; i < handlers.length; i++) {
+			const isLast = i === handlers.length - 1;
+			try {
+				const result = await handlers[i]();
+				this.sendReply(connection, messageId, result);
+				return;
+			} catch (error) {
+				if (isLast) {
+					this.handleHandlerError(error, connection, messageId);
+					return;
+				}
+			}
+		}
+	}
+	sendReply(connection, messageId, data) {
+		if (messageId === void 0) return;
+		connection.reply(messageId, data ?? null);
+	}
+	handleHandlerError(error, connection, messageId) {
+		const code = error instanceof WsError ? error.code : 500;
+		const message = error instanceof WsError ? error.message : "Internal Error";
+		if (messageId !== void 0) connection.replyError(messageId, code, message);
+		if (!(error instanceof WsError)) this.logger.error("Uncaught WS handler error:", error);
+	}
+	handleClose(connection) {
+		this.logger.debug(`WS disconnected: ${connection.id}`);
+		if (this.onDisconnectHandler) try {
+			const result = run(connection.ctx, this.onDisconnectHandler);
+			if (result !== null && result !== void 0 && typeof result.then === "function") result.catch((error) => {
+				this.logger.error("onDisconnect error:", error);
+			});
+		} catch (error) {
+			this.logger.error("onDisconnect error:", error);
+		}
+		this.roomManager.leaveAll(connection);
+		this.connections.delete(connection.id);
+	}
+	startHeartbeat() {
+		const interval = this.opts.heartbeatInterval ?? DEFAULT_HEARTBEAT_INTERVAL;
+		if (interval === 0) return;
+		this.heartbeatTimer = setInterval(() => {
+			for (const conn of this.connections.values()) {
+				if (!conn.alive) {
+					this.logger.debug(`WS heartbeat timeout: ${conn.id}`);
+					conn.ws.close(1001, "Heartbeat timeout");
+					continue;
+				}
+				conn.alive = false;
+				conn.ws.ping();
+			}
+		}, interval);
+		if (this.heartbeatTimer.unref) this.heartbeatTimer.unref();
+	}
+	stopHeartbeat() {
+		if (this.heartbeatTimer) {
+			clearInterval(this.heartbeatTimer);
+			this.heartbeatTimer = void 0;
+		}
+	}
+};
+function defaultParser(raw) {
+	const str = typeof raw === "string" ? raw : raw.toString("utf8");
+	const parsed = JSON.parse(str);
+	if (typeof parsed.event !== "string" || typeof parsed.path !== "string") throw new TypeError("Invalid WS message: missing event or path");
+	return parsed;
+}
+/**
+* Creates a new WooksWs WebSocket adapter.
+*
+* @example Integrated with HTTP (recommended):
+* ```ts
+* const http = createHttpApp()
+* const ws = createWsApp(http) // auto-registers upgrade contract
+* http.upgrade('/ws', () => ws.upgrade())
+* http.listen(3000)
+* ```
+*
+* @example Standalone:
+* ```ts
+* const ws = createWsApp({ heartbeatInterval: 30_000 })
+* ws.listen(3000)
+* ```
+*/
+function createWsApp(wooksOrOpts, opts) {
+	return new WooksWs(wooksOrOpts, opts);
+}
+
+//#endregion
+//#region packages/event-ws/src/testing.ts
+/** Creates a mock WsSocket for testing. */
+function createMockWsSocket() {
+	return {
+		send: () => {},
+		close: () => {},
+		on: () => {},
+		ping: () => {},
+		readyState: 1
+	};
+}
+/**
+* Creates a fully initialized WS connection context for testing.
+* Returns a runner function that executes callbacks inside the context scope.
+*/
+function prepareTestWsConnectionContext(options) {
+	const id = options?.id ?? "test-conn-id";
+	const ws = createMockWsSocket();
+	const ctx = new EventContext({
+		logger: console,
+		...options?.parentCtx ? { parent: options.parentCtx } : {}
+	});
+	ctx.seed(wsConnectionKind, {
+		id,
+		ws
+	});
+	if (options?.params) ctx.set(routeParamsKey, options.params);
+	return (cb) => run(ctx, cb);
+}
+/**
+* Creates a fully initialized WS message context for testing.
+* Sets up both connection context (parent) and message context (child).
+* Returns a runner function that executes callbacks inside the message context scope.
+*/
+function prepareTestWsMessageContext(options) {
+	const id = options.id ?? "test-conn-id";
+	const ws = createMockWsSocket();
+	const connectionCtx = new EventContext({
+		logger: console,
+		...options.parentCtx ? { parent: options.parentCtx } : {}
+	});
+	connectionCtx.seed(wsConnectionKind, {
+		id,
+		ws
+	});
+	const messageCtx = new EventContext({
+		logger: console,
+		parent: connectionCtx
+	});
+	const rawMessage = options.rawMessage ?? JSON.stringify({
+		event: options.event,
+		path: options.path,
+		data: options.data,
+		id: options.messageId
+	});
+	messageCtx.seed(wsMessageKind, {
+		data: options.data,
+		rawMessage,
+		messageId: options.messageId,
+		messagePath: options.path,
+		messageEvent: options.event
+	});
+	if (options.params) messageCtx.set(routeParamsKey, options.params);
+	return (cb) => run(messageCtx, cb);
+}
+
+//#endregion
+export { WooksWs, WsConnection, WsError, WsRoomManager, createWsApp, currentConnection, prepareTestWsConnectionContext, prepareTestWsMessageContext, useLogger, useRouteParams, useWsConnection, useWsMessage, useWsRooms, useWsServer, wsConnectionKind, wsMessageKind };