@procedures/client 0.2.3 → 0.4.0

package/src/protocol.ts

@@ -0,0 +1,108 @@
+/**
+ * Wire protocol v1 (roadmap R25). `documentation/WIRE-PROTOCOL.md` specifies the formats.
+ *
+ * - The version: a WebSocket connection starts with a `hello` frame of each side, and an HTTP
+ *   request and its response carry the `Procedures-Protocol` header. A side refuses a newer
+ *   version with `PROTOCOL_VERSION`.
+ * - One list of error codes for all faces, with the HTTP status of each.
+ * - A change after v1 adds only optional fields, or it makes v2.
+ */
+
+/** The version of the wire protocol that this package speaks. */
+export const PROTOCOL_VERSION = 1;
+
+/** The HTTP header of the protocol version, on a request and on its response. */
+export const PROTOCOL_HEADER = "Procedures-Protocol";
+
+/** The facts of one error code. */
+export interface ErrorCodeInfo {
+  /** The HTTP status of an error with this code. */
+  readonly http: number;
+  /** True when a retry of the same call can succeed. The error item can say otherwise. */
+  readonly retryable: boolean;
+  /** What the code means. */
+  readonly meaning: string;
+}
+
+/** An error code of the protocol. */
+export type ProtocolErrorCode =
+  | "NOT_FOUND"
+  | "NO_HANDLER"
+  | "NOT_EXPOSED"
+  | "NOT_DECLARED"
+  | "FORBIDDEN"
+  | "UNAUTHORIZED"
+  | "VALIDATION_ERROR"
+  | "INVALID_REQUEST"
+  | "PROTOCOL_VERSION"
+  | "OUTPUT_VALIDATION_ERROR"
+  | "NO_OUTPUT"
+  | "HANDLER_ERROR"
+  | "INTERNAL_ERROR"
+  | "NOT_ACCEPTABLE"
+  | "DUPLICATE"
+  | "DUPLICATE_REQUEST"
+  | "ABORTED"
+  | "TIMEOUT"
+  | "UNAVAILABLE"
+  | "CONNECTION_CLOSED"
+  | "CONNECTION_NOT_FOUND";
+
+/**
+ * The error codes of the protocol, on each face (HTTP, WebSocket, MCP, local). An error that a
+ * handler throws with its own `code` keeps it, for a value and for a stream (`errorCodeOf`). The
+ * HTTP status follows the code: the status of this list, the status of `ERROR_REGISTRY` for
+ * another known code, or 500.
+ */
+export const ERROR_CODES: Readonly<Record<ProtocolErrorCode, ErrorCodeInfo>> = {
+  NOT_FOUND: { http: 404, retryable: false, meaning: "No procedure has the path, or the host does not expose it" },
+  NO_HANDLER: { http: 404, retryable: false, meaning: "The procedure has no handler here (a stub of a remote host)" },
+  NOT_EXPOSED: { http: 403, retryable: false, meaning: "A nested call reached a procedure that the host does not expose" },
+  NOT_DECLARED: { http: 403, retryable: false, meaning: "A nested call is not in the calls that the procedure declares" },
+  FORBIDDEN: { http: 403, retryable: false, meaning: "The capability of the call refuses it. The metadata key reason tells why" },
+  UNAUTHORIZED: { http: 401, retryable: false, meaning: "The request does not present the token of the server" },
+  VALIDATION_ERROR: { http: 400, retryable: false, meaning: "The input does not agree with the input schema" },
+  INVALID_REQUEST: { http: 400, retryable: false, meaning: "The request is not a valid request of the protocol" },
+  PROTOCOL_VERSION: { http: 400, retryable: false, meaning: "The other side speaks a newer version of the protocol" },
+  OUTPUT_VALIDATION_ERROR: { http: 500, retryable: false, meaning: "The output does not agree with the output schema" },
+  NO_OUTPUT: { http: 500, retryable: false, meaning: "The procedure gave no output" },
+  HANDLER_ERROR: { http: 500, retryable: false, meaning: "The handler threw an error without a code" },
+  INTERNAL_ERROR: { http: 500, retryable: false, meaning: "The server failed outside the handler" },
+  NOT_ACCEPTABLE: { http: 406, retryable: false, meaning: "The face cannot give the output: a stream without an end, without NDJSON" },
+  DUPLICATE: { http: 409, retryable: false, meaning: "An idempotency key gave a stream, and a stream cannot be given again" },
+  DUPLICATE_REQUEST: { http: 409, retryable: false, meaning: "A request with this id is still running on the connection" },
+  ABORTED: { http: 499, retryable: false, meaning: "The caller aborted the call" },
+  TIMEOUT: { http: 504, retryable: false, meaning: "The deadline of the call passed" },
+  UNAVAILABLE: { http: 503, retryable: true, meaning: "The server cannot take the call now: it stops, or it is busy" },
+  CONNECTION_CLOSED: { http: 503, retryable: true, meaning: "The connection closed before the call left" },
+  CONNECTION_NOT_FOUND: { http: 404, retryable: false, meaning: "The server has no connection with this id" },
+};
+
+/** True when a code is an error code of the protocol. */
+export function isProtocolErrorCode(code: unknown): code is ProtocolErrorCode {
+  return typeof code === "string" && Object.prototype.hasOwnProperty.call(ERROR_CODES, code);
+}
+
+/**
+ * The code of an error that a handler or an invocation throws, on each face: its own code when
+ * it is a string, or `HANDLER_ERROR`. An invocation error has a code of this list. Before, a
+ * value lost the own code of a handler error, and a stream kept it (roadmap R30).
+ */
+export function errorCodeOf(error: unknown): string {
+  const code = (error as { code?: unknown } | null | undefined)?.code;
+  return typeof code === "string" ? code : "HANDLER_ERROR";
+}
+
+/** The HTTP status of an error code, or undefined for a code that is not in the list. */
+export function httpStatusOf(code: unknown): number | undefined {
+  return isProtocolErrorCode(code) ? ERROR_CODES[code].http : undefined;
+}
+
+/**
+ * The protocol version that a peer sends, or undefined when it sends none (an older peer, which
+ * speaks the formats of v1 without the version).
+ */
+export function protocolVersionOf(value: unknown): number | undefined {
+  const version = typeof value === "number" ? value : typeof value === "string" ? Number(value) : NaN;
+  return Number.isInteger(version) && version > 0 ? version : undefined;
+}

