@askrjs/node 0.0.8 → 0.0.11

package/dist/mcp.d.ts

@@ -2,21 +2,47 @@ import { Readable, Writable } from "node:stream";
 import { AuthContext } from "@askrjs/auth";
 import { McpServer } from "@askrjs/server/mcp";
 //#region src/mcp.d.ts
+/** Options for {@link connectMcpStdio}. */
 interface McpStdioOptions<Dependencies = undefined> {
+  /** Application dependencies passed through to each MCP request. */
   dependencies: Dependencies;
+  /** Stream to read newline-delimited JSON-RPC requests from; defaults to `process.stdin`. */
   input?: Readable;
+  /** Stream to write newline-delimited JSON-RPC responses to; defaults to `process.stdout`. */
   output?: Writable;
+  /** Stream that non-protocol errors are reported to; defaults to `process.stderr`. */
   diagnostics?: Writable;
+  /** Aborting this signal closes the connection. */
   signal?: AbortSignal;
+  /** Auth context to use for requests, or a function that derives one from the environment. */
   auth?: AuthContext | ((environment: NodeJS.ProcessEnv) => AuthContext | Promise<AuthContext>);
+  /** Environment passed to the `auth` function; defaults to `process.env`. */
   environment?: NodeJS.ProcessEnv;
+  /** Maximum size, in bytes, of a single input line before it is rejected; defaults to 1 MiB. */
   maxLineBytes?: number;
+  /** Maximum number of requests handled concurrently; defaults to 16. */
   maxConcurrency?: number;
 }
+/** A live MCP stdio connection returned by {@link connectMcpStdio}. */
 interface McpStdioConnection {
+  /** Resolves once the connection has fully closed. */
   readonly closed: Promise<void>;
+  /** Closes the connection, aborting in-flight requests and terminating the MCP session. */
   close(): Promise<void>;
 }
+/**
+ * Connects an MCP server to newline-delimited JSON-RPC over stdio (or any
+ * pair of readable/writable streams).
+ *
+ * Reads one JSON-RPC message per line, dispatches it to `mcp.handle`, and
+ * writes the response back as a line of JSON. Handles request cancellation
+ * notifications, enforces `maxConcurrency` and `maxLineBytes`, and cleans up
+ * the MCP session when the connection closes.
+ *
+ * @param mcp - The MCP server to dispatch requests to.
+ * @param options - Stdio connection options, including dependencies and stream overrides.
+ * @returns A handle exposing `closed` and `close()` for the connection's lifecycle.
+ */
 declare function connectMcpStdio<Dependencies>(mcp: McpServer<Dependencies>, options: McpStdioOptions<Dependencies>): McpStdioConnection;
 //#endregion
 export { McpStdioConnection, McpStdioOptions, connectMcpStdio };

package/dist/mcp.js

