@procedures/client 0.2.3 → 0.4.0

package/src/adapters/http/shared/headers.ts

@@ -95,7 +95,7 @@ export interface HeaderConverter {
  * Implements standard conventions for converting metadata to headers:
  * - Auth: Bearer token, API key
  * - Tracing: X-Trace-Id, X-Span-Id format
- * - Timeouts: X-Timeout header
+ * - The deadline: `procedure-timeout` in X-Metadata (no X-Timeout header)
  * - Custom fields: Pass through as-is
  */
 export class DefaultHeaderConverter implements HeaderConverter {
@@ -120,7 +120,10 @@ export class DefaultHeaderConverter implements HeaderConverter {
       headers[HTTPHeaders.API_KEY] = metadata.auth.apiKey;
     }
 
-    // Distributed Tracing
+    // Distributed Tracing: the W3C trace context, and the older headers (roadmap R16)
+    if (typeof metadata["traceparent"] === "string") {
+      headers["traceparent"] = metadata["traceparent"];
+    }
     if (metadata.tracing?.traceId) {
       headers[HTTPHeaders.TRACE_ID] = metadata.tracing.traceId;
     }
@@ -131,10 +134,8 @@ export class DefaultHeaderConverter implements HeaderConverter {
       headers[HTTPHeaders.PARENT_SPAN_ID] = metadata.tracing.parentSpanId;
     }
 
-    // Timeouts
-    if (metadata.timeout?.overall) {
-      headers[HTTPHeaders.TIMEOUT] = String(metadata.timeout.overall);
-    }
+    // No X-Timeout: the remaining time of the deadline goes as procedure-timeout in X-Metadata,
+    // which the server uses (roadmap R10). The server ignored X-Timeout.
 
     const custom: Record<string, unknown> = {};
     for (const [key, value] of Object.entries(metadata)) {

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

@@ -9,8 +9,41 @@ import type { Handler, LocalTransportOptions } from "./types.js";
 import { methodKey } from "./types.js";
 import type { ProcedureRegistry } from "../../../procedures/registry.js";
 import type { AnyProcedure } from "../../../procedures/types.js";
-import { InvocationError, invokeProcedure, isAsyncIterable } from "../../../procedures/invoke.js";
+import { InvocationError, invokeProcedure, isAsyncIterable, type Interceptor } from "../../../procedures/invoke.js";
+import { TIMEOUT_METADATA_KEY } from "../../../client/deadline.js";
+import { narrowCapability } from "../../../procedures/capability.js";
+import type { Capability, ClearanceOrder } from "../../../procedures/types.js";
 import { methodToPath } from "../../../server/method.js";
+import { errorCodeOf } from "../../../protocol.js";
+
+/** The value of `untilAborted` when the signal aborts first. */
+const ABORTED: unique symbol = Symbol("aborted");
+
+/** The value of a promise, or ABORTED when the signal aborts first. The promise runs on. */
+function untilAborted<T>(promise: Promise<T>, signal: AbortSignal | undefined): Promise<T | typeof ABORTED> {
+  if (!signal) return promise;
+  if (signal.aborted) {
+    promise.catch(() => undefined);
+    return Promise.resolve(ABORTED);
+  }
+  return new Promise((resolve, reject) => {
+    const onAbort = (): void => {
+      promise.catch(() => undefined);
+      resolve(ABORTED);
+    };
+    signal.addEventListener("abort", onAbort, { once: true });
+    promise.then(
+      (value) => {
+        signal.removeEventListener("abort", onAbort);
+        resolve(value);
+      },
+      (error: unknown) => {
+        signal.removeEventListener("abort", onAbort);
+        reject(error);
+      },
+    );
+  });
+}
 
 function successItem<TRes>(id: string, payload: unknown): ResponseItem<TRes> {
   return { id, status: { type: "success", code: 200 }, payload: payload as TRes, metadata: {} };
@@ -53,10 +86,16 @@ export class LocalTransport implements Transport {
   private readonly handlers = new Map<string, Handler>();
   private readonly throwOnMissing: boolean;
   private readonly registry: ProcedureRegistry | undefined;
+  private readonly interceptors: readonly Interceptor[] | undefined;
+  private readonly capability: Capability | undefined;
+  private readonly clearanceOrder: ClearanceOrder | undefined;
 
   constructor(options: LocalTransportOptions = {}) {
     this.throwOnMissing = options.throwOnMissing !== false;
     this.registry = options.registry;
+    this.interceptors = options.interceptors;
+    this.capability = options.capability;
+    this.clearanceOrder = options.clearanceOrder;
 
     // Register pre-configured handlers. A key without a version ("users.get") gets the
     // empty version, as methodKey() makes it: before, such a key was never found.
@@ -136,21 +175,44 @@ export class LocalTransport implements Transport {
       let values: AsyncIterable<unknown> | undefined;
       let value: unknown;
       if (procedure) {
-        const output = await invokeProcedure(procedure, message.payload, {
+        // The interceptors, the capability and the deadline of the call, as on a server (R14)
+        const timeoutMs = message.metadata[TIMEOUT_METADATA_KEY];
+        const capability =
+          typeof timeoutMs === "number" && Number.isFinite(timeoutMs) && timeoutMs >= 0
+            ? narrowCapability(this.capability, { timeoutMs }, this.clearanceOrder)
+            : this.capability;
+        const output = await untilAborted(invokeProcedure(procedure, message.payload, {
           registry: this.registry,
           metadata: message.metadata,
           signal: message.signal,
-        });
+          ...(this.interceptors ? { interceptors: this.interceptors } : {}),
+          ...(capability ? { capability } : {}),
+          ...(this.clearanceOrder ? { clearanceOrder: this.clearanceOrder } : {}),
+        }), message.signal);
+        if (output === ABORTED) {
+          // The caller stops waiting at once, as over HTTP and WebSocket (the conformance suite
+          // of roadmap R18 found this: before, a local call waited for its handler)
+          yield errorItem<TRes>(message.id, "ABORTED", "Request was aborted");
+          return;
+        }
         if (output.kind === "stream") values = output.items;
         else value = output.value;
       } else {
         // Execute handler (may be sync, async or an async generator)
-        const result = await handler!(message.payload, message);
+        const result = await untilAborted(Promise.resolve(handler!(message.payload, message)), message.signal);
+        if (result === ABORTED) {
+          yield errorItem<TRes>(message.id, "ABORTED", "Request was aborted");
+          return;
+        }
         if (isAsyncIterable(result)) values = result;
         else value = result;
       }
 
       if (values === undefined) {
+        if (message.signal?.aborted) {
+          yield errorItem<TRes>(message.id, "ABORTED", "Request was aborted");
+          return;
+        }
         yield successItem<TRes>(message.id, value);
         return;
       }
@@ -162,9 +224,13 @@ export class LocalTransport implements Transport {
         yield successItem<TRes>(message.id, item);
       }
     } catch (error) {
-      // The handler threw, or the invocation failed (its code: VALIDATION_ERROR, ABORTED and so on)
-      const code = error instanceof InvocationError ? error.code : "HANDLER_ERROR";
-      yield errorItem<TRes>(message.id, code, error instanceof Error ? error.message : "Unknown error");
+      // The handler threw, or the invocation failed (its code: VALIDATION_ERROR, ABORTED and so
+      // on). A handler error keeps its own code, as on the other faces (WIRE-PROTOCOL.md).
+      const code = errorCodeOf(error);
+      const item = errorItem<TRes>(message.id, code, error instanceof Error ? error.message : "Unknown error");
+      // The reason of a FORBIDDEN error travels on each face (roadmap R25)
+      if (error instanceof InvocationError && error.reason) item.metadata = { reason: error.reason };
+      yield item;
     }
   }
 
@@ -172,6 +238,7 @@ export class LocalTransport implements Transport {
     // No resources to clean up
   }
 
+
   /**
    * Clear all handlers.
    */

package/src/adapters/local/client/types.ts

@@ -6,6 +6,8 @@
 
 import type { Message, Method } from "../../../client/types.js";
 import type { ProcedureRegistry } from "../../../procedures/registry.js";
+import type { Interceptor } from "../../../procedures/invoke.js";
+import type { Capability, ClearanceOrder } from "../../../procedures/types.js";
 
 /**
  * Handler function for a method.
@@ -47,4 +49,20 @@ export interface LocalTransportOptions {
    * The procedure runs through `invokeProcedure()`, as on a server.
    */
   registry?: ProcedureRegistry;
+
+  /**
+   * The interceptors of each procedure that the transport runs, as on a server: policy, tracing,
+   * timeouts, metrics (roadmap R14). Before, a local call had none.
+   */
+  interceptors?: readonly Interceptor[] | undefined;
+
+  /**
+   * The capability of each call. The remaining time that a call sends (`procedure-timeout`)
+   * makes its deadline earlier, as on a server: a `Client` with a timeout gives a local call a
+   * deadline too (roadmap R14).
+   */
+  capability?: Capability | undefined;
+
+  /** The order of the clearance values of the capability. */
+  clearanceOrder?: ClearanceOrder | undefined;
 }

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

@@ -11,6 +11,7 @@ import type {
   MockTransportOptions,
   CallHistoryEntry,
 } from "./types.js";
+import { optionalMs } from "../../../duration.js";
 
 /**
  * Mock transport implementation for testing.
@@ -26,8 +27,8 @@ import type {
  * ```typescript
  * // Create mock transport with latency
  * const mock = new MockTransport({
- *   minLatency: 10,
- *   maxLatency: 50,
+ *   minLatency: ms(10),
+ *   maxLatency: ms(50),
  * });
  *
  * // Mock a specific response
@@ -57,14 +58,15 @@ import type {
 export class MockTransport implements Transport {
   readonly name = "mock";
 
-  private options: Required<MockTransportOptions>;
+  /** The options, with the latencies in milliseconds */
+  private options: Required<Omit<MockTransportOptions, "minLatency" | "maxLatency">> & { minLatency: number; maxLatency: number };
   private responses = new Map<ResponseMatcher, MockResponse>();
   private history: CallHistoryEntry[] = [];
 
   constructor(options: MockTransportOptions = {}) {
     this.options = {
-      minLatency: options.minLatency ?? 0,
-      maxLatency: options.maxLatency ?? 0,
+      minLatency: optionalMs(options.minLatency, "minLatency") ?? 0,
+      maxLatency: optionalMs(options.maxLatency, "maxLatency") ?? 0,
       failureRate: options.failureRate ?? 0,
       defaultErrorMessage: options.defaultErrorMessage ?? "Mock transport error",
       trackHistory: options.trackHistory ?? true,
@@ -247,7 +249,8 @@ export class MockTransport implements Transport {
 
     // Apply custom delay if specified
     if (mockResponse.delay !== undefined) {
-      await new Promise((resolve) => setTimeout(resolve, mockResponse.delay));
+      const delay = optionalMs(mockResponse.delay, "delay");
+      await new Promise((resolve) => setTimeout(resolve, delay));
     }
 
     // Handle error response

package/src/adapters/mock/client/types.ts

@@ -5,6 +5,7 @@
  */
 
 import type { Message, ResponseItem } from "../../../client/types.js";
+import type { Duration } from "../../../duration.js";
 
 /**
  * Mock response configuration.
@@ -26,10 +27,10 @@ export interface MockResponse<TRes = unknown> {
   error?: Error;
 
   /**
-   * Delay in milliseconds before responding
+   * Delay before responding
    * @default Uses transport's latency config
    */
-  delay?: number;
+  delay?: Duration;
 
   /**
    * Number of times this response can be used
@@ -48,16 +49,16 @@ export type ResponseMatcher = (method: any, payload: unknown) => boolean;
  */
 export interface MockTransportOptions {
   /**
-   * Minimum latency in milliseconds
+   * Minimum latency
    * @default 0
    */
-  minLatency?: number;
+  minLatency?: Duration;
 
   /**
-   * Maximum latency in milliseconds
+   * Maximum latency
    * @default 0
    */
-  maxLatency?: number;
+  maxLatency?: Duration;
 
   /**
    * Random failure rate (0-1)

package/src/adapters/port/transport.ts

@@ -0,0 +1,124 @@
+/**
+ * The transport over a message port (roadmap R27): a Web Worker, a `MessagePort` of a
+ * `MessageChannel`, an iframe, or a `worker_threads` port of Node.
+ *
+ * The two sides of a port send calls to each other with the frames of the WebSocket transport
+ * (`websocket/shared/rpc.ts`): a request, then a response, an error, or a stream with credit, and
+ * a cancel. A port sends objects, not text, so a frame needs no JSON. A side serves the calls of
+ * the other side with its `serve` handler, for example a `ProcedureServer`. Before, the site had
+ * two worker protocols of its own.
+ *
+ * @example
+ * ```typescript
+ * // In the worker: serve the procedures of a registry
+ * new PortTransport(self, { serve: new ProcedureServer({ registry, autoRegister: true }) });
+ *
+ * // On the page: call them
+ * const client = new Client(new PortTransport(new Worker(url, { type: "module" })));
+ * for await (const item of client.stream({ service: "site", operation: "run" }, input)) { ... }
+ * ```
+ */
+
+import type { Message, ResponseItem, Transport } from "../../client/types.js";
+import type { RequestHandler } from "../../server/types.js";
+import type { WebSocketMessage } from "../websocket/server/types.js";
+import { IncomingCalls, OutgoingCalls } from "../websocket/shared/rpc.js";
+import { withoutInternalKeys } from "../metadata.js";
+
+/**
+ * A message port: the object that a worker, a `MessagePort` or a `worker_threads` port gives. It
+ * has `postMessage`, and `addEventListener` (the browser form) or `on` (the Node form).
+ *
+ * The event of a listener has the type `any`: the DOM and Node give it different types, and a
+ * port of each must fit without a cast. The transport reads only its `data`.
+ */
+export interface PortLike {
+  postMessage(message: unknown): void;
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  addEventListener?(type: "message", listener: (event: any) => void): void;
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  removeEventListener?(type: "message", listener: (event: any) => void): void;
+  on?(type: "message", listener: (data: unknown) => void): unknown;
+  off?(type: "message", listener: (data: unknown) => void): unknown;
+  /** A `MessagePort` delivers its messages to `addEventListener` only after `start()`. */
+  start?(): void;
+}
+
+/** The options of a `PortTransport`. */
+export interface PortTransportOptions {
+  /** The handler of the calls of the other side, for example a `ProcedureServer`. */
+  serve?: RequestHandler | undefined;
+  /** The number of stream items that the reader holds. The default is 64. */
+  streamWindow?: number | undefined;
+}
+
+/** A frame of the protocol: an object with an id and a type. */
+function isFrame(value: unknown): value is WebSocketMessage {
+  return value !== null && typeof value === "object" && typeof (value as { type?: unknown }).type === "string";
+}
+
+/** The transport over a message port, in the two directions. */
+export class PortTransport implements Transport {
+  readonly name = "port";
+  private readonly outgoing: OutgoingCalls;
+  private readonly incoming: IncomingCalls | undefined;
+  private open = true;
+  private readonly onBrowserMessage = (event: { data: unknown }): void => this.receive(event.data);
+  private readonly onNodeMessage = (data: unknown): void => this.receive(data);
+
+  constructor(
+    private readonly port: PortLike,
+    options: PortTransportOptions = {},
+  ) {
+    const send = (frame: WebSocketMessage): void => this.port.postMessage(frame);
+    const isOpen = (): boolean => this.open;
+    this.outgoing = new OutgoingCalls({
+      send,
+      isOpen,
+      // No time limit: a worker can run a long program. The `signal` of a call stops it. This file
+      // does not import the Durations (quantity, 6 kB of gzip), so the page of a worker stays small.
+      requestTimeoutMs: 0,
+      streamWindow: Math.max(2, options.streamWindow ?? 64),
+      idPrefix: "",
+    });
+    if (options.serve) {
+      this.incoming = new IncomingCalls({
+        handler: options.serve,
+        send,
+        isOpen,
+        // A call over a port comes from a part of this application: it has no credentials
+        requestOf: (frame, signal) => ({
+          id: frame.id,
+          method: frame.method!,
+          payload: frame.payload === undefined ? {} : frame.payload,
+          metadata: withoutInternalKeys(frame.metadata),
+          signal,
+        }),
+      });
+    }
+    if (port.addEventListener) port.addEventListener("message", this.onBrowserMessage);
+    else port.on?.("message", this.onNodeMessage);
+    port.start?.();
+  }
+
+  private receive(data: unknown): void {
+    if (!this.open || !isFrame(data)) return;
+    if (this.outgoing.receive(data)) return;
+    this.incoming?.receive(data);
+  }
+
+  /** This function sends a call to the other side, and gives its response items. */
+  send<TReq, TRes>(message: Message<TReq>): AsyncIterable<ResponseItem<TRes>> {
+    return this.outgoing.call<TReq, TRes>(message);
+  }
+
+  /** This function stops the calls in the two directions, and stops to listen. It does not close the port. */
+  async close(): Promise<void> {
+    if (!this.open) return;
+    this.open = false;
+    this.outgoing.failAll("The port transport closed");
+    this.incoming?.abortAll();
+    if (this.port.removeEventListener) this.port.removeEventListener("message", this.onBrowserMessage);
+    else this.port.off?.("message", this.onNodeMessage);
+  }
+}

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

@@ -7,6 +7,7 @@
 // Types
 export type {
   WebSocketTransportOptions,
+  WebSocketClass,
   WebSocketMessage,
   ServerRequestMessage,
   ServerRequestHandler,

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

@@ -0,0 +1,34 @@
+/**
+ * The WebSocket client transport for Node (finding of roadmap R36).
+ *
+ * This class is the `WebSocketTransport` of the browser entry with one other default: its sockets
+ * are of the `WebSocket` class of the `ws` package. A drop by the heartbeat or by the time limit
+ * of the handshake then ends the socket at once with `terminate()`. The global `WebSocket` of Node
+ * has only `close()`, which waits for the answer of the peer. With a dead peer, that socket stays
+ * open until the kernel stops it: 924.6 seconds in the harness cells of R36.
+ *
+ * Only the Node entry `@procedures/client/node` exports this class. The browser entry does not
+ * import `ws`.
+ */
+
+import { WebSocket as NodeWebSocket } from "ws";
+import { WebSocketTransport as PortableWebSocketTransport } from "./transport.js";
+import type { WebSocketTransportOptions } from "./types.js";
+
+/**
+ * The WebSocket client transport with the `WebSocket` class of the `ws` package as the default
+ * class of its sockets. The option `webSocket` gives another class.
+ *
+ * @example
+ * ```typescript
+ * import { Client } from "@procedures/client";
+ * import { WebSocketTransport } from "@procedures/client/node";
+ *
+ * const client = new Client({ transport: new WebSocketTransport({ url: "ws://localhost:3000/ws" }) });
+ * ```
+ */
+export class WebSocketTransport extends PortableWebSocketTransport {
+  constructor(options: WebSocketTransportOptions) {
+    super({ ...options, webSocket: options.webSocket ?? NodeWebSocket });
+  }
+}