@acid-cat/core-ts 0.1.0 → 0.2.0

package/README.md

@@ -60,6 +60,30 @@ Standard Schema does not convert to JSON Schema. Give the converter of your sche
 | `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 |
 
+### Context for each request
+
+`mcpHandler` and `httpHandler` take `context` or `createContext`. With `context`, all requests share one context. With `createContext(request)`, the handler makes a new context for each request that passes the screening. Use it when a request must not use objects that an earlier request made, for example on Cloudflare Workers, or when a stateful service must not be shared between callers. When the context has `Symbol.asyncDispose` or `Symbol.dispose`, the handler calls it after the response:
+
+```ts
+const handler = httpHandler(aircon, {
+  allowedOrigins: [],
+  toJsonSchema,
+  createContext: () => ({ unit: connectUnit(env), [Symbol.asyncDispose]: () => disconnectUnit() }),
+});
+```
+
+### Context for each request
+
+`mcpHandler` and `httpHandler` take `context` or `createContext`. With `context`, all requests share one context. With `createContext(request)`, the handler makes a new context for each request that passes the screening. Use it when a request must not use objects that an earlier request made, for example on Cloudflare Workers, or when a stateful service must not be shared between callers. When the context has `Symbol.asyncDispose` or `Symbol.dispose`, the handler calls it after the response:
+
+```ts
+const handler = httpHandler(aircon, {
+  allowedOrigins: [],
+  toJsonSchema,
+  createContext: () => ({ unit: connectUnit(env), [Symbol.asyncDispose]: () => disconnectUnit() }),
+});
+```
+
 ## Examples and tests
 
 - [`examples/aircon.ts`](examples/aircon.ts) is the air conditioner of [`examples/aircon.pkl`](../../examples/aircon.pkl), with a simulated unit. Its catalog agrees with the Pkl catalog.

package/dist/app.js

@@ -0,0 +1,62 @@
+import { canonicalText } from "@acid-cat/catalog";
+//#region src/app.ts
+/**
+* Capabilities and applications in plain TypeScript. An application writes its own catalog.
+* See spec/catalog.md.
+*/
+/** Declare a capability. `Context` is the type of the services that `run` receives. */
+const defineCapability = (capability) => capability;
+/**
+* Declare capabilities for one context type. The other types come from the schemas:
+*
+* ```ts
+* const capability = capabilitiesFor<{ unit: Unit }>();
+* capability({ id: "aircon.power.set", input: z.object({ on: z.boolean() }), run: ({ on }, { context }) => … });
+* ```
+*/
+const capabilitiesFor = () => (capability) => capability;
+/** Declare an application. */
+const defineApp = (app) => app;
+/** The catalog of an application, as a JSON document. */
+function catalogOf(app, options) {
+	const types = {};
+	const toJson = (schema, where) => {
+		const { $schema: _, $defs, ...json } = options.toJsonSchema(schema);
+		for (const [name, definition] of Object.entries($defs ?? {})) {
+			const existing = types[name];
+			if (existing !== void 0 && JSON.stringify(existing) !== JSON.stringify(definition)) throw new Error(`${where}: two different schemas have the name ${name}. Give each one its own name.`);
+			types[name] = definition;
+		}
+		return json;
+	};
+	const capabilities = {};
+	for (const capability of app.capabilities) {
+		if (capability.id in capabilities) throw new Error(`The capability ${capability.id} is declared two times.`);
+		const failures = Object.fromEntries(Object.entries(capability.failures ?? {}).map(([tag, schema]) => [tag, toJson(schema, capability.id)]));
+		capabilities[capability.id] = {
+			description: capability.description,
+			audience: capability.audience,
+			...capability.input === void 0 ? {} : { input: toJson(capability.input, capability.id) },
+			...capability.output === void 0 ? {} : { output: toJson(capability.output, capability.id) },
+			...Object.keys(failures).length === 0 ? {} : { failures },
+			...capability.readOnly === true ? { readOnly: true } : {},
+			...capability.state === void 0 ? {} : { state: toJson(capability.state.schema, capability.id) }
+		};
+	}
+	return {
+		acidcat: "0.1",
+		...app.title === void 0 ? {} : { title: app.title },
+		...app.description === void 0 ? {} : { description: app.description },
+		targets: Object.fromEntries(Object.entries(app.targets).map(([name, target]) => [name, {
+			bindings: target.bindings,
+			...target.description === void 0 ? {} : { description: target.description },
+			...target.options === void 0 ? {} : { options: target.options }
+		}])),
+		...Object.keys(types).length === 0 ? {} : { $defs: types },
+		capabilities
+	};
+}
+/** The catalog of an application, as text in canonical form. */
+const renderCatalog = (app, options) => canonicalText(catalogOf(app, options));
+//#endregion
+export { capabilitiesFor, catalogOf, defineApp, defineCapability, renderCatalog };

package/dist/cli.js

@@ -0,0 +1,163 @@
+import { createSession } from "./session.js";
+import { CLI_EXIT_CODES, REFERENCE, bundle, cliExitCode, commandPath, isCallFailure } from "@acid-cat/spec-ts";
+//#region src/cli.ts
+/**
+* The CLI binding (spec/bindings/cli.md): a command line made from the catalog.
+*/
+var UsageError = class extends Error {
+	exitCode;
+	constructor(message, exitCode) {
+		super(message);
+		this.exitCode = exitCode;
+	}
+};
+/** Run the command line as the main program of the process. An interrupt (`SIGINT`) cancels the call. */
+function main(app, options) {
+	const interrupt = new AbortController();
+	process.once("SIGINT", () => interrupt.abort());
+	runCli(app, options, process.argv.slice(2), {
+		stdout: (text) => process.stdout.write(`${text}\n`),
+		stderr: (text) => process.stderr.write(`${text}\n`),
+		signal: interrupt.signal
+	}).then((code) => {
+		process.exitCode = code;
+	});
+}
+/** Run the command line with arguments. The result is the exit code (spec/bindings/cli.md#outcomes). */
+async function runCli(app, options, args, io) {
+	const session = createSession(app, {
+		target: options.target ?? "cli",
+		context: options.context,
+		toJsonSchema: options.toJsonSchema
+	});
+	const types = session.view.$defs ?? {};
+	const commands = Object.keys(session.view.capabilities).map((id) => ({
+		id,
+		path: commandPath(id)
+	}));
+	for (const { path } of commands) if (path[0] === "call" || path[0] === "list") throw new Error(`The command ${path.join(" ")} has the same name as a command of the command line.`);
+	const print = (outcome) => {
+		if (isCallFailure(outcome)) io.stderr(JSON.stringify({
+			kind: outcome.kind,
+			message: outcome.message
+		}));
+		else io.stdout(JSON.stringify(outcome.ok ? outcome.value : outcome.error, null, 2));
+		return cliExitCode(outcome);
+	};
+	try {
+		const [first, ...rest] = args;
+		if (first === void 0 || first === "--help" || first === "-h") {
+			io.stdout(help(options.name, commands.map(({ path }) => path.join(" "))));
+			return CLI_EXIT_CODES.value;
+		}
+		if (first === "--version" || first === "-v") {
+			io.stdout(options.version);
+			return CLI_EXIT_CODES.value;
+		}
+		if (first === "list") {
+			io.stdout(JSON.stringify([...session.handles.values()].map((handle) => ({
+				id: handle.id,
+				description: handle.description,
+				...handle.availability.getSnapshot(),
+				usage: `${options.name} ${commandPath(handle.id).join(" ")}`
+			})), null, 2));
+			return CLI_EXIT_CODES.value;
+		}
+		if (first === "call") {
+			const [id, text = "{}"] = rest;
+			if (id === void 0) throw new UsageError("Give the id of a capability.", CLI_EXIT_CODES["invalid-input"]);
+			let input;
+			try {
+				input = JSON.parse(text);
+			} catch {
+				return print({
+					kind: "invalid-input",
+					message: "The input is not JSON."
+				});
+			}
+			return print(await session.invoke(id, input, { signal: io.signal }));
+		}
+		const match = commands.filter(({ path }) => path.every((word, index) => args[index] === word)).sort((a, b) => b.path.length - a.path.length)[0];
+		if (match === void 0) throw new UsageError(`There is no command ${args.filter((arg) => !arg.startsWith("-")).join(" ")}.`, CLI_EXIT_CODES["unknown-capability"]);
+		const capability = session.view.capabilities[match.id];
+		const schema = bundle(capability.input ?? { type: "object" }, types);
+		const flagArgs = args.slice(match.path.length);
+		if (flagArgs.includes("--help") || flagArgs.includes("-h")) {
+			io.stdout(usage(options.name, match.path, capability.description, schema));
+			return CLI_EXIT_CODES.value;
+		}
+		return print(await session.invoke(match.id, parseFlags(flagArgs, schema), { signal: io.signal }));
+	} catch (error) {
+		if (!(error instanceof UsageError)) throw error;
+		io.stderr(error.message);
+		return error.exitCode;
+	} finally {
+		await session.dispose();
+	}
+}
+/** Make the input from the flags (spec/bindings/cli.md#commands). */
+function parseFlags(args, schema) {
+	const properties = schema.properties ?? {};
+	const definitions = schema.$defs ?? {};
+	const input = {};
+	for (let index = 0; index < args.length; index += 1) {
+		const arg = args[index];
+		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(property, definitions);
+		if (type.type === "boolean") {
+			input[name] = inline === void 0 ? true : inline === "true";
+			continue;
+		}
+		const text = inline ?? args[index += 1];
+		if (text === void 0) throw new UsageError(`The flag --${name} needs a value.`, CLI_EXIT_CODES["invalid-input"]);
+		input[name] = valueOf(name, text, type);
+	}
+	for (const name of schema.required ?? []) if (!(name in input)) throw new UsageError(`The flag --${name} is required.`, CLI_EXIT_CODES["invalid-input"]);
+	return input;
+}
+function valueOf(name, text, type) {
+	if (Array.isArray(type.enum) && type.enum.every((value) => typeof value === "string")) {
+		if (!type.enum.includes(text)) throw new UsageError(`The flag --${name} must be one of: ${type.enum.join(", ")}.`, CLI_EXIT_CODES["invalid-input"]);
+		return text;
+	}
+	if (type.type === "integer" || type.type === "number") {
+		const number = Number(text);
+		if (text.trim() === "" || !Number.isFinite(number) || type.type === "integer" && !Number.isInteger(number)) throw new UsageError(`The flag --${name} must be a ${type.type}.`, CLI_EXIT_CODES["invalid-input"]);
+		return number;
+	}
+	if (type.type === "string") return text;
+	try {
+		return JSON.parse(text);
+	} catch {
+		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 : definitions[name] ?? property;
+}
+function help(name, paths) {
+	return [
+		`Usage: ${name} <command> [flags]`,
+		"",
+		"Commands:",
+		...paths.map((path) => `  ${path}`),
+		"  call <id> [input]",
+		"  list"
+	].join("\n");
+}
+function usage(name, path, description, schema) {
+	const properties = Object.keys(schema.properties ?? {});
+	const required = new Set(schema.required ?? []);
+	const flags = properties.map((property) => required.has(property) ? `--${property} <value>` : `[--${property} <value>]`);
+	return [
+		`Usage: ${name} ${[...path, ...flags].join(" ")}`,
+		"",
+		description
+	].join("\n");
+}
+//#endregion
+export { main, runCli };

package/dist/context.d.ts

@@ -0,0 +1,18 @@
+/**
+ * The context of the web handlers: one context that all requests share, or a new context for each request.
+ */
+export type ContextOption<Context> = {
+    /** The context of all requests. */
+    readonly context: Context;
+    readonly createContext?: undefined;
+} | {
+    /**
+     * Make the context of one request. The handler calls it for each request that passes the screening. When the
+     * context has `Symbol.asyncDispose` or `Symbol.dispose`, the handler calls it after the response, as a `using`
+     * declaration does.
+     */
+    readonly createContext: (request: Request) => Context | Promise<Context>;
+    readonly context?: undefined;
+};
+/** Give the context of one request to `use`, and release it afterwards if the handler made it. */
+export declare function withContext<Context, A>(option: ContextOption<Context>, request: Request, use: (context: Context) => Promise<A>): Promise<A>;

package/dist/context.js

@@ -0,0 +1,20 @@
+//#region src/context.ts
+/** Give the context of one request to `use`, and release it afterwards if the handler made it. */
+async function withContext(option, request, use) {
+	if (option.createContext === void 0) return use(option.context);
+	const context = await option.createContext(request);
+	try {
+		return await use(context);
+	} finally {
+		await release(context);
+	}
+}
+/** Call `Symbol.asyncDispose` or `Symbol.dispose` of a value, if it has one. */
+async function release(value) {
+	if (typeof value !== "object" || value === null) return;
+	const disposable = value;
+	if (typeof disposable[Symbol.asyncDispose] === "function") await disposable[Symbol.asyncDispose]();
+	else if (typeof disposable[Symbol.dispose] === "function") disposable[Symbol.dispose]();
+}
+//#endregion
+export { withContext };

package/dist/http.d.ts

@@ -1,8 +1,10 @@
 import type { App, ToJsonSchema } from "./app.js";
-export interface HttpOptions<Context> {
+import type { ContextOption } from "./context.js";
+/** The options of `httpHandler`. Give `context` to share one context, or `createContext` to make one for each request. */
+export type HttpOptions<Context> = HttpSettings & ContextOption<Context>;
+export interface HttpSettings {
     /** The origins that can call the API. A request with no `Origin` header is accepted. */
     readonly allowedOrigins: readonly string[];
-    readonly context: Context;
     readonly toJsonSchema: ToJsonSchema;
     /** The target that the API serves. The default is `"api"`. */
     readonly target?: string | undefined;
@@ -13,5 +15,5 @@ export interface HttpOptions<Context> {
     /** The maximum size of a request body, in bytes. The default is 1 MiB. */
     readonly maximumBytes?: number | undefined;
 }
-/** A web request handler for the API. Each request has its own session. */
+/** A web request handler for the API. Each request has its own session, and with `createContext` its own context. */
 export declare function httpHandler<Context>(app: App<Context>, options: HttpOptions<Context>): (request: Request) => Promise<Response>;

package/dist/http.js

@@ -0,0 +1,73 @@
+import { createSession } from "./session.js";
+import { withContext } from "./context.js";
+import { callFailure, httpStatus, isCallFailure, readBounded, screenRequest } from "@acid-cat/spec-ts";
+//#region src/http.ts
+/**
+* The HTTP binding (spec/bindings/http.md): JSON through HTTP.
+*/
+/** A web request handler for the API. Each request has its own session, and with `createContext` its own context. */
+function httpHandler(app, options) {
+	const maximumBytes = options.maximumBytes ?? 1048576;
+	return async (request) => {
+		const screened = screenRequest(request, {
+			methods: ["GET", "POST"],
+			allowedOrigins: options.allowedOrigins,
+			mediaType: "application/json",
+			maximumBytes
+		});
+		if (screened !== void 0) return rejection(screened);
+		const path = new URL(request.url).pathname.slice((options.base ?? "").length);
+		return withContext(options, request, async (context) => {
+			const session = createSession(app, {
+				target: options.target ?? "api",
+				context,
+				toJsonSchema: options.toJsonSchema
+			});
+			try {
+				if (request.method === "GET" && path === "/capabilities") return json(200, [...session.handles.values()].map((handle) => ({
+					id: handle.id,
+					...handle.availability.getSnapshot()
+				})));
+				if (request.method === "GET" && path === "/catalog" && options.serveCatalog !== false) return json(200, session.view);
+				const id = request.method === "POST" && path.startsWith("/capabilities/") ? path.slice(14) : void 0;
+				if (id === void 0) return json(404, callFailure("unknown-capability", "There is no such route."));
+				const body = await readBounded(request, maximumBytes);
+				if ("rejection" in body) return rejection(body.rejection);
+				let input;
+				try {
+					input = body.text === "" ? {} : JSON.parse(body.text);
+				} catch {
+					return json(422, callFailure("invalid-input", "The request body is not JSON."));
+				}
+				const outcome = await session.invoke(decodeURIComponent(id), input, { signal: request.signal });
+				return json(httpStatus(outcome), isCallFailure(outcome) ? {
+					kind: outcome.kind,
+					message: outcome.message
+				} : outcome);
+			} finally {
+				await session.dispose();
+			}
+		});
+	};
+}
+const json = (status, body) => new Response(JSON.stringify(body), {
+	status,
+	headers: { "Content-Type": "application/json" }
+});
+const statuses = {
+	method: 405,
+	origin: 403,
+	"media-type": 415,
+	"too-large": 413,
+	"not-utf8": 400
+};
+function rejection(reason) {
+	const headers = new Headers({ "Cache-Control": "no-store" });
+	if (reason === "method") headers.set("Allow", "GET, POST");
+	return new Response(null, {
+		status: statuses[reason],
+		headers
+	});
+}
+//#endregion
+export { httpHandler };

package/dist/index.d.ts

@@ -3,9 +3,10 @@ export type { AnyCapability, App, Capability, Observable, Target, ToJsonSchema }
 export { createSession } from "./session.js";
 export type { Handle, Session, SessionOptions } from "./session.js";
 export { mcpHandler } from "./mcp.js";
-export type { McpOptions } from "./mcp.js";
+export type { McpOptions, McpSettings } from "./mcp.js";
 export { httpHandler } from "./http.js";
-export type { HttpOptions } from "./http.js";
+export type { HttpOptions, HttpSettings } from "./http.js";
+export type { ContextOption } from "./context.js";
 export { main as cliMain, runCli } from "./cli.js";
 export type { CliIo, CliOptions } from "./cli.js";
 export { findHost, installWebMcp } from "./webmcp.js";