@procedures/client 0.38.0 → 0.40.0

package/src/adapters/websocket/client/transport.ts

@@ -5,7 +5,7 @@
  * Supports automatic reconnection, heartbeats, and streaming.
  */
 
-import type { Transport, Message, ResponseItem } from "../../../client/types.js";
+import { ClientError, type Transport, type Message, type ResponseItem } from "../../../client/types.js";
 import type { WebSocketTransportOptions, WebSocketMessage, ServerRequestHandler, EventHandler, WebSocketClass } from "./types.js";
 import { WebSocketState } from "./types.js";
 import { withoutInternalKeys } from "../../metadata.js";
@@ -133,6 +133,19 @@ function detach(ws: WebSocket): void {
   ws.onerror = ignoreError;
 }
 
+/** The close code of a message above the limit of the other side (RFC 6455, 1009). */
+const MESSAGE_TOO_BIG = 1009;
+
+/**
+ * The error of a pending call when the server closes the connection with 1009: a message was
+ * above the limit of the server (`maxPayload`). The close drops each pending call of the
+ * connection, so each gets this error (CLI-85). Before, each got an error without a code.
+ */
+function tooLarge(id: string): ClientError {
+  const message = "The server closed the connection: a message was larger than its limit (1009)";
+  return new ClientError({ type: "error", code: "PAYLOAD_TOO_LARGE", message, retryable: false }, id);
+}
+
 function errorItem<TRes>(id: string, code: string, message: string, retryable: boolean): ResponseItem<TRes> {
   return { id, status: { type: "error", code, message, retryable }, payload: null as TRes, metadata: {} };
 }
