silgi 0.53.0 → 0.53.2

package/dist/ws.mjs

@@ -1,64 +1,132 @@
 import { SilgiError, toSilgiError } from "./core/error.mjs";
-import { compileRouter, createContext, releaseContext } from "./compile.mjs";
+import { compileRouter } from "./compile.mjs";
 import { stringifyJSON } from "./core/utils.mjs";
 import { decode, encode } from "./codec/msgpack.mjs";
 //#region src/ws.ts
 /**
-* WebSocket RPC adapter — powered by crossws.
+* WebSocket RPC adapter
+* -----------------------
 *
-* Bidirectional type-safe RPC over WebSocket.
-* Supports subscriptions (server → client streaming) natively.
+* Exposes silgi procedures over a WebSocket connection using the
+* `crossws` runtime-agnostic adapter underneath. Every procedure
+* registered via `router()` is reachable — no opt-in flag required.
 *
-* Protocol:
-*   Client → Server: { id: string, path: string, input?: unknown }
-*   Server → Client: { id: string, result?: unknown, error?: unknown }
-*   Server → Client (stream): { id: string, data: unknown, done?: boolean }
+* Wire protocol
+* -------------
+*
+*   Client → Server:  { id, path, input? }
+*   Server → Client:  { id, result?, error? }                  (single value)
+*   Server → Client:  { id, data, done? }                      (streaming chunk)
+*
+* Requests are correlated by `id`. A subscription (any resolver that returns
+* an async iterable) streams back one `{ id, data }` frame per yielded
+* value, followed by a terminal `{ id, data: null, done: true }`. Clients
+* close a subscription by closing the socket; the peer disconnect aborts
+* every in-flight resolver for that peer.
+*
+* Two encodings are supported: UTF-8 JSON (default) and binary MessagePack.
+* The choice is per-adapter, not per-message.
 */
 /**
-* Internal — build crossws-compatible hooks for Silgi RPC over WebSocket.
+* Build the crossws hook set that implements silgi's WebSocket RPC.
 *
-* Used by `attachWebSocket()`, `serve({ ws: true })`, and `handler()` auto-WS.
-* Not part of the public API; callers should use one of those higher-level entry points.
+* @internal
+*
+* This is not part of the public API — `silgi({...}).handler()`,
+* `serve({ ws: true })`, and `attachWebSocket()` are the three supported
+* entry points. They all go through this builder so protocol behavior
+* stays identical everywhere.
 */
