@acid-cat/core-ts 0.7.0 → 0.8.0

package/README.md

@@ -62,9 +62,35 @@ Standard Schema does not convert to JSON Schema. Give the converter of your sche
 | `httpHandler(app, options)` | [HTTP](../../spec/bindings/http.md) | `(request: Request) => Promise<Response>` |
 | `cliMain(app, options)`, `runCli(…)` | [CLI](../../spec/bindings/cli.md) | The command line of the process, or an exit code |
 | `installWebMcp(session)` | [WebMCP](../../spec/bindings/webmcp.md) | Tools in the page, with a status |
+| `serve(handler, options)`, from `@acid-cat/core-ts/node` | MCP and HTTP | A Node.js server for the web handlers. See [Serve on Node.js](#serve-on-nodejs) |
 
 When the signal of a request aborts, `mcpHandler` and `httpHandler` cancel the call of the request.
 
+### Serve on Node.js
+
+`@acid-cat/core-ts/node` serves web handlers on Node.js, with only `node:http`. It has no other dependency.
+
+```ts
+import { serve } from "@acid-cat/core-ts/node";
+
+const mcp = mcpHandler(aircon, { name: "aircon", version: "1.0.0", allowedOrigins: [], toJsonSchema, context: { unit } });
+const http = httpHandler(aircon, { allowedOrigins: [], toJsonSchema, context: { unit } });
+
+const server = await serve({ "/mcp": mcp, "/": http }, { port: 3000 });
+console.log(server.url); // http://127.0.0.1:3000
+```
+
+`serve(handler, options)` takes one handler for all paths, or handlers by path prefix. The longest prefix that matches gets the request, and the prefix `/` matches all paths. The MCP handler answers on all paths, so give it only its own prefix. A path that no prefix matches gets `404`. A handler that rejects gets `500`.
+
+| Option | Default | Use |
+| --- | --- | --- |
+| `port` | `3000` | The port. With `0`, the system chooses a free port. `server.port` gives it |
+| `hostname` | `127.0.0.1` | The address. Only the same computer can connect. Use `0.0.0.0` or `::` to accept connections from the network |
+
+`serve` resolves when the server listens. `server.close()` stops it, and `await using server = await serve(…)` closes it at the end of the block. When a client closes its connection, the signal of its request aborts, so the handler cancels the call.
+
+`serve` gives a plain HTTP/1.1 server. For more, use a library for web handlers, for example [srvx](https://srvx.h3.dev): HTTPS, HTTP/2, middleware, or the same server code on Bun and Deno. Give it the handler. Make sure that the library aborts the signal of a request when the client closes the connection. If it does not, a closed connection does not cancel the call.
+
 ### Typed calls and handles
 
 `createSession` gives a `Session<Context>`. It calls a capability with the types of the capability in two ways. Both take the capability object, so the types come from its schemas:
@@ -102,6 +128,20 @@ const handler = httpHandler(aircon, {
 });
 ```
 
+### Command line
+
+The command line has one command for each capability in the view of the `cli` target. Each top-level property of the input is a flag with the same name, for example `--celsius 22` or `--celsius=22`. A boolean property is a switch, for example `--on`. A property with an array of strings, numbers or values of a string enum is a repeated flag: each occurrence gives one item, in the order of the flags. A repeated flag that occurs once can also give the whole array as JSON text. Other properties take JSON text. For example, with the command line of the air conditioner, [`examples/aircon/core-ts/cli.ts`](../../examples/aircon/core-ts/cli.ts):
+
+```sh
+node cli.ts aircon temperature set --celsius 22
+node cli.ts aircon schedule set --days mon --days fri --hours 7 --hours 18   # {"days":["mon","fri"],"hours":[7,18]}
+node cli.ts aircon schedule set --days '["mon","fri"]' --hours '[7,18]'      # the same input, as JSON text
+node cli.ts aircon schedule set --days '[]'                                   # an empty array
+node cli.ts list                                                             # the usage of each command
+```
+
+`list` gives a usage line for each capability. The usage of a repeated flag ends with `...`, for example `--days <mon|tue|wed|thu|fri|sat|sun>... [--hours <integer>...]`. See the [CLI binding](../../spec/bindings/cli.md#commands) for all the rules.
+
 ### Commands of the application
 
 The option `commands` of `cliMain` and `runCli` adds commands of the application beside the commands of the capabilities, `call` and `list`. A command has a `name`, a `description` for the help, and `run(args, io)`. `run` gets the arguments after the name of the command, and `io` with `stdout`, `stderr`, `signal` and the `context`. It returns the exit code. The name must not be `call`, `list`, the name of another command of the application, or the first word of the command of a capability. If it is, `runCli` throws. The option `description` gives the text at the top of the help. The default is the description of the application, then its title, then the name of the program.

package/dist/cli.js

@@ -1,5 +1,5 @@
 import { createSession } from "./session.js";
-import { CLI_EXIT_CODES, REFERENCE, bundle, cliExitCode, cliFlags, cliUsage, commandPath, isCallFailure, isJsonObject } from "@acid-cat/spec-ts";
+import { CLI_EXIT_CODES, bundle, cliExitCode, cliFlags, cliJsonArray, cliRepeatedItems, cliResolve, cliUsage, commandPath, isCallFailure, isJsonObject } from "@acid-cat/spec-ts";
 //#region src/cli.ts
 /**
 * The CLI binding (spec/bindings/cli.md): a command line made from the catalog.
@@ -119,21 +119,32 @@ function parseFlags(args, schema) {
 	const properties = objectOrEmpty(schema.properties);
 	const definitions = objectOrEmpty(schema.$defs);
 	const input = {};
+	const repeated = /* @__PURE__ */ new Map();
 	const remaining = args.values();
 	for (const arg of remaining) {
 		if (!arg.startsWith("--")) throw new UsageError(`Unexpected argument ${arg}.`, CLI_EXIT_CODES["invalid-input"]);
 		const [name = "", inline] = arg.slice(2).split(/=(.*)/s, 2);
 		const property = properties[name];
 		if (property === void 0) throw new UsageError(`Unknown flag --${name}.`, CLI_EXIT_CODES["invalid-input"]);
-		const type = resolve(objectOrEmpty(property), definitions);
+		const type = cliResolve(objectOrEmpty(property), definitions);
 		if (type.type === "boolean") {
 			input[name] = inline === void 0 ? true : inline === "true";
 			continue;
 		}
 		const text = inline ?? remaining.next().value;
 		if (text === void 0) throw new UsageError(`The flag --${name} needs a value.`, CLI_EXIT_CODES["invalid-input"]);
-		input[name] = valueOf(name, text, type);
+		const items = cliRepeatedItems(type, definitions);
+		if (items === void 0) input[name] = valueOf(name, text, type);
+		else {
+			const flag = repeated.get(name) ?? {
+				items,
+				values: []
+			};
+			flag.values.push(text);
+			repeated.set(name, flag);
+		}
 	}
+	for (const [name, { items, values }] of repeated) input[name] = cliJsonArray(values) ?? values.map((text) => valueOf(name, text, items));
 	const required = Array.isArray(schema.required) ? schema.required.filter((name) => typeof name === "string") : [];
 	for (const name of required) if (!(name in input)) throw new UsageError(`The flag --${name} is required.`, CLI_EXIT_CODES["invalid-input"]);
 	return input;
@@ -155,10 +166,6 @@ function valueOf(name, text, type) {
 		throw new UsageError(`The flag --${name} must be JSON.`, CLI_EXIT_CODES["invalid-input"]);
 	}
 }
-function resolve(property, definitions) {
-	const name = typeof property.$ref === "string" ? REFERENCE.exec(property.$ref)?.[1] : void 0;
-	return name === void 0 ? property : objectOrEmpty(definitions[name] ?? property);
-}
 /** A value as a JSON object, or an empty object when it is not one. */
 const objectOrEmpty = (value) => isJsonObject(value) ? value : {};
 /** The capability `id` of a view. The view has it, because the session serves it. */

package/dist/node.d.ts

@@ -0,0 +1,39 @@
+/** A web request handler. */
+export type WebHandler = (request: Request) => Promise<Response> | Response;
+/**
+ * Handlers by path prefix, for example `{ "/mcp": mcp, "/api": http }`. A prefix matches its own path and the paths
+ * below it: `/api` matches `/api` and `/api/status`, but not `/apis`. The longest prefix that matches gets the request.
+ * The prefix `/` matches all paths. The handler gets the full URL of the request.
+ */
+export interface Routes {
+    readonly [prefix: string]: WebHandler;
+}
+export interface ServeOptions {
+    /** The port. The default is `3000`. With `0`, the system chooses a free port. */
+    readonly port?: number | undefined;
+    /**
+     * The address to listen on. The default is `127.0.0.1`, so that only the same computer can connect. Use `0.0.0.0`
+     * or `::` to accept connections from the network.
+     */
+    readonly hostname?: string | undefined;
+}
+/** A server that runs. `await using` closes it at the end of its block. */
+export interface Served extends AsyncDisposable {
+    /** The base URL, for example `http://127.0.0.1:3000`. */
+    readonly url: string;
+    /** The port that the server listens on. */
+    readonly port: number;
+    /** Stop accepting connections, and resolve when the open requests are complete. */
+    readonly close: () => Promise<void>;
+}
+/**
+ * Serve one handler for all paths, or handlers by path prefix. The promise resolves when the server listens, and rejects
+ * when it cannot listen, for example when the port is in use.
+ *
+ * - The signal of each request aborts when the client closes the connection before the response is complete. A handler
+ *   that follows the signal then cancels its work.
+ * - A path that no prefix matches gets `404`. A handler that throws or rejects gets `500`. A request that is not valid
+ *   HTTP for a URL gets `400`.
+ * - The body of a request is a stream that reads from the connection only when the handler reads it.
+ */
+export declare function serve(handler: WebHandler | Routes, options?: ServeOptions): Promise<Served>;

package/dist/node.js

@@ -0,0 +1,172 @@
+import { createServer } from "node:http";
+//#region src/node.ts
+/**
+* The functions that need Node.js. The main entry point, `@acid-cat/core-ts`, works in all runtimes.
+*
+* `serve` serves web request handlers, `(request: Request) => Promise<Response>`, such as the handlers of `mcpHandler`
+* and `httpHandler`, on Node.js, with only `node:http`. The server serves plain HTTP/1.1. For HTTPS, HTTP/2 or
+* middleware, use a library for web handlers.
+*/
+/**
+* Serve one handler for all paths, or handlers by path prefix. The promise resolves when the server listens, and rejects
+* when it cannot listen, for example when the port is in use.
+*
+* - The signal of each request aborts when the client closes the connection before the response is complete. A handler
+*   that follows the signal then cancels its work.
+* - A path that no prefix matches gets `404`. A handler that throws or rejects gets `500`. A request that is not valid
+*   HTTP for a URL gets `400`.
+* - The body of a request is a stream that reads from the connection only when the handler reads it.
+*/
+function serve(handler, options = {}) {
+	const route = router(handler);
+	const hostname = options.hostname ?? "127.0.0.1";
+	const server = createServer((incoming, outgoing) => {
+		answer(incoming, outgoing, route);
+	});
+	return new Promise((resolve, reject) => {
+		server.once("error", reject);
+		server.listen(options.port ?? 3e3, hostname, () => {
+			server.off("error", reject);
+			const address = server.address();
+			const port = typeof address === "object" && address !== null ? address.port : 0;
+			const close = () => new Promise((done) => server.close(() => done()));
+			resolve({
+				url: `http://${hostname.includes(":") ? `[${hostname}]` : hostname}:${port}`,
+				port,
+				close,
+				[Symbol.asyncDispose]: close
+			});
+		});
+	});
+}
+/** The handler of a path, or `undefined` when no prefix matches. */
+function router(handler) {
+	if (typeof handler === "function") return () => handler;
+	const prefixes = Object.keys(handler).sort((a, b) => b.length - a.length);
+	const matches = (path, prefix) => prefix.endsWith("/") ? path.startsWith(prefix) || path === prefix.slice(0, -1) : path === prefix || path.startsWith(`${prefix}/`);
+	return (path) => {
+		const prefix = prefixes.find((candidate) => matches(path, candidate));
+		return prefix === void 0 ? void 0 : handler[prefix];
+	};
+}
+async function answer(incoming, outgoing, route) {
+	const abort = new AbortController();
+	outgoing.on("close", () => {
+		if (!outgoing.writableFinished) abort.abort();
+	});
+	let request;
+	try {
+		request = requestOf(incoming, abort.signal);
+	} catch {
+		outgoing.writeHead(400).end();
+		return;
+	}
+	const handler = route(new URL(request.url).pathname);
+	if (handler === void 0) {
+		outgoing.writeHead(404).end();
+		return;
+	}
+	try {
+		await send(await handler(request), outgoing);
+	} catch {
+		if (outgoing.headersSent) outgoing.destroy();
+		else outgoing.writeHead(500).end();
+	}
+}
+/** The web request of an incoming request. It throws when the request has no valid URL. */
+function requestOf(incoming, signal) {
+	const url = new URL(incoming.url ?? "/", `http://${incoming.headers.host ?? "localhost"}`);
+	const headers = new Headers();
+	for (const [name, value] of Object.entries(incoming.headers)) if (Array.isArray(value)) value.forEach((item) => headers.append(name, item));
+	else if (value !== void 0) headers.set(name, value);
+	const method = incoming.method ?? "GET";
+	const init = {
+		method,
+		headers,
+		signal
+	};
+	if (method === "GET" || method === "HEAD") return new Request(url, init);
+	const withBody = {
+		...init,
+		body: bodyOf(incoming),
+		duplex: "half"
+	};
+	return new Request(url, withBody);
+}
+/**
+* Write a web response. The body waits when the connection is full. When the client closes the connection, the body
+* is cancelled.
+*/
+async function send(response, outgoing) {
+	const headers = {};
+	for (const [name, value] of response.headers) if (name !== "set-cookie") headers[name] = value;
+	const cookies = response.headers.getSetCookie();
+	if (cookies.length > 0) headers["set-cookie"] = cookies;
+	outgoing.writeHead(response.status, response.statusText, headers);
+	if (response.body === null) {
+		outgoing.end();
+		return;
+	}
+	const reader = response.body.getReader();
+	const cancel = () => void reader.cancel().catch(() => void 0);
+	outgoing.on("close", cancel);
+	try {
+		for (;;) {
+			const chunk = await reader.read();
+			if (chunk.done) break;
+			if (outgoing.destroyed) return;
+			if (!outgoing.write(chunk.value)) await drained(outgoing);
+		}
+		outgoing.end();
+	} finally {
+		outgoing.off("close", cancel);
+	}
+}
+/** Resolve when the connection can take more data, or when it closes. */
+function drained(outgoing) {
+	return new Promise((resolve) => {
+		const done = () => {
+			outgoing.off("drain", done);
+			outgoing.off("close", done);
+			resolve();
+		};
+		outgoing.on("drain", done);
+		outgoing.on("close", done);
+	});
+}
+/**
+* The body of an incoming request, as a web stream. The stream reads the request only when the handler reads the body,
+* and the request pauses after each chunk until the handler reads again. A request that the handler does not read stays
+* unread, so that Node.js discards it after the response. When the handler cancels the stream, the request discards the
+* rest of its body.
+*/
+function bodyOf(incoming) {
+	let open = true;
+	let reading = false;
+	const close = (end) => {
+		if (open) end();
+		open = false;
+	};
+	return new ReadableStream({
+		pull(controller) {
+			if (!reading) {
+				reading = true;
+				incoming.on("data", (chunk) => {
+					if (!open) return;
+					if (!(chunk instanceof Uint8Array)) return close(() => controller.error(/* @__PURE__ */ new TypeError("a chunk of the request body is not bytes")));
+					controller.enqueue(chunk);
+					incoming.pause();
+				});
+				incoming.on("end", () => close(() => controller.close()));
+				incoming.on("error", (error) => close(() => controller.error(error)));
+			}
+			incoming.resume();
+		},
+		cancel() {
+			open = false;
+			incoming.resume();
+		}
+	}, { highWaterMark: 0 });
+}
+//#endregion
+export { serve };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@acid-cat/core-ts",
-  "version": "0.7.0",
+  "version": "0.8.0",
   "description": "Serve AcidCat capabilities in plain TypeScript, with no Effect dependency.",
   "keywords": [
     "acidcat",
@@ -26,17 +26,21 @@
     ".": {
       "types": "./dist/index.d.ts",
       "default": "./dist/index.js"
+    },
+    "./node": {
+      "types": "./dist/node.d.ts",
+      "default": "./dist/node.js"
     }
   },
   "publishConfig": {
     "access": "public"
   },
   "dependencies": {
-    "@acid-cat/catalog": "0.7.0",
-    "@acid-cat/spec-ts": "0.7.0"
+    "@acid-cat/catalog": "0.8.0",
+    "@acid-cat/spec-ts": "0.8.0"
   },
   "devDependencies": {
-    "@acid-cat/cli": "0.7.0",
+    "@acid-cat/cli": "0.8.0",
     "@types/node": "26.6.5",
     "esbuild": "0.28.2",
     "playwright": "1.64.0",