package/src/server/host-policy.ts

@@ -10,7 +10,7 @@
  *   procedure.
  * - `strictCalls`: a procedure of code that declares no `metadata.calls` calls only exposed
  *   procedures (a host for an outside caller sets it).
- * - `timeoutMs`: the time limit of each call from a caller (not of its nested calls).
+ * - `timeout`: the time limit of each call from a caller (not of its nested calls).
  * - `token`, `browser`: the checks of the network transports (`client-server` applies them).
  * - `capability`, `readOnly`, `clearanceOrder`, `resources`, `admitItem`: the capability of each
  *   call and what the host gives for it (CAPABILITIES-2026-10).
@@ -24,6 +24,7 @@ import { timeoutInterceptor } from "../procedures/interceptors.js";
 import type { BrowserGuardOptions } from "./browser-guard.js";
 import type { ProcedureRegistry } from "../procedures/registry.js";
 import type { ProcedureServerOptions } from "./procedure-server.js";
+import { toMs, type Duration } from "../duration.js";
 
 /** The procedures of a host that are tools: namespaces (first path segments), less some keys. */
 export interface ToolSurface {
@@ -63,8 +64,8 @@ export interface HostPolicyOptions {
   exclude?: readonly string[] | undefined;
   /** A procedure of code with no `metadata.calls` calls only exposed procedures. */
   strictCalls?: boolean | undefined;
-  /** The time limit of each call from a caller, in milliseconds. 0 or no value: no limit. */
-  timeoutMs?: number | undefined;
+  /** The time limit of each call from a caller, for example `minutes(10)`. 0 or no value: no limit. */
+  timeout?: Duration | undefined;
   /** More interceptors, after the policy's own (tracing, metrics). */
   interceptors?: readonly Interceptor[] | undefined;
   /** The token that each network request must send (HTTP and WebSocket transports). */
@@ -130,8 +131,8 @@ function exposeOf(options: HostPolicyOptions): ((path: ProcedurePath) => boolean
 /** This function builds the policy of a host from its options. */
 export function hostPolicy(options: HostPolicyOptions = {}): HostPolicy {
   const interceptors: Interceptor[] = [];
-  if (options.timeoutMs !== undefined && options.timeoutMs > 0) {
-    interceptors.push(timeoutInterceptor({ ms: options.timeoutMs }));
+  if (options.timeout !== undefined && toMs(options.timeout, "timeout") > 0) {
+    interceptors.push(timeoutInterceptor({ limit: options.timeout }));
   }
   interceptors.push(...(options.interceptors ?? []));
   return {
@@ -154,6 +155,8 @@ export function procedureServerOptions(policy: HostPolicy, registry?: ProcedureR
     ...(registry ? { registry } : {}),
     ...(policy.expose ? { expose: policy.expose } : {}),
     strictCalls: policy.strictCalls,
+    // The token of the policy: ProcedureServer examines it for each network request (R18)
+    ...(policy.token !== undefined ? { token: policy.token } : {}),
     ...(policy.interceptors.length > 0 ? { interceptors: policy.interceptors } : {}),
     ...(policy.capabilityOf ? { capability: policy.capabilityOf } : {}),
     ...(policy.clearanceOrder ? { clearanceOrder: policy.clearanceOrder } : {}),

package/src/server/host-procedures.ts

@@ -0,0 +1,102 @@
+/**
+ * The procedures of a host (roadmap R19): `host.health`, `host.info` and `host.metrics`.
+ *
+ * Before, a peer gave its health only as an Express route (`/health`), and the counts of
+ * `metricsInterceptor` had no way out. A host pins these procedures on its `ProcedureServer`
+ * (`registerProcedure`), so they do not change the registry that the host serves. A call needs
+ * the token of the host, as each other call does. The `/health` route stays for the checks
+ * that have no token.
+ */
+
+import { z } from "zod";
+import { createProcedure } from "../procedures/define.js";
+import { PURE_EFFECTS } from "../procedures/effects.js";
+import type { AnyProcedure } from "../procedures/types.js";
+import type { MetricsInterceptor } from "../procedures/interceptors.js";
+import type { ProcedureServer } from "./procedure-server.js";
+
+/** What a host tells about itself. */
+export interface HostSource {
+  /** The id of the host (the peer id). */
+  readonly id: string;
+  /** The time at which the host started, from `Date.now()`. */
+  readonly startedAt: number;
+  /** The server of the host. */
+  readonly server: ProcedureServer;
+  /** The endpoints of the host, when it has network transports. */
+  readonly endpoints?: (() => ReadonlyArray<{ type: string; address: string }>) | undefined;
+  /** The metrics interceptor of the host, when it counts its calls. */
+  readonly metrics?: MetricsInterceptor | undefined;
+}
+
+const healthOutput = z.object({
+  status: z.enum(["ok", "stopping"]).describe("ok, or stopping while the host waits for its calls in flight"),
+  uptimeMs: z.number().describe("The time since the start of the host, in milliseconds"),
+  procedures: z.number().describe("The number of procedures that the host serves"),
+  callsInFlight: z.number().describe("The calls that run now, streams included"),
+  peerId: z.string().describe("The id of the host"),
+});
+
+const infoOutput = z.object({
+  peerId: z.string().describe("The id of the host"),
+  startedAt: z.string().describe("The start time of the host (ISO 8601)"),
+  endpoints: z.array(z.object({ type: z.string(), address: z.string() })).describe("The network endpoints of the host"),
+  runtime: z.string().describe("The runtime of the host, for example node 24.1.0"),
+});
+
+const metricsOutput = z.object({
+  procedures: z
+    .record(
+      z.string(),
+      z.object({ calls: z.number(), errors: z.number(), totalMs: z.number(), maxMs: z.number() }),
+    )
+    .describe("The calls, the errors and the time of each procedure since the start, by key"),
+});
+
+/** The runtime of this process: its name and version. */
+function runtimeOf(): string {
+  const process = (globalThis as { process?: { versions?: { node?: string } } }).process;
+  if (process?.versions?.node) return `node ${process.versions.node}`;
+  const navigator = (globalThis as { navigator?: { userAgent?: string } }).navigator;
+  return navigator?.userAgent ?? "unknown";
+}
+
+/** This function gives the procedures of a host: `host.health`, `host.info` and `host.metrics`. */
+export function hostProcedures(source: HostSource): AnyProcedure[] {
+  const health = createProcedure()
+    .path(["host", "health"])
+    .input(z.object({}))
+    .output(healthOutput)
+    .meta({ description: "The health of the host: its state, its uptime and its calls in flight", effects: PURE_EFFECTS })
+    .handler(async () => ({
+      status: source.server.stopping ? ("stopping" as const) : ("ok" as const),
+      uptimeMs: Date.now() - source.startedAt,
+      procedures: source.server.procedureCount,
+      callsInFlight: source.server.callsInFlight,
+      peerId: source.id,
+    }))
+    .build();
+
+  const info = createProcedure()
+    .path(["host", "info"])
+    .input(z.object({}))
+    .output(infoOutput)
+    .meta({ description: "The identity of the host: its id, its start time, its endpoints and its runtime", effects: PURE_EFFECTS })
+    .handler(async () => ({
+      peerId: source.id,
+      startedAt: new Date(source.startedAt).toISOString(),
+      endpoints: [...(source.endpoints?.() ?? [])],
+      runtime: runtimeOf(),
+    }))
+    .build();
+
+  const metrics = createProcedure()
+    .path(["host", "metrics"])
+    .input(z.object({}))
+    .output(metricsOutput)
+    .meta({ description: "The calls, the errors and the time of each procedure since the start of the host", effects: PURE_EFFECTS })
+    .handler(async () => ({ procedures: source.metrics?.snapshot() ?? {} }))
+    .build();
+
+  return [health, info, metrics] as AnyProcedure[];
+}

package/src/server/index.ts

@@ -37,14 +37,17 @@
 export { Server } from "./server.js";
 export type { ServerOptions } from "./server.js";
 
-export { ProcedureServer, createProcedureServer } from "./procedure-server.js";
-export type { ProcedureServerOptions, StorageConfig } from "./procedure-server.js";
+export { ProcedureServer, createProcedureServer, STREAM_METADATA_KEY, isUnboundedStream } from "./procedure-server.js";
+export type { ProcedureServerOptions, StorageConfig, StopOptions, UseStorageOptions } from "./procedure-server.js";
 export { pathToMethod, methodToPath } from "./method.js";
 export {
   HandlerNotFoundError,
   ServerError,
   type ServerRequest,
   type ServerResponse,
+  type RequestHandler,
+  type Credentials,
+  type Principal,
   type ServerHandler,
   type ServerMiddleware,
   type ServerContext,