@@ -375,7 +388,7 @@ export class WebSocketTransport implements Transport {
       ws.onclose = (event) => {
         if (this.ws !== ws) return;
         this.ws = null;
-        this.handleClose(event.reason);
+        this.handleClose(event.reason, event.code);
       };
 
       // Connection error
@@ -422,9 +435,9 @@ export class WebSocketTransport implements Transport {
   }
 
   /** Fail every request in progress (a stream ends with the error too). */
-  private failPending(reason: string): void {
-    for (const pending of this.pendingRequests.values()) {
-      pending.queue.fail(new Error(reason));
+  private failPending(reason: string, closeCode?: number): void {
+    for (const [id, pending] of this.pendingRequests) {
+      pending.queue.fail(closeCode === MESSAGE_TOO_BIG ? tooLarge(id) : new Error(reason));
       pending.timeout?.();
     }
     this.pendingRequests.clear();
@@ -433,7 +446,7 @@ export class WebSocketTransport implements Transport {
   /**
    * Handle WebSocket close.
    */
-  private handleClose(reason?: string): void {
+  private handleClose(reason?: string, closeCode?: number): void {
     this.stopHeartbeat();
     this.incoming?.abortAll();
     this.incoming = undefined;
@@ -450,7 +463,7 @@ export class WebSocketTransport implements Transport {
       this.options.onDisconnect(reason);
     }
 
-    this.failPending("WebSocket connection closed");
+    this.failPending("WebSocket connection closed", closeCode);
 
     if (willReconnect) {
       this.scheduleReconnect();

package/src/testing/index.ts

@@ -0,0 +1,31 @@
+/**
+ * The entry point "@procedures/client/testing" (roadmap CLI-85): the transport contract, for the
+ * test files of each face of the procedures server. A face in another package, or the server of
+ * an app, runs the same cases as the faces of this package. `WIRE-PROTOCOL.md` is the contract.
+ *
+ * It imports no test runner: the caller gives the functions of its runner (`ContractRunner`).
+ */
+
+export {
+  CONTRACT_COLLECTION,
+  CONTRACT_PATHS,
+  CONTRACT_PRINCIPAL,
+  CONTRACT_TOKEN,
+  clientCaller,
+  contractDescription,
+  describeTransportContract,
+} from "./transport-contract.js";
+export type {
+  ContractCallOptions,
+  ContractCaller,
+  ContractCapabilities,
+  ContractCase,
+  ContractExpectation,
+  ContractFace,
+  ContractRunner,
+  ContractServer,
+  ContractSpec,
+} from "./transport-contract.js";
+export { mcpCaller } from "./mcp-caller.js";
+export type { McpClientLike } from "./mcp-caller.js";
+export { LogStorage } from "./log-storage.js";

package/src/testing/log-storage.ts

@@ -0,0 +1,72 @@
+/**
+ * A collection storage of a Map with a change log (`v:<number>`), for the tests (CLI-85). The
+ * transport contract serves its collection from it.
+ */
+
+import type { CollectionStorage, StorageChanges } from "../procedures/collection/storage.js";
+
+export class LogStorage implements CollectionStorage<unknown> {
+  readonly data: Map<string, unknown> = new Map();
+  private seq = 0;
+  private readonly changedAt = new Map<string, number>();
+  private readonly deletedAt = new Map<string, number>();
+
+  /** The items are in the storage before the first version: a delta does not have them. */
+  constructor(items: Record<string, unknown> = {}) {
+    for (const [id, value] of Object.entries(items)) this.data.set(id, value);
+  }
+  async get(id: string): Promise<unknown> {
+    return this.data.get(id);
+  }
+  async getAll(): Promise<unknown[]> {
+    return [...this.data.values()];
+  }
+  async getEntries(): Promise<Array<[string, unknown]>> {
+    return [...this.data.entries()];
+  }
+  async getChangesSince(since?: string): Promise<StorageChanges<unknown>> {
+    const version = `v:${this.seq}`;
+    if (since === undefined) return { version, full: true, changed: [...this.data.entries()], deleted: [] };
+    const from = Number(since.slice(2));
+    const changed = [...this.changedAt].filter(([, at]) => at > from).map(([id]): [string, unknown] => [id, this.data.get(id)]);
+    const deleted = [...this.deletedAt].filter(([, at]) => at > from).map(([id]) => id);
+    return { version, full: false, changed, deleted };
+  }
+  async find(predicate: (item: unknown) => boolean): Promise<unknown[]> {
+    return [...this.data.values()].filter(predicate);
+  }
+  async has(id: string): Promise<boolean> {
+    return this.data.has(id);
+  }
+  async size(): Promise<number> {
+    return this.data.size;
+  }
+  async set(id: string, value: unknown): Promise<void> {
+    this.data.set(id, value);
+    this.changedAt.set(id, ++this.seq);
+    this.deletedAt.delete(id);
+  }
+  async delete(id: string): Promise<boolean> {
+    const existed = this.data.delete(id);
+    if (existed) {
+      this.deletedAt.set(id, ++this.seq);
+      this.changedAt.delete(id);
+    }
+    return existed;
+  }
+  async clear(): Promise<void> {
+    for (const id of [...this.data.keys()]) await this.delete(id);
+  }
+  async setBatch(items: Array<[string, unknown]>): Promise<void> {
+    for (const [id, value] of items) await this.set(id, value);
+  }
+  async deleteBatch(ids: string[]): Promise<number> {
+    let count = 0;
+    for (const id of ids) if (await this.delete(id)) count++;
+    return count;
+  }
+  async getBatch(ids: string[]): Promise<Map<string, unknown>> {
+    return new Map(ids.filter((id) => this.data.has(id)).map((id): [string, unknown] => [id, this.data.get(id)]));
+  }
+  async close(): Promise<void> {}
+}

package/src/testing/mcp-caller.ts

@@ -0,0 +1,100 @@
+/**
+ * A caller of the transport contract over an MCP client (CLI-85). The MCP faces of `client-mcp`
+ * and of a host in `client-server` use it. It has no import of the MCP SDK: the face gives the
+ * client, so the caller works with the copy of the SDK of each package.
+ *
+ * An MCP tool call is one result. A stream comes back as one result with a text block for each
+ * item. An error result has `isError`, its code and its flag in `_meta`, and its message in the
+ * last text block.
+ */
+
+import { pathToKey } from "../index.js";
+import { contractDescription, type ContractCaller } from "./transport-contract.js";
+
+/** The parts of an MCP client of the SDK that the caller uses. */
+export interface McpClientLike {
+  listTools(): Promise<{ tools: Array<{ name: string; description?: string | undefined }> }>;
+  callTool(params: { name: string; arguments?: Record<string, unknown> }, resultSchema?: undefined, options?: { signal?: AbortSignal }): Promise<unknown>;
+  close(): Promise<void>;
+}
+
+type ToolResult = { content?: Array<{ type: string; text?: string }>; isError?: boolean; _meta?: Record<string, unknown> };
+
+/** The value of a text block: JSON, or the text itself. */
+function valueOf(text: string | undefined): unknown {
+  if (text === undefined) return undefined;
+  try {
+    return JSON.parse(text);
+  } catch {
+    return text;
+  }
+}
+
+/**
+ * The error of an error result: the code and the flag of `_meta`, and the message of the last text
+ * block. The blocks of a stream that fails are its items, then the message of the error.
+ */
+function errorOf(result: ToolResult): Error {
+  const meta = result._meta ?? {};
+  return Object.assign(new Error(result.content?.at(-1)?.text ?? ""), { code: meta["code"], retryable: meta["retryable"] === true, metadata: meta });
+}
+
+/**
+ * The error of a refusal of the HTTP endpoint, before the tool call: the SDK puts the JSON-RPC
+ * body of the refusal in its message. Its `data.code` is the code of the refusal.
+ */
+function refusalOf(error: unknown): unknown {
+  const message = error instanceof Error ? error.message : String(error);
+  const start = message.indexOf("{");
+  if (start < 0) return error;
+  try {
+    const body = JSON.parse(message.slice(start)) as { error?: { message?: string; data?: { code?: string; retryable?: boolean } } };
+    const code = body.error?.data?.code;
+    if (code === undefined) return error;
+    return Object.assign(new Error(body.error?.message ?? message), { code, retryable: body.error?.data?.retryable === true });
+  } catch {
+    return error;
+  }
+}
+
+/**
+ * A caller of an MCP client. It finds the tool of a path by the description of the procedure, so
+ * it does not depend on the form of a tool name. The client connects at its first call, so a
+ * refusal of the connection is the error of that call.
+ */
+export function mcpCaller(open: () => Promise<McpClientLike>): ContractCaller {
+  let client: Promise<{ mcp: McpClientLike; names: Map<string, string> }> | undefined;
+  const connect = () =>
+    (client ??= (async () => {
+      const mcp = await open();
+      const { tools } = await mcp.listTools();
+      return { mcp, names: new Map(tools.map((tool) => [tool.description ?? "", tool.name])) };
+    })());
+  const call = async (path: readonly string[], input: unknown, signal?: AbortSignal): Promise<ToolResult> => {
+    try {
+      const { mcp, names } = await connect();
+      const name = names.get(contractDescription(path)) ?? pathToKey(path);
+      return (await mcp.callTool({ name, arguments: input as Record<string, unknown> }, undefined, signal ? { signal } : {})) as ToolResult;
+    } catch (error) {
+      throw refusalOf(error);
+    }
+  };
+  return {
+    async call(path, input, options) {
+      const result = await call(path, input, options?.signal);
+      if (result.isError) throw errorOf(result);
+      return valueOf(result.content?.[0]?.text);
+    },
+    async *stream(path, input, options) {
+      const result = await call(path, input, options?.signal);
+      if (result.isError) throw errorOf(result);
+      // A stream without items gives one block "(no items)" for the reader of the result
+      const blocks = result.content ?? [];
+      if (blocks.length === 1 && blocks[0]!.text === "(no items)") return;
+      for (const block of blocks) yield valueOf(block.text);
+    },
+    async close() {
+      if (client) await (await client.catch(() => undefined))?.mcp.close();
+    },
+  };
+}