@mostra/protocol 0.0.0-stage → 0.1.0

package/dist/rpc/peer.d.ts

@@ -0,0 +1,81 @@
+import { Diagnostic } from "../diagnostics/diagnostic.js";
+import { MethodDefinition } from "../method.js";
+import { JsonRpcId, JsonRpcMessage, JsonRpcParams } from "./messages.js";
+//#region src/rpc/peer.d.ts
+/** What a request handler learns about the request besides its params. */
+export interface RpcRequestContext {
+  /** The request's ID. */
+  readonly id: JsonRpcId;
+  /** The method name. */
+  readonly method: string;
+}
+/** Options for {@link RpcPeer}. */
+export interface RpcPeerOptions {
+  /**
+   * Sends one message. The transport serializes it (`encodeLine` for newline-delimited streams).
+   * Throwing means the transport is gone: the peer closes.
+   */
+  send(message: JsonRpcMessage): void;
+  /**
+   * Answers an incoming request. Return the result, or throw an {@link RpcError} to answer with
+   * its diagnostic. Any other exception is answered with `MOSTRA_HOST_INTERNAL_ERROR`, without
+   * its details, and reported to `onInternalError`. Without a handler, every request is answered
+   * with `MOSTRA_HOST_METHOD_UNKNOWN`.
+   */
+  onRequest?(method: string, params: unknown, context: RpcRequestContext): unknown;
+  /** Receives an incoming notification. Exceptions are reported to `onInternalError`. */
+  onNotification?(method: string, params: unknown): void;
+  /** Reports an unexpected exception from a handler, for logging. */
+  onInternalError?(error: unknown, method: string): void;
+  /** The docs base URL for diagnostics the peer creates. Default `DEFAULT_DOCS_BASE`. */
+  readonly docsBase?: string;
+}
+/** Options for one outgoing request. */
+export interface RpcRequestOptions {
+  /**
+   * Gives up after this many milliseconds with `MOSTRA_HOST_TIMEOUT`. A late response is
+   * ignored. Default: no timeout (FAILURE_MODEL §9).
+   */
+  readonly timeoutMs?: number;
+}
+/** One end of a JSON-RPC 2.0 connection. */
+export declare class RpcPeer {
+  #private;
+  constructor(options: RpcPeerOptions);
+  /** Whether the peer has closed. A closed peer sends nothing and rejects new requests. */
+  get closed(): boolean;
+  /** How many outgoing requests are waiting for a response. */
+  get pendingRequests(): number;
+  /**
+   * Receives one line of a newline-delimited stream. Blank lines are skipped; a line that isn't
+   * JSON is answered with a parse error (-32700).
+   */
+  receiveLine(line: string): void;
+  /** Receives one parsed message. */
+  receive(value: unknown): void;
+  /**
+   * Sends a request and resolves with its result, or rejects with an {@link RpcError}: the
+   * other side's diagnostic, `MOSTRA_HOST_TIMEOUT` or `MOSTRA_HOST_CONNECTION_CLOSED`.
+   */
+  request(method: string, params?: JsonRpcParams, options?: RpcRequestOptions): Promise<unknown>;
+  /**
+   * Calls a protocol method: validates the params before sending and the result on arrival. A
+   * result that fails the method's schema rejects with `MOSTRA_HOST_MALFORMED`.
+   */
+  call<P, R>(definition: MethodDefinition<P, R>, params: P, options?: RpcRequestOptions): Promise<R>;
+  /** Sends a notification. Does nothing once the peer is closed. */
+  notify(method: string, params?: JsonRpcParams): void;
+  /**
+   * Closes the peer: every waiting request rejects with `diagnostic` (by default
+   * `MOSTRA_HOST_CONNECTION_CLOSED`), and later messages are ignored. Idempotent.
+   */
+  close(diagnostic?: Diagnostic): void;
+}
+/**
+ * Validates a method's params against its schema and returns the parsed value. Throws an
+ * {@link RpcError} with `MOSTRA_HOST_INVALID_PARAMS` naming the first problem; the message
+ * describes types and paths, never the values sent.
+ */
+export declare function parseParams<P, R>(definition: MethodDefinition<P, R>, params: unknown, docsBase?: string): P;
+//#endregion
+//# sourceMappingURL=peer.d.ts.map

package/dist/rpc/peer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"peer.d.ts","names":[],"sources":["../../src/rpc/peer.ts"],"mappings":";;;;;iBA0BiB;;WAEN,IAAI;;WAEJ;;;iBAIM;;;;;EAKf,KAAK,SAAS;;;;;;;EAOd,WAAW,gBAAgB,iBAAiB,SAAS;;EAErD,gBAAgB,gBAAgB;;EAEhC,iBAAiB,gBAAgB;;WAExB;;;iBAIM;;;;;WAKN;;;qBAWE;;EAMX,YAAY,SAAS;;MAKjB;;MAKA;;;;;EAQJ,YAAY;;EAkBZ,QAAQ;;;;;EAwCR,QACE,gBACA,SAAS,eACT,UAAS,oBACR;;;;;EA+BH,KAAW,GAAG,GACZ,YAAY,iBAAiB,GAAG,IAChC,QAAQ,GACR,UAAS,oBACR,QAAQ;;EAcX,OAAO,gBAAgB,SAAS;;;;;EAWhC,MAAM,aAAa;;;;;;;wBA4GL,YAAY,GAAG,GAC7B,YAAY,iBAAiB,GAAG,IAChC,iBACA,oBACC"}

package/dist/rpc/peer.js