-/** @internal — exported only for use by silgi.ts handler() and attachWebSocket(). Not part of the public API. */
 function _createWSHooks(routerDef, options = {}) {
-	const flat = compileRouter(routerDef);
+	const compiled = compileRouter(routerDef);
 	const useMsgpack = options.protocol === "messagepack" || options.protocol == null && (options.binary ?? false);
 	const contextFactory = options.context;
 	const keepaliveMs = options.keepalive === false ? 0 : options.keepalive ?? 3e4;
 	const peerAbortControllers = /* @__PURE__ */ new WeakMap();
 	const peerKeepaliveTimers = /* @__PURE__ */ new WeakMap();
-	function send(peer, data) {
+	/** Send a single frame, applying the peer's chosen encoding and compression. */
+	const send = (peer, data) => {
 		const compress = !!options.compress;
 		if (useMsgpack) peer.send(encode(data), { compress });
 		else peer.send(stringifyJSON(data), { compress });
-	}
-	function parseMessage(message) {
+	};
+	/** Decode an incoming frame into an `RPCRequest`. Throws on parse error. */
+	const parseMessage = (message) => {
 		if (useMsgpack) return decode(message.uint8Array());
 		return message.json();
-	}
+	};
+	/**
+	* Build the per-request context.
+	*
+	* Isolated here so the message handler stays readable; the caller
+	* handles send-back-error on failure.
+	*/
+	const buildContext = async (peer) => {
+		const ctx = Object.create(null);
+		if (contextFactory) {
+			const base = await contextFactory(peer);
+			for (const key of Object.keys(base)) ctx[key] = base[key];
+		}
+		return ctx;
+	};
+	/**
+	* Stream a subscription result back to the peer. Returns when the
+	* iterator is exhausted, the peer disconnects, or the resolver throws.
+	*
+	* `iter.return?.()` is called in `finally` so the resolver's cleanup
+	* (database cursors, external watchers, etc.) runs even on disconnect.
+	*/
+	const streamSubscription = async (peer, id, iter, signal) => {
+		try {
+			for await (const data of iter) {
+				if (signal.aborted) break;
+				send(peer, {
+					id,
+					data
+				});
+			}
+			if (!signal.aborted) send(peer, {
+				id,
+				data: null,
+				done: true
+			});
+		} catch (err) {
+			if (!signal.aborted) send(peer, {
+				id,
+				error: toClientError(err)
+			});
+		} finally {
+			await iter.return?.();
+		}
+	};
+	/**
+	* Install a keepalive ping loop on a peer, if the runtime gives us
+	* access to the underlying `ws` instance. Silently no-ops when it
+	* does not — some adapters (e.g. Bun) do not expose that handle.
+	*/
+	const installKeepalive = (peer) => {
+		if (keepaliveMs <= 0) return;
+		const ws = peer._internal?.ws;
+		if (!ws || typeof ws.ping !== "function" || typeof ws.on !== "function" || typeof ws.terminate !== "function") return;
+		let alive = true;
+		ws.on("pong", () => {
+			alive = true;
+		});
+		const timer = setInterval(() => {
+			if (!alive) {
+				clearInterval(timer);
+				ws.terminate();
+				return;
+			}
+			alive = false;
+			ws.ping();
+		}, keepaliveMs);
+		peerKeepaliveTimers.set(peer, timer);
+	};
 	return {
 		open(peer) {
 			peerAbortControllers.set(peer, /* @__PURE__ */ new Set());
-			if (keepaliveMs > 0) {
-				const ws = peer._internal?.ws;
-				if (ws && typeof ws.ping === "function") {
-					let alive = true;
-					ws.on("pong", () => {
-						alive = true;
-					});
-					const timer = setInterval(() => {
-						if (!alive) {
-							clearInterval(timer);
-							ws.terminate();
-							return;
-						}
-						alive = false;
-						ws.ping();
-					}, keepaliveMs);
-					peerKeepaliveTimers.set(peer, timer);
-				}
-			}
+			installKeepalive(peer);
 		},
 		async message(peer, message) {
 			let req;
@@ -76,7 +144,7 @@ function _createWSHooks(routerDef, options = {}) {
 				return;
 			}
 			const { id, path, input } = req;
-			const route = flat("POST", "/" + path)?.data;
+			const route = compiled("POST", "/" + path)?.data;
 			if (!route) {
 				send(peer, {
 					id,
@@ -88,66 +156,35 @@ function _createWSHooks(routerDef, options = {}) {
 				});
 				return;
 			}
-			const ctx = createContext();
-			if (contextFactory) try {
-				const baseResult = contextFactory(peer);
-				const base = baseResult instanceof Promise ? await baseResult : baseResult;
-				const keys = Object.keys(base);
-				for (let i = 0; i < keys.length; i++) ctx[keys[i]] = base[keys[i]];
+			let ctx;
+			try {
+				ctx = await buildContext(peer);
 			} catch (err) {
-				releaseContext(ctx);
 				send(peer, {
 					id,
-					error: (err instanceof SilgiError ? err : toSilgiError(err)).toJSON()
+					error: toClientError(err)
 				});
 				return;
 			}
 			const ac = new AbortController();
-			const controllers = peerAbortControllers.get(peer);
-			controllers?.add(ac);
+			peerAbortControllers.get(peer)?.add(ac);
 			try {
-				const result = route.handler(ctx, input ?? {}, ac.signal);
-				const output = result instanceof Promise ? await result : result;
-				if (output && typeof output === "object" && Symbol.asyncIterator in output) {
-					const iter = output;
-					try {
-						for await (const data of iter) {
-							if (ac.signal.aborted) break;
-							send(peer, {
-								id,
-								data
-							});
-						}
-						if (!ac.signal.aborted) send(peer, {
-							id,
-							data: null,
-							done: true
-						});
-					} catch (err) {
-						if (!ac.signal.aborted) send(peer, {
-							id,
-							error: (err instanceof SilgiError ? err : toSilgiError(err)).toJSON()
-						});
-					} finally {
-						await iter.return?.();
-					}
-					return;
-				}
-				send(peer, {
+				const output = await route.handler(ctx, input ?? {}, ac.signal);
+				if (output && typeof output === "object" && Symbol.asyncIterator in output) await streamSubscription(peer, id, output, ac.signal);
+				else send(peer, {
 					id,
 					result: output
 				});
 			} catch (err) {
 				send(peer, {
 					id,
-					error: (err instanceof SilgiError ? err : toSilgiError(err)).toJSON()
+					error: toClientError(err)
 				});
 			} finally {
-				controllers?.delete(ac);
-				releaseContext(ctx);
+				peerAbortControllers.get(peer)?.delete(ac);
 			}
 		},
-		close(peer, _details) {
+		close(peer) {
 			const timer = peerKeepaliveTimers.get(peer);
 			if (timer) {
 				clearInterval(timer);
@@ -165,18 +202,20 @@ function _createWSHooks(routerDef, options = {}) {
 		}
 	};
 }
+/** Normalize any thrown value into the `{ code, status, message, ... }` shape clients expect. */
+function toClientError(err) {
+	return (err instanceof SilgiError ? err : toSilgiError(err)).toJSON();
+}
 /**
-* Attach WebSocket RPC handler to an existing Node.js HTTP server.
+* Attach silgi's WebSocket RPC to an existing Node.js `http.Server`.
 *
 * @example
-* ```ts
-* import { createServer } from "node:http";
-* import { attachWebSocket } from "silgi/ws";
+*   import { createServer } from 'node:http'
+*   import { attachWebSocket } from 'silgi/ws'
 *
-* const server = createServer(httpHandler);
-* attachWebSocket(server, appRouter);
-* server.listen(3000);
-* ```
+*   const server = createServer(httpHandler)
+*   await attachWebSocket(server, appRouter)
+*   server.listen(3000)
 */
 async function attachWebSocket(server, routerDef, options = {}) {
 	const nodeAdapter = (await import("crossws/adapters/node")).default;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "silgi",
-  "version": "0.53.0",
+  "version": "0.53.2",
   "private": false,
   "description": "The fastest end-to-end type-safe RPC framework for TypeScript — compiled pipelines, single package, every runtime",
   "keywords": [