@askrjs/node 0.0.3 → 0.0.5

package/README.md

@@ -0,0 +1,90 @@
+# @askrjs/node
+
+[![CI](https://github.com/askrjs/askr-node/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/askrjs/askr-node/actions/workflows/ci.yml)
+[![npm version](https://img.shields.io/npm/v/%40askrjs%2Fnode.svg)](https://www.npmjs.com/package/@askrjs/node)
+
+Run an `@askrjs/server` application on Node.js. The adapter translates Node HTTP messages at the
+boundary while the application continues to use Web `Request` and `Response` objects.
+
+## Install
+
+```sh
+npm install @askrjs/server @askrjs/node
+```
+
+## Create a Node handler
+
+```ts
+import { createServer } from "node:http";
+import { createServerApp, json } from "@askrjs/server";
+import { createNodeHandler } from "@askrjs/node";
+
+const app = createServerApp({
+  routes: [{ path: "/health", handler: () => json({ status: "ok" }) }],
+});
+
+createServer(createNodeHandler(app)).listen(3000);
+```
+
+`createNodeHandler` also works as Connect middleware because it accepts an optional `next`
+callback. It preserves streaming bodies, repeated `Set-Cookie` headers, aborts, backpressure,
+status text, and HEAD responses.
+
+## Listen directly
+
+```ts
+import { listen } from "@askrjs/node";
+
+const server = await listen(app, {
+  port: 3000,
+  requestTimeout: 120_000,
+  headersTimeout: 60_000,
+  keepAliveTimeout: 5_000,
+});
+server.close();
+```
+
+Pass an `AbortSignal` to integrate shutdown with your process lifecycle.
+
+Enable the built-in `ws` transport with `websocket: true`. It defaults to a
+1 MiB maximum message payload with compression disabled; pass
+`websocket: { maxPayload, perMessageDeflate }` to override those settings.
+
+```ts
+router.ws("/echo", (socket) => {
+  socket.onMessage((message) => socket.send(message));
+});
+
+const server = await listen(createServerApp({ router }), { websocket: true });
+```
+
+Route matching, authentication, and middleware complete before the handshake.
+Rejected upgrades preserve the application response, and shutdown closes active
+sockets.
+
+## Serve a production application
+
+```ts
+import { serve } from "@askrjs/node";
+
+const running = await serve(app, {
+  port: 3000,
+  assets: { root: "./dist/client" },
+});
+
+await running.close();
+```
+
+`serve` handles static assets and closes both the HTTP server and the application during shutdown.
+
+## MCP over stdio
+
+```ts
+import { connectMcpStdio } from "@askrjs/node/mcp";
+
+const connection = connectMcpStdio(mcp, { dependencies });
+await connection.closed;
+```
+
+Protocol messages use stdin/stdout; diagnostics remain isolated on stderr. Authentication may be
+provided directly or resolved from the process environment for each message.

package/dist/index.d.ts

@@ -1,7 +1,12 @@
 import { IncomingMessage, Server, ServerResponse } from "node:http";
+import { PerMessageDeflateOptions } from "ws";
 import { ServerApp } from "@askrjs/server";
 import { AddressInfo } from "node:net";
 //#region src/contracts.d.ts
+interface NodeWebSocketOptions {
+  readonly maxPayload?: number;
+  readonly perMessageDeflate?: boolean | PerMessageDeflateOptions;
+}
 interface NodeHandlerOptions {
   baseUrl?: string;
 }
@@ -10,6 +15,10 @@ interface ListenOptions {
   host?: string;
   backlog?: number;
   signal?: AbortSignal;
+  requestTimeout?: number;
+  headersTimeout?: number;
+  keepAliveTimeout?: number;
+  websocket?: boolean | NodeWebSocketOptions;
 }
 interface ServeOptions extends ListenOptions {
   readonly assets?: {
@@ -39,4 +48,4 @@ declare function serve(app: ServerApp & {
   close?: () => void | Promise<void>;
 }, options?: ServeOptions): Promise<ServedApplication>;
 //#endregion
-export { ConnectNext, ListenOptions, ListeningServer, NodeHandler, NodeHandlerOptions, ServeOptions, ServedApplication, createNodeHandler, listen, serve };
+export { ConnectNext, ListenOptions, ListeningServer, NodeHandler, NodeHandlerOptions, NodeWebSocketOptions, ServeOptions, ServedApplication, createNodeHandler, listen, serve };

package/dist/index.js

@@ -1,5 +1,6 @@
 import { Readable } from "node:stream";
 import { createServer } from "node:http";
+import { WebSocketServer } from "ws";
 import { createReadStream } from "node:fs";
 import { stat } from "node:fs/promises";
 import { extname, resolve, sep } from "node:path";
@@ -129,9 +130,88 @@ function createNodeHandler(app, options = {}) {
 	};
 }
 //#endregion
+//#region src/websocket.ts
+function subscribe(socket, event, listener) {
+	socket.on(event, listener);
+	return () => socket.off(event, listener);
+}
+function socketLike(socket) {
+	return {
+		send: (data) => socket.send(data),
+		close: (code, reason) => socket.close(code, reason),
+		onMessage: (listener) => subscribe(socket, "message", (data, binary) => {
+			if (!binary) listener(data.toString());
+			else {
+				const buffer = Array.isArray(data) ? Buffer.concat(data) : Buffer.from(data);
+				listener(new Uint8Array(buffer.buffer, buffer.byteOffset, buffer.byteLength));
+			}
+		}),
+		onClose: (listener) => subscribe(socket, "close", (code, reason) => listener({
+			code,
+			reason: reason.toString(),
+			wasClean: code === 1e3
+		})),
+		onError: (listener) => subscribe(socket, "error", listener)
+	};
+}
+async function rejectUpgrade(socket, response) {
+	const body = Buffer.from(await response.arrayBuffer());
+	const lines = [`HTTP/1.1 ${response.status} ${response.statusText || "Rejected"}`];
+	response.headers.forEach((value, name) => lines.push(`${name}: ${value}`));
+	if (!response.headers.has("content-length")) lines.push(`content-length: ${body.byteLength}`);
+	lines.push("connection: close", "", "");
+	socket.end(Buffer.concat([Buffer.from(lines.join("\r\n")), body]));
+}
+function installWebSockets(server, app, options = {}, handlerOptions = {}) {
+	const webSockets = new WebSocketServer({
+		noServer: true,
+		maxPayload: options.maxPayload ?? 1048576,
+		perMessageDeflate: options.perMessageDeflate ?? false
+	});
+	server.on("upgrade", (request, socket, head) => {
+		const controller = new AbortController();
+		let accepted;
+		Promise.resolve().then(() => requestFromNode(request, handlerOptions, controller.signal)).then(async (webRequest) => {
+			let marker;
+			const response = await app.fetch(webRequest, { websocket: { upgrade: (_request, handler, context) => {
+				marker = new Response(null, { status: 200 });
+				accepted = {
+					handler,
+					context,
+					response: marker
+				};
+				return marker;
+			} } });
+			if (!accepted || response !== accepted.response) {
+				await rejectUpgrade(socket, response);
+				return;
+			}
+			webSockets.handleUpgrade(request, socket, head, (webSocket) => {
+				webSocket.once("close", () => controller.abort());
+				Promise.resolve(accepted.handler(socketLike(webSocket), accepted.context)).catch(() => webSocket.close(1011, "WebSocket handler failed"));
+			});
+		}).catch(() => socket.destroy());
+	});
+	return { close() {
+		for (const socket of webSockets.clients) socket.close(1001, "Server shutting down");
+		webSockets.close();
+	} };
+}
+//#endregion
 //#region src/listen.ts
 function listen(app, options = {}) {
 	const server = createServer(createNodeHandler(app));
+	if (options.requestTimeout !== void 0) server.requestTimeout = options.requestTimeout;
+	if (options.headersTimeout !== void 0) server.headersTimeout = options.headersTimeout;
+	if (options.keepAliveTimeout !== void 0) server.keepAliveTimeout = options.keepAliveTimeout;
+	const webSockets = options.websocket ? installWebSockets(server, app, options.websocket === true ? {} : options.websocket) : void 0;
+	if (webSockets) {
+		const nativeClose = server.close.bind(server);
+		server.close = ((callback) => {
+			webSockets.close();
+			return nativeClose(callback);
+		});
+	}
 	const close = () => server.close();
 	options.signal?.addEventListener("abort", close, { once: true });
 	server.once("close", () => options.signal?.removeEventListener("abort", close));
@@ -169,8 +249,8 @@ function isAssetPath(pathname) {
 }
 async function serve(app, options = {}) {
 	const root = options.assets ? resolve(options.assets.root) : void 0;
-	const applicationHandler = createNodeHandler({ async fetch(request) {
-		const result = await app.fetch(request);
+	const applicationHandler = createNodeHandler({ async fetch(request, dispatchOptions) {
+		const result = await app.fetch(request, dispatchOptions);
 		if (!result.headers.has("cache-control") && result.headers.get("content-type")?.includes("text/html")) {
 			const headers = new Headers(result.headers);
 			headers.set("cache-control", "no-cache");
@@ -220,6 +300,10 @@ async function serve(app, options = {}) {
 		}
 		applicationHandler(request, response);
 	});
+	if (options.requestTimeout !== void 0) server.requestTimeout = options.requestTimeout;
+	if (options.headersTimeout !== void 0) server.headersTimeout = options.headersTimeout;
+	if (options.keepAliveTimeout !== void 0) server.keepAliveTimeout = options.keepAliveTimeout;
+	const webSockets = options.websocket ? installWebSockets(server, app, options.websocket === true ? {} : options.websocket) : void 0;
 	let closing;
 	const signals = options.signals === false ? [] : options.signals ?? ["SIGINT", "SIGTERM"];
 	const removeListeners = () => {
@@ -228,6 +312,7 @@ async function serve(app, options = {}) {
 	};
 	const close = () => closing ??= new Promise((resolveClose, rejectClose) => {
 		removeListeners();
+		webSockets?.close();
 		const finish = async (serverError) => {
 			try {
 				await app.close?.();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@askrjs/node",
-  "version": "0.0.3",
+  "version": "0.0.5",
   "description": "Node http adapter for @askrjs/server",
   "keywords": [
     "askr",
@@ -56,10 +56,12 @@
   },
   "dependencies": {
     "@askrjs/auth": ">=0.0.1 <0.1.0",
-    "@askrjs/server": ">=0.0.1 <0.1.0"
+    "@askrjs/server": ">=0.0.5 <0.1.0",
+    "ws": "^8.21.1"
   },
   "devDependencies": {
     "@types/node": "^26.0.0",
+    "@types/ws": "^8.18.1",
     "publint": "^0.3.21",
     "typescript": "^6.0.0",
     "vite-plus": "^0.2.4",