@@ -0,0 +1,208 @@
+import { JSON_RPC_ERROR_CODES, RpcError, hostDiagnostic } from "./error.js";
+import { classifyMessage } from "./messages.js";
+//#region src/rpc/peer.ts
+/** One end of a JSON-RPC 2.0 connection. */
+var RpcPeer = class {
+	#options;
+	#pending = /* @__PURE__ */ new Map();
+	#nextId = 1;
+	#closed;
+	constructor(options) {
+		this.#options = options;
+	}
+	/** Whether the peer has closed. A closed peer sends nothing and rejects new requests. */
+	get closed() {
+		return this.#closed !== void 0;
+	}
+	/** How many outgoing requests are waiting for a response. */
+	get pendingRequests() {
+		return this.#pending.size;
+	}
+	/**
+	* Receives one line of a newline-delimited stream. Blank lines are skipped; a line that isn't
+	* JSON is answered with a parse error (-32700).
+	*/
+	receiveLine(line) {
+		if (line.trim() === "") return;
+		let value;
+		try {
+			value = JSON.parse(line);
+		} catch {
+			this.#reply(null, { rpc: new RpcError(this.#diagnostic("MOSTRA_HOST_MALFORMED", "A line wasn't valid JSON."), JSON_RPC_ERROR_CODES.parseError) });
+			return;
+		}
+		this.receive(value);
+	}
+	/** Receives one parsed message. */
+	receive(value) {
+		if (this.#closed) return;
+		const classified = classifyMessage(value);
+		switch (classified.kind) {
+			case "request":
+				this.#handleRequest(classified.message.id, classified.message.method, classified.message.params);
+				return;
+			case "notification":
+				this.#handleNotification(classified.message.method, classified.message.params);
+				return;
+			case "success":
+				this.#settle(classified.message.id, (pending) => pending.resolve(classified.message.result));
+				return;
+			case "failure": {
+				const { id, error } = classified.message;
+				if (id !== null) this.#settle(id, (pending) => pending.reject(RpcError.fromErrorObject(error, this.#options.docsBase)));
+				return;
+			}
+			case "invalid":
+				this.#reply(classified.id, { rpc: new RpcError(this.#diagnostic("MOSTRA_HOST_MALFORMED", classified.reason)) });
+				return;
+		}
+	}
+	/**
+	* Sends a request and resolves with its result, or rejects with an {@link RpcError}: the
+	* other side's diagnostic, `MOSTRA_HOST_TIMEOUT` or `MOSTRA_HOST_CONNECTION_CLOSED`.
+	*/
+	request(method, params, options = {}) {
+		if (this.#closed) return Promise.reject(new RpcError(this.#closed));
+		const id = this.#nextId++;
+		return new Promise((resolve, reject) => {
+			const pending = {
+				method,
+				resolve,
+				reject
+			};
+			if (options.timeoutMs !== void 0) pending.timer = setTimeout(() => {
+				this.#pending.delete(id);
+				reject(new RpcError(this.#diagnostic("MOSTRA_HOST_TIMEOUT", `No response to ${method} within ${options.timeoutMs} ms.`)));
+			}, options.timeoutMs);
+			this.#pending.set(id, pending);
+			this.#send(params === void 0 ? {
+				jsonrpc: "2.0",
+				id,
+				method
+			} : {
+				jsonrpc: "2.0",
+				id,
+				method,
+				params
+			});
+		});
+	}
+	/**
+	* Calls a protocol method: validates the params before sending and the result on arrival. A
+	* result that fails the method's schema rejects with `MOSTRA_HOST_MALFORMED`.
+	*/
+	async call(definition, params, options = {}) {
+		const checked = parseParams(definition, params, this.#options.docsBase);
+		const raw = await this.request(definition.method, checked, options);
+		const parsed = definition.result.safeParse(raw);
+		if (parsed.success) return parsed.data;
+		throw new RpcError(this.#diagnostic("MOSTRA_HOST_MALFORMED", `The result of ${definition.method} doesn't match its schema: ${describeIssue(parsed.error.issues)}`));
+	}
+	/** Sends a notification. Does nothing once the peer is closed. */
+	notify(method, params) {
+		if (this.#closed) return;
+		this.#send(params === void 0 ? {
+			jsonrpc: "2.0",
+			method
+		} : {
+			jsonrpc: "2.0",
+			method,
+			params
+		});
+	}
+	/**
+	* Closes the peer: every waiting request rejects with `diagnostic` (by default
+	* `MOSTRA_HOST_CONNECTION_CLOSED`), and later messages are ignored. Idempotent.
+	*/
+	close(diagnostic) {
+		if (this.#closed) return;
+		const reason = diagnostic ?? this.#diagnostic("MOSTRA_HOST_CONNECTION_CLOSED", "The connection closed before a response arrived.");
+		this.#closed = reason;
+		const pending = [...this.#pending.values()];
+		this.#pending.clear();
+		for (const entry of pending) {
+			if (entry.timer !== void 0) clearTimeout(entry.timer);
+			entry.reject(new RpcError(reason));
+		}
+	}
+	#handleRequest(id, method, params) {
+		const handler = this.#options.onRequest;
+		if (!handler) {
+			this.#reply(id, { rpc: new RpcError(this.#diagnostic("MOSTRA_HOST_METHOD_UNKNOWN", `This side serves no method ${method}.`)) });
+			return;
+		}
+		let outcome;
+		try {
+			outcome = handler(method, params, {
+				id,
+				method
+			});
+		} catch (error) {
+			this.#reply(id, { rpc: this.#asRpcError(error, method) });
+			return;
+		}
+		Promise.resolve(outcome).then((result) => this.#reply(id, { result: result === void 0 ? null : result }), (error) => this.#reply(id, { rpc: this.#asRpcError(error, method) }));
+	}
+	#handleNotification(method, params) {
+		try {
+			this.#options.onNotification?.(method, params);
+		} catch (error) {
+			this.#options.onInternalError?.(error, method);
+		}
+	}
+	#asRpcError(error, method) {
+		if (error instanceof RpcError) return error;
+		this.#options.onInternalError?.(error, method);
+		return new RpcError(this.#diagnostic("MOSTRA_HOST_INTERNAL_ERROR", `${method} failed unexpectedly.`));
+	}
+	#settle(id, action) {
+		const pending = this.#pending.get(id);
+		if (!pending) return;
+		this.#pending.delete(id);
+		if (pending.timer !== void 0) clearTimeout(pending.timer);
+		action(pending);
+	}
+	#reply(id, outcome) {
+		if (this.#closed) return;
+		if ("rpc" in outcome) this.#send({
+			jsonrpc: "2.0",
+			id,
+			error: outcome.rpc.toErrorObject()
+		});
+		else if (id !== null) this.#send({
+			jsonrpc: "2.0",
+			id,
+			result: outcome.result
+		});
+	}
+	#send(message) {
+		try {
+			this.#options.send(message);
+		} catch {
+			this.close();
+		}
+	}
+	#diagnostic(code, message) {
+		return hostDiagnostic(code, { message }, this.#options.docsBase);
+	}
+};
+function describeIssue(issues) {
+	const [first] = issues;
+	if (!first) return "unknown problem";
+	const path = first.path.map(String).join(".");
+	return `${path === "" ? "(root)" : path}: ${first.message}`;
+}
+/**
+* Validates a method's params against its schema and returns the parsed value. Throws an
+* {@link RpcError} with `MOSTRA_HOST_INVALID_PARAMS` naming the first problem; the message
+* describes types and paths, never the values sent.
+*/
+function parseParams(definition, params, docsBase) {
+	const parsed = definition.params.safeParse(params ?? {});
+	if (parsed.success) return parsed.data;
+	throw new RpcError(hostDiagnostic("MOSTRA_HOST_INVALID_PARAMS", { message: `Invalid params for ${definition.method}: ${describeIssue(parsed.error.issues)}` }, docsBase));
+}
+//#endregion
+export { RpcPeer, parseParams };
+
+//# sourceMappingURL=peer.js.map

