@procedures/client 0.37.0 → 0.39.0

package/src/procedures/types.ts

@@ -38,7 +38,7 @@ export type ProcedurePath = string[];
  * `%` as `%25` and `.` as `%2E` (`encodeSegment()`, roadmap CLI-75). Thus the key of
  * `["a.b", "c"]` is `a%2Eb.c`, and not the key of `["a", "b", "c"]`. A plain path keeps its key.
  */
-export function pathToKey(path: ProcedurePath): string {
+export function pathToKey(path: readonly string[]): string {
   return segmentsToTopic(path);
 }
 

package/src/server/index.ts

@@ -43,7 +43,8 @@ export type { ServerOptions } from "./server.js";
 export type { ServerErrorPolicy, ExposedError, ErrorCall } from "./error-policy.js";
 export { exposeError, lastResortError, HIDDEN_ERROR_MESSAGE, DEFAULT_KEPT_METADATA } from "./error-policy.js";
 
-export { ProcedureServer, createProcedureServer, STREAM_METADATA_KEY, isUnboundedStream } from "./procedure-server.js";
+export { ProcedureServer, createProcedureServer } from "./procedure-server.js";
+export { STREAM_METADATA_KEY, isUnboundedStream } from "./stream-metadata.js";
 export type { ProcedureServerOptions, RegisterProcedureOptions, StorageConfig, StopOptions, StopParts, StorageHandle, UseStorageOptions } from "./procedure-server.js";
 export { pathToMethod, methodToPath, methodName } from "./method.js";
 // The escape of a segment with a dot, for a method name, a key and a topic (roadmap CLI-75)

package/src/server/procedure-server.ts

@@ -12,6 +12,7 @@ export { errorResponse };
 import type { Admission, AmbientCredentials, Credentials, Method, Principal, PrincipalOf, RequestIdentity, ServerHandler, ServerRequest, ServerResponse } from "./types.js";
 import { methodToPath, pathToMethod } from "./method.js";
 import { isLocalCredentials } from "./request-auth.js";
+import { STREAM_METADATA_KEY } from "./stream-metadata.js";
 import type {
   AnyProcedure,
   ProcedurePath,
@@ -230,17 +231,6 @@ export interface RegisterProcedureOptions {
   alwaysOn?: boolean | undefined;
 }
 
-/**
- * The metadata key of a stream response whose procedure declares `stream: { unbounded: true }`.
- * Its value is "unbounded".
- */
-export const STREAM_METADATA_KEY = "stream";
-
-/** True when a stream response can run without an end (roadmap R15). */
-export function isUnboundedStream(response: { metadata?: Record<string, unknown> | undefined }): boolean {
-  return response.metadata?.[STREAM_METADATA_KEY] === "unbounded";
-}
-
 /**
  * True when the presented token is the expected one. The comparison reads each character of the
  * expected token for each presented token, so its time depends only on the expected token. The
@@ -1274,6 +1264,7 @@ export class ProcedureServer extends Server implements RepositoryProvider, StopP
       else byStorage.set(storage, [name]);
     }
     return Array.from(byStorage, ([storage, collections]) => ({
+      // path-check: the name of a health dependency, not a topic.
       name: `collections.${collections.join("+")}`,
       collections,
       storage,

package/src/server/stream-metadata.ts

@@ -0,0 +1,16 @@
+/**
+ * The metadata of an unbounded stream response (roadmap R15). `ProcedureServer` writes it, and the
+ * HTTP server transport reads it. This module has no import, so a transport can use it without an
+ * import of the server (invariant I9, roadmap CLI-83).
+ */
+
+/**
+ * The metadata key of a stream response whose procedure declares `stream: { unbounded: true }`.
+ * Its value is "unbounded".
+ */
+export const STREAM_METADATA_KEY = "stream";
+
+/** True when a stream response can run without an end (roadmap R15). */
+export function isUnboundedStream(response: { metadata?: Record<string, unknown> | undefined }): boolean {
+  return response.metadata?.[STREAM_METADATA_KEY] === "unbounded";
+}

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();
+    },
+  };
+}