@@ -1,3 +1,5 @@
+import { addAbortListener } from "node:events";
+import { randomUUID } from "node:crypto";
 //#region src/mcp.ts
 const anonymous = Object.freeze({
 	authenticated: false,
@@ -5,12 +7,25 @@ const anonymous = Object.freeze({
 	session: null,
 	tenant: null
 });
+/**
+* Connects an MCP server to newline-delimited JSON-RPC over stdio (or any
+* pair of readable/writable streams).
+*
+* Reads one JSON-RPC message per line, dispatches it to `mcp.handle`, and
+* writes the response back as a line of JSON. Handles request cancellation
+* notifications, enforces `maxConcurrency` and `maxLineBytes`, and cleans up
+* the MCP session when the connection closes.
+*
+* @param mcp - The MCP server to dispatch requests to.
+* @param options - Stdio connection options, including dependencies and stream overrides.
+* @returns A handle exposing `closed` and `close()` for the connection's lifecycle.
+*/
 function connectMcpStdio(mcp, options) {
 	const input = options.input ?? process.stdin;
 	const output = options.output ?? process.stdout;
 	const diagnostics = options.diagnostics ?? process.stderr;
 	const controllers = /* @__PURE__ */ new Map();
-	const sessionId = crypto.randomUUID();
+	const sessionId = randomUUID();
 	let finish;
 	const closed = new Promise((resolve) => {
 		finish = resolve;
@@ -18,31 +33,73 @@ function connectMcpStdio(mcp, options) {
 	let ended = false;
 	const maxLineBytes = options.maxLineBytes ?? 1048576;
 	const maxConcurrency = options.maxConcurrency ?? 16;
-	if (!Number.isInteger(maxLineBytes) || maxLineBytes <= 0) throw new TypeError("MCP maxLineBytes must be a positive integer.");
-	if (!Number.isInteger(maxConcurrency) || maxConcurrency <= 0) throw new TypeError("MCP maxConcurrency must be a positive integer.");
+	if (!Number.isSafeInteger(maxLineBytes) || maxLineBytes <= 0) throw new TypeError("MCP maxLineBytes must be a positive integer.");
+	if (!Number.isSafeInteger(maxConcurrency) || maxConcurrency <= 0) throw new TypeError("MCP maxConcurrency must be a positive integer.");
 	let active = 0;
-	let cleanupInput = () => void 0;
-	const write = (message) => new Promise((resolve, reject) => {
-		output.write(`${JSON.stringify(message)}\n`, (error) => error ? reject(error) : resolve());
-	});
+	let abortListener;
+	let cleanupTransport = () => void 0;
+	const report = (error) => {
+		try {
+			diagnostics.write(`MCP stdio error: ${error instanceof Error ? error.message : String(error)}\n`);
+		} catch {}
+	};
+	const write = (message) => {
+		if (ended) return Promise.reject(/* @__PURE__ */ new Error("MCP stdio connection is closed."));
+		return new Promise((resolve, reject) => {
+			output.write(`${JSON.stringify(message)}\n`, (error) => error ? reject(error) : resolve());
+		});
+	};
 	const close = async () => {
 		if (ended) return closed;
 		ended = true;
-		cleanupInput();
-		for (const controller of controllers.values()) controller.abort();
+		cleanupTransport();
+		abortListener?.[Symbol.dispose]();
+		for (const values of controllers.values()) for (const controller of values) controller.abort();
 		controllers.clear();
-		mcp.terminateSession(sessionId);
-		finish();
+		try {
+			mcp.terminateSession(sessionId);
+		} catch (error) {
+			report(error);
+		} finally {
+			finish();
+		}
 		return closed;
 	};
-	options.signal?.addEventListener("abort", () => void close(), { once: true });
+	if (options.signal) abortListener = addAbortListener(options.signal, () => void close());
+	const writeProtocolError = (code, message) => write({
+		jsonrpc: "2.0",
+		id: null,
+		error: {
+			code,
+			message
+		}
+	});
 	const handleLine = (line) => {
+		if (ended) return;
+		let message;
+		try {
+			message = JSON.parse(line);
+		} catch {
+			writeProtocolError(-32700, "Parse error").catch(() => void close());
+			return;
+		}
+		if (!message || typeof message !== "object" || Array.isArray(message)) {
+			writeProtocolError(-32600, "Invalid Request").catch(() => void close());
+			return;
+		}
+		const value = message;
+		if (value.method === "notifications/cancelled" && value.params && typeof value.params === "object") {
+			const requestId = value.params.requestId;
+			if (typeof requestId === "string" || typeof requestId === "number") for (const controller of controllers.get(requestId) ?? []) controller.abort();
+			return;
+		}
+		const id = value.id;
 		if (active >= maxConcurrency) {
-			write({
+			if (typeof id === "string" || typeof id === "number") write({
 				jsonrpc: "2.0",
-				id: null,
+				id,
 				error: {
-					code: -32600,
+					code: -32e3,
 					message: "Too many concurrent requests"
 				}
 			}).catch(() => void close());
@@ -50,51 +107,52 @@ function connectMcpStdio(mcp, options) {
 		}
 		active += 1;
 		(async () => {
-			let message;
+			const controller = typeof id === "string" || typeof id === "number" ? new AbortController() : void 0;
+			if (controller && (typeof id === "string" || typeof id === "number")) {
+				const values = controllers.get(id) ?? /* @__PURE__ */ new Set();
+				values.add(controller);
+				controllers.set(id, values);
+			}
 			try {
-				message = JSON.parse(line);
-			} catch {
-				await write({
-					jsonrpc: "2.0",
-					id: null,
-					error: {
-						code: -32700,
-						message: "Parse error"
-					}
+				const environment = options.environment ?? process.env;
+				const auth = typeof options.auth === "function" ? await options.auth(environment) : options.auth ?? anonymous;
+				const result = await mcp.handle(message, {
+					dependencies: options.dependencies,
+					auth,
+					transport: "stdio",
+					sessionId,
+					supportsPush: true,
+					signal: controller?.signal ?? options.signal,
+					send: write
 				});
-				return;
-			}
-			if (message && typeof message === "object") {
-				const value = message;
-				if (value.method === "notifications/cancelled" && value.params && typeof value.params === "object") {
-					const requestId = value.params.requestId;
-					if (typeof requestId === "string" || typeof requestId === "number") controllers.get(requestId)?.abort();
-				}
-				const id = value.id;
-				const controller = typeof id === "string" || typeof id === "number" ? new AbortController() : void 0;
-				if (controller && (typeof id === "string" || typeof id === "number")) controllers.set(id, controller);
-				try {
-					const environment = options.environment ?? process.env;
-					const auth = typeof options.auth === "function" ? await options.auth(environment) : options.auth ?? anonymous;
-					const result = await mcp.handle(message, {
-						dependencies: options.dependencies,
-						auth,
-						transport: "stdio",
-						sessionId,
-						supportsPush: true,
-						signal: controller?.signal ?? options.signal,
-						send: write
+				if (result !== void 0 && !ended) await write(result);
+			} catch (error) {
+				if (!ended) {
+					report(error);
+					if (typeof id === "string" || typeof id === "number") await write({
+						jsonrpc: "2.0",
+						id,
+						error: {
+							code: -32603,
+							message: "Internal error"
+						}
 					});
-					if (result !== void 0) await write(result);
-				} finally {
-					if (controller && id !== void 0) controllers.delete(id);
+				}
+			} finally {
+				if (controller && (typeof id === "string" || typeof id === "number")) {
+					const values = controllers.get(id);
+					values?.delete(controller);
+					if (values?.size === 0) controllers.delete(id);
 				}
 			}
-		})().catch((error) => diagnostics.write(`MCP stdio error: ${error instanceof Error ? error.message : String(error)}\n`)).finally(() => {
+		})().catch((error) => {
+			if (!ended) report(error);
+		}).finally(() => {
 			active -= 1;
 		});
 	};
 	const lineBuffer = Buffer.allocUnsafe(maxLineBytes);
+	const decoder = new TextDecoder("utf-8", { fatal: true });
 	let lineBytes = 0;
 	let discardingOversizedLine = false;
 	const rejectOversizedLine = () => {
@@ -108,6 +166,7 @@ function connectMcpStdio(mcp, options) {
 		}).catch(() => void close());
 	};
 	const onData = (chunk) => {
+		if (ended) return;
 		const bytes = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
 		let offset = 0;
 		while (offset < bytes.byteLength) {
@@ -127,29 +186,39 @@ function connectMcpStdio(mcp, options) {
 			if (newline < 0) break;
 			if (!discardingOversizedLine) {
 				const length = lineBytes > 0 && lineBuffer[lineBytes - 1] === 13 ? lineBytes - 1 : lineBytes;
-				handleLine(lineBuffer.subarray(0, length).toString("utf8"));
+				try {
+					handleLine(decoder.decode(lineBuffer.subarray(0, length)));
+				} catch {
+					writeProtocolError(-32700, "Parse error").catch(() => void close());
+				}
 			}
 			lineBytes = 0;
 			discardingOversizedLine = false;
 			offset = newline + 1;
 		}
 	};
-	const finishInput = () => {
-		if (!ended) {
-			if (!discardingOversizedLine && lineBytes > 0) handleLine(lineBuffer.subarray(0, lineBytes).toString("utf8"));
-			ended = true;
-			cleanupInput();
-			finish();
-		}
+	const finishInput = () => void close();
+	const inputError = (error) => {
+		report(error);
+		close();
+	};
+	const outputError = (error) => {
+		report(error);
+		close();
 	};
 	input.on("data", onData);
 	input.once("end", finishInput);
 	input.once("close", finishInput);
-	cleanupInput = () => {
+	input.once("error", inputError);
+	output.once("error", outputError);
+	cleanupTransport = () => {
 		input.off("data", onData);
 		input.off("end", finishInput);
 		input.off("close", finishInput);
+		input.off("error", inputError);
+		output.off("error", outputError);
 	};
+	if (input.readableEnded || input.destroyed || output.destroyed) close();
 	return {
 		closed,
 		close

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@askrjs/node",
-  "version": "0.0.8",
+  "version": "0.0.11",
   "description": "Node http adapter for @askrjs/server",
   "keywords": [
     "askr",
@@ -43,10 +43,12 @@
     "access": "public"
   },
   "scripts": {
+    "bench": "vitest bench --run",
+    "bench:http": "vitest bench --run benches/http.bench.ts",
     "build": "vp pack",
     "fmt": "vp fmt .",
     "lint": "vp lint .",
-    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "typecheck": "tsc -p tsconfig.json --noEmit && tsc -p tsconfig.test.json --noEmit",
     "test": "vp test run",
     "test:publint": "publint",
     "pack:check": "node tests/package-artifacts.js",
@@ -55,18 +57,18 @@
     "prepublishOnly": "npm run check"
   },
   "dependencies": {
-    "@askrjs/auth": ">=0.0.1 <0.1.0",
-    "@askrjs/server": ">=0.0.5 <0.1.0",
-    "ws": "^8.21.1"
+    "@askrjs/auth": ">=0.0.8 <0.1.0",
+    "@askrjs/server": ">=0.0.11 <0.1.0",
+    "@types/ws": "^8.18.1",
+    "ws": "^8.21.3"
   },
   "devDependencies": {
-    "@askrjs/schema": ">=0.0.2 <0.1.0",
-    "@types/node": "^26.0.0",
-    "@types/ws": "^8.18.1",
-    "publint": "^0.3.21",
-    "typescript": "^6.0.0",
-    "vite-plus": "^0.2.4",
-    "vitest": "^4.0.0"
+    "@askrjs/schema": ">=0.0.5 <0.1.0",
+    "@types/node": "^26.2.0",
+    "publint": "^0.3.23",
+    "typescript": "^7.0.2",
+    "vite-plus": "^0.2.8",
+    "vitest": "^4.1.10"
   },
   "engines": {
     "node": ">=24.0.0"