package/dist/rpc/peer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"peer.js","names":[],"sources":["../../src/rpc/peer.ts"],"sourcesContent":["/**\n * One end of a JSON-RPC 2.0 connection (D83): it matches responses to requests, dispatches\n * incoming requests and notifications, and turns every failure into a diagnostic. It has no I/O.\n * The transport hands it parsed messages (or raw lines) and sends what it gives back, so the same\n * peer serves stdio, Unix sockets, Node IPC and `postMessage`.\n *\n * ```ts\n * const peer = new RpcPeer({\n *   send: (message) => socket.write(encodeLine(message)),\n *   onRequest: (method, params) => handlers[method](params),\n * });\n * splitter.push(chunk).forEach((line) => peer.receiveLine(line));\n * const result = await peer.call(mostraInitializeMethod, params);\n * ```\n */\nimport type { Diagnostic } from \"../diagnostics/diagnostic.ts\";\nimport type { MethodDefinition } from \"../method.ts\";\nimport { hostDiagnostic, JSON_RPC_ERROR_CODES, RpcError } from \"./error.ts\";\nimport {\n  classifyMessage,\n  type JsonRpcId,\n  type JsonRpcMessage,\n  type JsonRpcParams,\n} from \"./messages.ts\";\n\n/** What a request handler learns about the request besides its params. */\nexport interface RpcRequestContext {\n  /** The request's ID. */\n  readonly id: JsonRpcId;\n  /** The method name. */\n  readonly method: string;\n}\n\n/** Options for {@link RpcPeer}. */\nexport interface RpcPeerOptions {\n  /**\n   * Sends one message. The transport serializes it (`encodeLine` for newline-delimited streams).\n   * Throwing means the transport is gone: the peer closes.\n   */\n  send(message: JsonRpcMessage): void;\n  /**\n   * Answers an incoming request. Return the result, or throw an {@link RpcError} to answer with\n   * its diagnostic. Any other exception is answered with `MOSTRA_HOST_INTERNAL_ERROR`, without\n   * its details, and reported to `onInternalError`. Without a handler, every request is answered\n   * with `MOSTRA_HOST_METHOD_UNKNOWN`.\n   */\n  onRequest?(method: string, params: unknown, context: RpcRequestContext): unknown;\n  /** Receives an incoming notification. Exceptions are reported to `onInternalError`. */\n  onNotification?(method: string, params: unknown): void;\n  /** Reports an unexpected exception from a handler, for logging. */\n  onInternalError?(error: unknown, method: string): void;\n  /** The docs base URL for diagnostics the peer creates. Default `DEFAULT_DOCS_BASE`. */\n  readonly docsBase?: string;\n}\n\n/** Options for one outgoing request. */\nexport interface RpcRequestOptions {\n  /**\n   * Gives up after this many milliseconds with `MOSTRA_HOST_TIMEOUT`. A late response is\n   * ignored. Default: no timeout (FAILURE_MODEL §9).\n   */\n  readonly timeoutMs?: number;\n}\n\ninterface Pending {\n  readonly method: string;\n  resolve(result: unknown): void;\n  reject(error: RpcError): void;\n  timer?: ReturnType<typeof setTimeout>;\n}\n\n/** One end of a JSON-RPC 2.0 connection. */\nexport class RpcPeer {\n  readonly #options: RpcPeerOptions;\n  readonly #pending = new Map<JsonRpcId, Pending>();\n  #nextId = 1;\n  #closed: Diagnostic | undefined;\n\n  constructor(options: RpcPeerOptions) {\n    this.#options = options;\n  }\n\n  /** Whether the peer has closed. A closed peer sends nothing and rejects new requests. */\n  get closed(): boolean {\n    return this.#closed !== undefined;\n  }\n\n  /** How many outgoing requests are waiting for a response. */\n  get pendingRequests(): number {\n    return this.#pending.size;\n  }\n\n  /**\n   * Receives one line of a newline-delimited stream. Blank lines are skipped; a line that isn't\n   * JSON is answered with a parse error (-32700).\n   */\n  receiveLine(line: string): void {\n    if (line.trim() === \"\") return;\n    let value: unknown;\n    try {\n      value = JSON.parse(line);\n    } catch {\n      this.#reply(null, {\n        rpc: new RpcError(\n          this.#diagnostic(\"MOSTRA_HOST_MALFORMED\", \"A line wasn't valid JSON.\"),\n          JSON_RPC_ERROR_CODES.parseError,\n        ),\n      });\n      return;\n    }\n    this.receive(value);\n  }\n\n  /** Receives one parsed message. */\n  receive(value: unknown): void {\n    if (this.#closed) return;\n    const classified = classifyMessage(value);\n    switch (classified.kind) {\n      case \"request\":\n        this.#handleRequest(\n          classified.message.id,\n          classified.message.method,\n          classified.message.params,\n        );\n        return;\n      case \"notification\":\n        this.#handleNotification(classified.message.method, classified.message.params);\n        return;\n      case \"success\":\n        this.#settle(classified.message.id, (pending) =>\n          pending.resolve(classified.message.result),\n        );\n        return;\n      case \"failure\": {\n        const { id, error } = classified.message;\n        if (id !== null) {\n          this.#settle(id, (pending) =>\n            pending.reject(RpcError.fromErrorObject(error, this.#options.docsBase)),\n          );\n        }\n        return;\n      }\n      case \"invalid\":\n        this.#reply(classified.id, {\n          rpc: new RpcError(this.#diagnostic(\"MOSTRA_HOST_MALFORMED\", classified.reason)),\n        });\n        return;\n    }\n  }\n\n  /**\n   * Sends a request and resolves with its result, or rejects with an {@link RpcError}: the\n   * other side's diagnostic, `MOSTRA_HOST_TIMEOUT` or `MOSTRA_HOST_CONNECTION_CLOSED`.\n   */\n  request(\n    method: string,\n    params?: JsonRpcParams,\n    options: RpcRequestOptions = {},\n  ): Promise<unknown> {\n    if (this.#closed) return Promise.reject(new RpcError(this.#closed));\n    const id = this.#nextId++;\n    return new Promise<unknown>((resolve, reject) => {\n      const pending: Pending = { method, resolve, reject };\n      if (options.timeoutMs !== undefined) {\n        pending.timer = setTimeout(() => {\n          this.#pending.delete(id);\n          reject(\n            new RpcError(\n              this.#diagnostic(\n                \"MOSTRA_HOST_TIMEOUT\",\n                `No response to ${method} within ${options.timeoutMs} ms.`,\n              ),\n            ),\n          );\n        }, options.timeoutMs);\n      }\n      this.#pending.set(id, pending);\n      this.#send(\n        params === undefined\n          ? { jsonrpc: \"2.0\", id, method }\n          : { jsonrpc: \"2.0\", id, method, params },\n      );\n    });\n  }\n\n  /**\n   * Calls a protocol method: validates the params before sending and the result on arrival. A\n   * result that fails the method's schema rejects with `MOSTRA_HOST_MALFORMED`.\n   */\n  async call<P, R>(\n    definition: MethodDefinition<P, R>,\n    params: P,\n    options: RpcRequestOptions = {},\n  ): Promise<R> {\n    const checked = parseParams(definition, params, this.#options.docsBase);\n    const raw = await this.request(definition.method, checked as JsonRpcParams, options);\n    const parsed = definition.result.safeParse(raw);\n    if (parsed.success) return parsed.data;\n    throw new RpcError(\n      this.#diagnostic(\n        \"MOSTRA_HOST_MALFORMED\",\n        `The result of ${definition.method} doesn't match its schema: ${describeIssue(parsed.error.issues)}`,\n      ),\n    );\n  }\n\n  /** Sends a notification. Does nothing once the peer is closed. */\n  notify(method: string, params?: JsonRpcParams): void {\n    if (this.#closed) return;\n    this.#send(\n      params === undefined ? { jsonrpc: \"2.0\", method } : { jsonrpc: \"2.0\", method, params },\n    );\n  }\n\n  /**\n   * Closes the peer: every waiting request rejects with `diagnostic` (by default\n   * `MOSTRA_HOST_CONNECTION_CLOSED`), and later messages are ignored. Idempotent.\n   */\n  close(diagnostic?: Diagnostic): void {\n    if (this.#closed) return;\n    const reason =\n      diagnostic ??\n      this.#diagnostic(\n        \"MOSTRA_HOST_CONNECTION_CLOSED\",\n        \"The connection closed before a response arrived.\",\n      );\n    this.#closed = reason;\n    const pending = [...this.#pending.values()];\n    this.#pending.clear();\n    for (const entry of pending) {\n      if (entry.timer !== undefined) clearTimeout(entry.timer);\n      entry.reject(new RpcError(reason));\n    }\n  }\n\n  #handleRequest(id: JsonRpcId, method: string, params: unknown): void {\n    const handler = this.#options.onRequest;\n    if (!handler) {\n      this.#reply(id, {\n        rpc: new RpcError(\n          this.#diagnostic(\"MOSTRA_HOST_METHOD_UNKNOWN\", `This side serves no method ${method}.`),\n        ),\n      });\n      return;\n    }\n    let outcome: unknown;\n    try {\n      outcome = handler(method, params, { id, method });\n    } catch (error) {\n      this.#reply(id, { rpc: this.#asRpcError(error, method) });\n      return;\n    }\n    Promise.resolve(outcome).then(\n      (result) => this.#reply(id, { result: result === undefined ? null : result }),\n      (error: unknown) => this.#reply(id, { rpc: this.#asRpcError(error, method) }),\n    );\n  }\n\n  #handleNotification(method: string, params: unknown): void {\n    try {\n      this.#options.onNotification?.(method, params);\n    } catch (error) {\n      this.#options.onInternalError?.(error, method);\n    }\n  }\n\n  #asRpcError(error: unknown, method: string): RpcError {\n    if (error instanceof RpcError) return error;\n    this.#options.onInternalError?.(error, method);\n    return new RpcError(\n      this.#diagnostic(\"MOSTRA_HOST_INTERNAL_ERROR\", `${method} failed unexpectedly.`),\n    );\n  }\n\n  #settle(id: JsonRpcId, action: (pending: Pending) => void): void {\n    const pending = this.#pending.get(id);\n    if (!pending) return;\n    this.#pending.delete(id);\n    if (pending.timer !== undefined) clearTimeout(pending.timer);\n    action(pending);\n  }\n\n  #reply(id: JsonRpcId | null, outcome: { result: unknown } | { rpc: RpcError }): void {\n    if (this.#closed) return;\n    if (\"rpc\" in outcome) {\n      this.#send({ jsonrpc: \"2.0\", id, error: outcome.rpc.toErrorObject() });\n    } else if (id !== null) {\n      this.#send({ jsonrpc: \"2.0\", id, result: outcome.result });\n    }\n  }\n\n  #send(message: JsonRpcMessage): void {\n    try {\n      this.#options.send(message);\n    } catch {\n      this.close();\n    }\n  }\n\n  #diagnostic(\n    code:\n      | \"MOSTRA_HOST_MALFORMED\"\n      | \"MOSTRA_HOST_METHOD_UNKNOWN\"\n      | \"MOSTRA_HOST_INTERNAL_ERROR\"\n      | \"MOSTRA_HOST_TIMEOUT\"\n      | \"MOSTRA_HOST_CONNECTION_CLOSED\",\n    message: string,\n  ): Diagnostic {\n    return hostDiagnostic(code, { message }, this.#options.docsBase);\n  }\n}\n\nfunction describeIssue(\n  issues: readonly { readonly path: readonly PropertyKey[]; readonly message: string }[],\n): string {\n  const [first] = issues;\n  if (!first) return \"unknown problem\";\n  const path = first.path.map(String).join(\".\");\n  return `${path === \"\" ? \"(root)\" : path}: ${first.message}`;\n}\n\n/**\n * Validates a method's params against its schema and returns the parsed value. Throws an\n * {@link RpcError} with `MOSTRA_HOST_INVALID_PARAMS` naming the first problem; the message\n * describes types and paths, never the values sent.\n */\nexport function parseParams<P, R>(\n  definition: MethodDefinition<P, R>,\n  params: unknown,\n  docsBase?: string,\n): P {\n  const parsed = definition.params.safeParse(params ?? {});\n  if (parsed.success) return parsed.data;\n  throw new RpcError(\n    hostDiagnostic(\n      \"MOSTRA_HOST_INVALID_PARAMS\",\n      { message: `Invalid params for ${definition.method}: ${describeIssue(parsed.error.issues)}` },\n      docsBase,\n    ),\n  );\n}\n"],"mappings":";;;;AAwEA,IAAa,UAAb,MAAqB;CACnB;CACA,2BAAoB,IAAI,IAAwB;CAChD,UAAU;CACV;CAEA,YAAY,SAAyB;EACnC,KAAK,WAAW;CAClB;;CAGA,IAAI,SAAkB;EACpB,OAAO,KAAK,YAAY,KAAA;CAC1B;;CAGA,IAAI,kBAA0B;EAC5B,OAAO,KAAK,SAAS;CACvB;;;;;CAMA,YAAY,MAAoB;EAC9B,IAAI,KAAK,KAAK,MAAM,IAAI;EACxB,IAAI;EACJ,IAAI;GACF,QAAQ,KAAK,MAAM,IAAI;EACzB,QAAQ;GACN,KAAK,OAAO,MAAM,EAChB,KAAK,IAAI,SACP,KAAK,YAAY,yBAAyB,2BAA2B,GACrE,qBAAqB,UACvB,EACF,CAAC;GACD;EACF;EACA,KAAK,QAAQ,KAAK;CACpB;;CAGA,QAAQ,OAAsB;EAC5B,IAAI,KAAK,SAAS;EAClB,MAAM,aAAa,gBAAgB,KAAK;EACxC,QAAQ,WAAW,MAAnB;GACE,KAAK;IACH,KAAK,eACH,WAAW,QAAQ,IACnB,WAAW,QAAQ,QACnB,WAAW,QAAQ,MACrB;IACA;GACF,KAAK;IACH,KAAK,oBAAoB,WAAW,QAAQ,QAAQ,WAAW,QAAQ,MAAM;IAC7E;GACF,KAAK;IACH,KAAK,QAAQ,WAAW,QAAQ,KAAK,YACnC,QAAQ,QAAQ,WAAW,QAAQ,MAAM,CAC3C;IACA;GACF,KAAK,WAAW;IACd,MAAM,EAAE,IAAI,UAAU,WAAW;IACjC,IAAI,OAAO,MACT,KAAK,QAAQ,KAAK,YAChB,QAAQ,OAAO,SAAS,gBAAgB,OAAO,KAAK,SAAS,QAAQ,CAAC,CACxE;IAEF;GACF;GACA,KAAK;IACH,KAAK,OAAO,WAAW,IAAI,EACzB,KAAK,IAAI,SAAS,KAAK,YAAY,yBAAyB,WAAW,MAAM,CAAC,EAChF,CAAC;IACD;EACJ;CACF;;;;;CAMA,QACE,QACA,QACA,UAA6B,CAAC,GACZ;EAClB,IAAI,KAAK,SAAS,OAAO,QAAQ,OAAO,IAAI,SAAS,KAAK,OAAO,CAAC;EAClE,MAAM,KAAK,KAAK;EAChB,OAAO,IAAI,SAAkB,SAAS,WAAW;GAC/C,MAAM,UAAmB;IAAE;IAAQ;IAAS;GAAO;GACnD,IAAI,QAAQ,cAAc,KAAA,GACxB,QAAQ,QAAQ,iBAAiB;IAC/B,KAAK,SAAS,OAAO,EAAE;IACvB,OACE,IAAI,SACF,KAAK,YACH,uBACA,kBAAkB,OAAO,UAAU,QAAQ,UAAU,KACvD,CACF,CACF;GACF,GAAG,QAAQ,SAAS;GAEtB,KAAK,SAAS,IAAI,IAAI,OAAO;GAC7B,KAAK,MACH,WAAW,KAAA,IACP;IAAE,SAAS;IAAO;IAAI;GAAO,IAC7B;IAAE,SAAS;IAAO;IAAI;IAAQ;GAAO,CAC3C;EACF,CAAC;CACH;;;;;CAMA,MAAM,KACJ,YACA,QACA,UAA6B,CAAC,GAClB;EACZ,MAAM,UAAU,YAAY,YAAY,QAAQ,KAAK,SAAS,QAAQ;EACtE,MAAM,MAAM,MAAM,KAAK,QAAQ,WAAW,QAAQ,SAA0B,OAAO;EACnF,MAAM,SAAS,WAAW,OAAO,UAAU,GAAG;EAC9C,IAAI,OAAO,SAAS,OAAO,OAAO;EAClC,MAAM,IAAI,SACR,KAAK,YACH,yBACA,iBAAiB,WAAW,OAAO,6BAA6B,cAAc,OAAO,MAAM,MAAM,GACnG,CACF;CACF;;CAGA,OAAO,QAAgB,QAA8B;EACnD,IAAI,KAAK,SAAS;EAClB,KAAK,MACH,WAAW,KAAA,IAAY;GAAE,SAAS;GAAO;EAAO,IAAI;GAAE,SAAS;GAAO;GAAQ;EAAO,CACvF;CACF;;;;;CAMA,MAAM,YAA+B;EACnC,IAAI,KAAK,SAAS;EAClB,MAAM,SACJ,cACA,KAAK,YACH,iCACA,kDACF;EACF,KAAK,UAAU;EACf,MAAM,UAAU,CAAC,GAAG,KAAK,SAAS,OAAO,CAAC;EAC1C,KAAK,SAAS,MAAM;EACpB,KAAK,MAAM,SAAS,SAAS;GAC3B,IAAI,MAAM,UAAU,KAAA,GAAW,aAAa,MAAM,KAAK;GACvD,MAAM,OAAO,IAAI,SAAS,MAAM,CAAC;EACnC;CACF;CAEA,eAAe,IAAe,QAAgB,QAAuB;EACnE,MAAM,UAAU,KAAK,SAAS;EAC9B,IAAI,CAAC,SAAS;GACZ,KAAK,OAAO,IAAI,EACd,KAAK,IAAI,SACP,KAAK,YAAY,8BAA8B,8BAA8B,OAAO,EAAE,CACxF,EACF,CAAC;GACD;EACF;EACA,IAAI;EACJ,IAAI;GACF,UAAU,QAAQ,QAAQ,QAAQ;IAAE;IAAI;GAAO,CAAC;EAClD,SAAS,OAAO;GACd,KAAK,OAAO,IAAI,EAAE,KAAK,KAAK,YAAY,OAAO,MAAM,EAAE,CAAC;GACxD;EACF;EACA,QAAQ,QAAQ,OAAO,CAAC,CAAC,MACtB,WAAW,KAAK,OAAO,IAAI,EAAE,QAAQ,WAAW,KAAA,IAAY,OAAO,OAAO,CAAC,IAC3E,UAAmB,KAAK,OAAO,IAAI,EAAE,KAAK,KAAK,YAAY,OAAO,MAAM,EAAE,CAAC,CAC9E;CACF;CAEA,oBAAoB,QAAgB,QAAuB;EACzD,IAAI;GACF,KAAK,SAAS,iBAAiB,QAAQ,MAAM;EAC/C,SAAS,OAAO;GACd,KAAK,SAAS,kBAAkB,OAAO,MAAM;EAC/C;CACF;CAEA,YAAY,OAAgB,QAA0B;EACpD,IAAI,iBAAiB,UAAU,OAAO;EACtC,KAAK,SAAS,kBAAkB,OAAO,MAAM;EAC7C,OAAO,IAAI,SACT,KAAK,YAAY,8BAA8B,GAAG,OAAO,sBAAsB,CACjF;CACF;CAEA,QAAQ,IAAe,QAA0C;EAC/D,MAAM,UAAU,KAAK,SAAS,IAAI,EAAE;EACpC,IAAI,CAAC,SAAS;EACd,KAAK,SAAS,OAAO,EAAE;EACvB,IAAI,QAAQ,UAAU,KAAA,GAAW,aAAa,QAAQ,KAAK;EAC3D,OAAO,OAAO;CAChB;CAEA,OAAO,IAAsB,SAAwD;EACnF,IAAI,KAAK,SAAS;EAClB,IAAI,SAAS,SACX,KAAK,MAAM;GAAE,SAAS;GAAO;GAAI,OAAO,QAAQ,IAAI,cAAc;EAAE,CAAC;OAChE,IAAI,OAAO,MAChB,KAAK,MAAM;GAAE,SAAS;GAAO;GAAI,QAAQ,QAAQ;EAAO,CAAC;CAE7D;CAEA,MAAM,SAA+B;EACnC,IAAI;GACF,KAAK,SAAS,KAAK,OAAO;EAC5B,QAAQ;GACN,KAAK,MAAM;EACb;CACF;CAEA,YACE,MAMA,SACY;EACZ,OAAO,eAAe,MAAM,EAAE,QAAQ,GAAG,KAAK,SAAS,QAAQ;CACjE;AACF;AAEA,SAAS,cACP,QACQ;CACR,MAAM,CAAC,SAAS;CAChB,IAAI,CAAC,OAAO,OAAO;CACnB,MAAM,OAAO,MAAM,KAAK,IAAI,MAAM,CAAC,CAAC,KAAK,GAAG;CAC5C,OAAO,GAAG,SAAS,KAAK,WAAW,KAAK,IAAI,MAAM;AACpD;;;;;;AAOA,SAAgB,YACd,YACA,QACA,UACG;CACH,MAAM,SAAS,WAAW,OAAO,UAAU,UAAU,CAAC,CAAC;CACvD,IAAI,OAAO,SAAS,OAAO,OAAO;CAClC,MAAM,IAAI,SACR,eACE,8BACA,EAAE,SAAS,sBAAsB,WAAW,OAAO,IAAI,cAAc,OAAO,MAAM,MAAM,IAAI,GAC5F,QACF,CACF;AACF"}

package/dist/serializer.d.ts

@@ -0,0 +1,178 @@
+//#region src/serializer.d.ts
+/**
+ * The serializer of server-function arguments and results (D19 seam 2, D54): exactly the type set
+ * React documents for Server Functions, plus `AsyncIterable` results, in one JSON wire form the
+ * browser, the gateway and the worker share. It has no I/O and no Node built-ins.
+ *
+ * A value is written as a series of **batches**, each a JSON array of {@link Frame}s. The first
+ * batch holds the value's root (chunk 0); a promise or an async iterable in it is a reference whose
+ * settlement or items arrive in later batches, so a result streams as it settles. Shared objects
+ * and cycles are kept: an object met twice is written once, in a chunk of its own.
+ *
+ * ```ts
+ * const batches: Frame[][] = [];
+ * const writer = new ValueWriter({ mode: "result", onBatch: (batch) => batches.push(batch) });
+ * await writer.write({ when: new Date(), items: new Map([["a", 1]]) });
+ * await writer.done;
+ * const reader = new ValueReader();
+ * for (const batch of batches) reader.push(batch);
+ * const value = await reader.root;
+ * ```
+ *
+ * What it accepts (react.dev, `'use server'`, "Serializable arguments and return values"):
+ * strings, numbers (`NaN`, infinities and `-0` too), bigints, booleans, `undefined`, `null`,
+ * symbols registered with `Symbol.for`, arrays, `Map`, `Set`, typed arrays, `DataView`,
+ * `ArrayBuffer`, `Date`, `FormData` (with string and file values), plain objects, Server Functions
+ * and promises; results may also be async iterables. Anything else (class instances, objects with
+ * a null prototype, other functions, unregistered symbols, React elements) is refused with a
+ * {@link SerializationError} naming where it is.
+ */
+/** One step of a written value. */
+export type Frame = {
+  readonly c: number;
+  readonly v: unknown;
+} | {
+  readonly p: number;
+  readonly v: unknown;
+} | {
+  readonly p: number;
+  readonly e: WireError;
+} | {
+  readonly i: number;
+  readonly v: unknown;
+} | {
+  readonly i: number;
+  readonly end: true;
+} | {
+  readonly i: number;
+  readonly e: WireError;
+};
+/** An error as the wire carries it: a rejected promise, a failed iteration. */
+export interface WireError {
+  /** The error's message. */
+  readonly message: string;
+  /** Its diagnostic code, when it carried one (`MOSTRA_SECRET_MISSING`, say). */
+  readonly code?: string;
+}
+/** Any function: a Server Function as the serializer sees it. */
+export type AnyFunction = (...args: never) => unknown;
+/** Whether a value is written as a call's arguments or as its result. */
+export type SerializeMode = "argument" | "result";
+/**
+ * The most digits a bigint argument may have. A page's arguments are decoded before the action
+ * runs, and parsing a bigint takes time that grows faster than its length: 16 M digits held a
+ * worker's event loop for seconds. Results aren't limited; server code writes them.
+ */
+export declare const ARGUMENT_BIGINT_DIGITS_MAX = 1e4;
+/** The diagnostic code of a value outside the type set (INTERFACES §2.4). */
+export declare const UNSERIALIZABLE_CODE = "MOSTRA_ACTION_UNSERIALIZABLE";
+/** A value outside the type set, or a malformed written value. */
+export declare class SerializationError extends Error {
+  /** Always `MOSTRA_ACTION_UNSERIALIZABLE`. */
+  readonly code: string;
+  /** Where in the value: `.items[2].when`, or empty for the value itself. */
+  readonly path: string;
+  constructor(message: string, path?: string);
+}
+/** The error a rejected promise or a failed iteration carries on the wire. */
+export declare function wireError(error: unknown): WireError;
+/** An error read back from the wire, as the reader's promises and iterables reject with it. */
+export declare class RemoteError extends Error {
+  /** The diagnostic code the error carried, if any. */
+  readonly code: string | undefined;
+  constructor(error: WireError);
+}
+/** Standard base64 of `bytes`, with padding. */
+export declare function toBase64(bytes: Uint8Array): string;
+/** The bytes of standard base64 text; throws a {@link SerializationError} on anything else. */
+export declare function fromBase64(text: string): Uint8Array;
+/** Options for {@link ValueWriter}. */
+export interface ValueWriterOptions {
+  /** `argument`: no async iterables. `result`: everything. */
+  readonly mode: SerializeMode;
+  /** Receives each batch, in order. */
+  readonly onBatch: (batch: Frame[]) => void;
+  /**
+   * The ID of a function that is a Server Function, or `undefined` for any other function. The
+   * client's stubs carry their ID; the worker knows its registry.
+   */
+  readonly serverFunctionId?: (fn: AnyFunction) => string | undefined;
+}
+/**
+ * Writes one value as batches. `write` throws a {@link SerializationError} when the value, or
+ * anything it holds synchronously, is outside the type set; a promise that later settles with such
+ * a value is written as rejected with that error. `done` settles once every promise and iterable
+ * in the value has settled or ended; `abort` stops iterables early (the reader went away).
+ */
+export declare class ValueWriter {
+  #private;
+  /** Settles once every async part of the value has been written. */
+  readonly done: Promise<void>;
+  constructor(options: ValueWriterOptions);
+  /** Writes the value's first batch; async parts follow in later batches. */
+  write(value: unknown): Promise<void>;
+  /**
+   * Whether {@link ValueWriter.abort} stopped the value before all of it was written: a promise
+   * still unsettled, an iterable not yet ended.
+   */
+  get cutShort(): boolean;
+  /** Stops every iterable still being read, and settles `done`. */
+  abort(): void;
+}
+/**
+ * Writes `value` completely: every promise settled, so the batches can be sent at once. For
+ * arguments, which a browser sends in one request.
+ */
+export declare function serializeAll(value: unknown, options: Omit<ValueWriterOptions, "onBatch">): Promise<Frame[][]>;
+/** Options for {@link ValueReader}. */
+export interface ValueReaderOptions {
+  /** The function a Server Function ID stands for; absent: a reference is refused. */
+  readonly serverFunction?: (id: string) => AnyFunction;
+  /**
+   * `argument`: what a page sent, read where server code runs: no symbols, no async iterables,
+   * bigints of at most {@link ARGUMENT_BIGINT_DIGITS_MAX} digits, the writer's own limits. Default
+   * `result`: everything the writer writes.
+   */
+  readonly mode?: SerializeMode;
+}
+/**
+ * Reads batches back into a value. `root` resolves once the first batch arrived; promises and
+ * async iterables in it settle and yield as later batches arrive. A malformed batch throws a
+ * {@link SerializationError} from `push`; `fail` rejects everything still open, for a stream that
+ * broke before its end.
+ */
+export declare class ValueReader {
+  #private;
+  /** The value, once the first batch arrived. */
+  readonly root: Promise<unknown>;
+  constructor(options?: ValueReaderOptions);
+  /** Whether every promise and iterable read so far has settled or ended. */
+  get complete(): boolean;
+  /** Takes one batch. */
+  push(batch: unknown): void;
+  /**
+   * Ends the value: every frame taken so far is applied, and the value must be complete. Throws a
+   * {@link SerializationError} when a promise or iterable it holds is still open or a frame names
+   * one the value never refers to, so a reader that has all the batches (a page's arguments)
+   * never hands on a promise that can't settle.
+   */
+  finish(): void;
+  /** Rejects every promise and iterable still open: the stream broke. */
+  fail(error: unknown): void;
+}
+/**
+ * Reads complete batches back into a value: every promise in it settled from the batches, every
+ * async iterable replaying its items. For arguments and stored results.
+ */
+export declare function deserializeAll(batches: readonly unknown[], options?: ValueReaderOptions): Promise<unknown>;
+/**
+ * Checks a page's argument batches without decoding them, before they reach server code: no
+ * symbol (`$S`), no async iterable (`$x`), no bigint of more than
+ * {@link ARGUMENT_BIGINT_DIGITS_MAX} digits. The supervisor runs it so such arguments are refused
+ * before any worker sees them (Opus review 1); the worker's reader refuses them again.
+ *
+ * @throws SerializationError naming what was found.
+ */
+export declare function checkArgumentFrames(batches: readonly unknown[]): void;
+//#endregion
+//# sourceMappingURL=serializer.d.ts.map

package/dist/serializer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"serializer.d.ts","names":[],"sources":["../src/serializer.ts"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;YA8BY;WAEG;WAAoB;;WAEpB;WAAoB;;WACpB;WAAoB,GAAG;;WAEvB;WAAoB;;WACpB;WAAoB;;WACpB;WAAoB,GAAG;;;iBAMrB;;WAEN;;WAEA;;;YAIC,kBAAkB;;YAGlB;;;;;;qBAOC;;qBAGA;;qBAGA,2BAA2B;;WAE7B;;WAEA;EACT,YAAY,iBAAiB;;;wBAkBf,UAAU,iBAAiB;;qBAS9B,oBAAoB;;WAEtB;EACT,YAAY,OAAO;;;wBAcL,SAAS,OAAO;;wBAwBhB,WAAW,eAAe;;iBA6GzB;;WAEN,MAAM;;WAEN,UAAU,OAAO;;;;;WAKjB,oBAAoB,IAAI;;;;;;;;qBAStB;;;WAaF,MAAM;EAEf,YAAY,SAAS;;EAYrB,MAAY,iBAAiB;;;;;MA8BzB;;EAKJ;;;;;;wBA0WoB,aACpB,gBACA,SAAS,KAAK,iCACb,QAAQ;;iBAWM;;WAEN,kBAAkB,eAAe;;;;;;WAMjC,OAAO;;;;;;;;qBAiGL;;;WAYF,MAAM;EAEf,YAAY,UAAS;;MAKjB;;EASJ,KAAK;;;;;;;EAiCL;;EAaA,KAAK;;;;;;wBAyQe,eACpB,6BACA,UAAS,qBACR;;;;;;;;;wBAoBa,oBAAoB"}