@procedures/client 0.2.3 → 0.4.0

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

@@ -6,9 +6,20 @@
  */
 
 import type { Transport, Message, ResponseItem } from "../../../client/types.js";
-import type { WebSocketTransportOptions, WebSocketMessage, ServerRequestHandler, EventHandler } from "./types.js";
+import type { WebSocketTransportOptions, WebSocketMessage, ServerRequestHandler, EventHandler, WebSocketClass } from "./types.js";
 import { WebSocketState } from "./types.js";
 import { withoutInternalKeys } from "../../metadata.js";
+import { IncomingCalls } from "../shared/rpc.js";
+import type { RequestHandler, ServerResponse } from "../../../server/types.js";
+import { methodToPath } from "../../../server/method.js";
+import { optionalMs } from "../../../duration.js";
+import { PROTOCOL_VERSION, protocolVersionOf } from "../../../protocol.js";
+import { TIMER_DEFAULTS } from "../../../timers.js";
+import { realClock, type Cancel, type Clock } from "../../../clock.js";
+import { heartbeat, type Heartbeat } from "@mark1russell7/service/heartbeat";
+import { backoffDelay } from "@mark1russell7/service/backoff";
+import type { MachineTransition } from "../../../machines.js";
+import { WEBSOCKET_CONNECTION_MACHINE } from "../../../machines.js";
 
 /**
  * Pending request waiting for response.
@@ -64,7 +75,7 @@ interface PendingRequest {
   /** The response items of the request, in order */
   queue: ItemQueue<ResponseItem<unknown>>;
   /** The request timeout: it runs until the first frame arrives */
-  timeout?: ReturnType<typeof setTimeout> | undefined;
+  timeout?: Cancel | undefined;
 }
 
 /**
@@ -85,6 +96,23 @@ interface PendingRequest {
  * const client = new Client({ transport });
  * ```
  */
+/** The `readyState` of an open socket. The global `WebSocket` and the `ws` package use the same number. */
+const OPEN = 1;
+
+/**
+ * The error handler of a socket that the transport left. A `WebSocket` of the `ws` package that
+ * closes during its handshake emits an error. Without a handler, that error ends the process.
+ */
+const ignoreError = (): void => undefined;
+
+/** This function removes the handlers of the transport from a socket, and keeps `ignoreError`. */
+function detach(ws: WebSocket): void {
+  ws.onopen = null;
+  ws.onmessage = null;
+  ws.onclose = null;
+  ws.onerror = ignoreError;
+}
+
 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: {} };
 }
@@ -93,6 +121,59 @@ function abortedItem<TRes>(id: string): ResponseItem<TRes> {
   return errorItem<TRes>(id, "ABORTED", "Request was aborted", false);
 }
 
+/**
+ * The handler of the calls of the server without a `serve` option: the older `onServerRequest`
+ * function (it gets the path and the input), or else a `NOT_FOUND` answer.
+ */
+function legacyHandler(onServerRequest: ServerRequestHandler | undefined): RequestHandler {
+  return {
+    async handle(request): Promise<ServerResponse> {
+      if (!onServerRequest) {
+        return {
+          id: request.id,
+          status: { type: "error", code: "NOT_FOUND", message: "This client serves no procedures", retryable: false },
+          metadata: {},
+        };
+      }
+      try {
+        const payload = await onServerRequest(methodToPath(request.method), request.payload);
+        return { id: request.id, status: { type: "success", code: 200 }, payload, metadata: {} };
+      } catch (error) {
+        return {
+          id: request.id,
+          status: { type: "error", code: "HANDLER_ERROR", message: error instanceof Error ? error.message : String(error), retryable: false },
+          metadata: {},
+        };
+      }
+    },
+  };
+}
+
+/**
+ * The delay before a reconnect try (from 1): an exponential backoff up to `maxDelay`, with a
+ * random part. With `jitter: 1` (full jitter, the default), the delay is a random time from 0 to
+ * the backoff, so the clients of a server that restarted do not come back at the same moments
+ * (roadmap R3). The backoff is `backoffDelay` of `@mark1russell7/service/backoff` (roadmap R37).
+ */
+export function reconnectDelay(
+  attempt: number,
+  options: { initialDelay: number; backoffMultiplier: number; maxDelay: number; jitter: number },
+  random: () => number = Math.random,
+): number {
+  return Math.round(
+    backoffDelay(
+      {
+        base: options.initialDelay,
+        factor: options.backoffMultiplier,
+        cap: options.maxDelay,
+        jitter: { kind: "subtract", fraction: options.jitter },
+      },
+      attempt,
+      random,
+    ),
+  );
+}
+
 export class WebSocketTransport implements Transport {
   readonly name = "websocket";
 
@@ -106,6 +187,7 @@ export class WebSocketTransport implements Transport {
       initialDelay: number;
       maxDelay: number;
       backoffMultiplier: number;
+      jitter: number;
     };
     connectionTimeout: number;
     requestTimeout: number;
@@ -114,12 +196,14 @@ export class WebSocketTransport implements Transport {
       enabled: boolean;
       interval: number;
       timeout: number;
+      misses: number;
     };
     onConnect: (() => void) | undefined;
     onDisconnect: ((reason?: string) => void) | undefined;
     onReconnecting: ((attempt: number) => void) | undefined;
     onError: ((error: Error) => void) | undefined;
     onServerRequest: ServerRequestHandler | undefined;
+    serve: RequestHandler | undefined;
     onEvent: EventHandler | undefined;
   };
   /** The requests in progress, by wire id */
@@ -135,9 +219,21 @@ export class WebSocketTransport implements Transport {
   /** Set by close(): the connection is being closed on purpose, so it must not reconnect */
   private closing = false;
   private reconnectAttempts = 0;
-  private reconnectTimer: ReturnType<typeof setTimeout> | undefined = undefined;
-  private heartbeatTimer: ReturnType<typeof setTimeout> | undefined = undefined;
-  private heartbeatTimeout: ReturnType<typeof setTimeout> | undefined = undefined;
+  private reconnectTimer: Cancel | undefined = undefined;
+  /** The heartbeat of the connection: `heartbeat` of `@mark1russell7/service/heartbeat` (roadmap R37) */
+  private heartbeat: Heartbeat | undefined = undefined;
+  /** The clock of each timer of the transport (roadmap R35) */
+  private readonly clock: Clock;
+  /** The class of the sockets, or undefined for the global `WebSocket` (finding of roadmap R36) */
+  private readonly webSocketClass: WebSocketClass | undefined;
+  /** The observer of the changes of the state (roadmap R35) */
+  private readonly transitionHandler: ((transition: MachineTransition) => void) | undefined;
+  /** The protocol version of the server, from its hello, or undefined (an older server) (R25) */
+  private serverProtocol: number | undefined;
+  /** The calls that the server sends on the current socket, served by `serve` (roadmap R24) */
+  private incoming: IncomingCalls | undefined;
+  /** The time limit of the handshake of the socket that opens now */
+  private handshakeTimer: Cancel | undefined = undefined;
 
   constructor(options: WebSocketTransportOptions) {
     this.options = {
@@ -145,40 +241,54 @@ export class WebSocketTransport implements Transport {
       reconnect: {
         enabled: options.reconnect?.enabled ?? true,
         maxAttempts: options.reconnect?.maxAttempts ?? Infinity,
-        initialDelay: options.reconnect?.initialDelay ?? 1000,
-        maxDelay: options.reconnect?.maxDelay ?? 30000,
+        initialDelay: optionalMs(options.reconnect?.initialDelay, "reconnect.initialDelay") ?? TIMER_DEFAULTS.webSocketClient.reconnectInitialDelayMs,
+        maxDelay: optionalMs(options.reconnect?.maxDelay, "reconnect.maxDelay") ?? TIMER_DEFAULTS.webSocketClient.reconnectMaxDelayMs,
         backoffMultiplier: options.reconnect?.backoffMultiplier ?? 1.5,
+        jitter: Math.min(1, Math.max(0, options.reconnect?.jitter ?? 1)),
       },
-      connectionTimeout: options.connectionTimeout ?? 10000,
-      requestTimeout: options.requestTimeout ?? 30000,
+      connectionTimeout: optionalMs(options.connectionTimeout, "connectionTimeout") ?? TIMER_DEFAULTS.webSocketClient.connectionTimeoutMs,
+      requestTimeout: optionalMs(options.requestTimeout, "requestTimeout") ?? TIMER_DEFAULTS.webSocketClient.requestTimeoutMs,
       streamWindow: Math.max(2, options.streamWindow ?? 64),
       heartbeat: {
         enabled: options.heartbeat?.enabled ?? true,
-        interval: options.heartbeat?.interval ?? 30000,
-        timeout: options.heartbeat?.timeout ?? 5000,
+        interval: optionalMs(options.heartbeat?.interval, "heartbeat.interval") ?? TIMER_DEFAULTS.webSocketClient.heartbeatIntervalMs,
+        timeout: optionalMs(options.heartbeat?.timeout, "heartbeat.timeout") ?? TIMER_DEFAULTS.webSocketClient.heartbeatTimeoutMs,
+        misses: Math.max(1, options.heartbeat?.misses ?? TIMER_DEFAULTS.webSocketClient.heartbeatMisses),
       },
       onConnect: options.onConnect,
       onDisconnect: options.onDisconnect,
       onReconnecting: options.onReconnecting,
       onError: options.onError,
       onServerRequest: options.onServerRequest,
+      serve: options.serve,
       onEvent: options.onEvent,
     };
+    this.clock = options.clock ?? realClock;
+    this.webSocketClass = options.webSocket;
+    this.transitionHandler = options.onTransition;
 
     // Auto-connect
     this.connect();
   }
 
-  /** Change the state, and tell the callers that wait for a connection. */
-  private setState(state: WebSocketState): void {
+  /**
+   * Change the state, and tell the callers that wait for a connection. `on` is the event of
+   * `WEBSOCKET_CONNECTION_MACHINE`: a change goes to `onTransition` (roadmap R35).
+   */
+  private setState(state: WebSocketState, on: string): void {
+    const from = this.state;
     this.state = state;
+    if (from !== state) {
+      this.transitionHandler?.({ machine: WEBSOCKET_CONNECTION_MACHINE.id, instance: this.name, from, on, to: state, at: this.clock.now() });
+    }
     for (const listener of [...this.stateListeners]) listener();
   }
 
   /**
    * Connect to WebSocket server.
    */
-  private connect(): void {
+  /** `on` is the event of the machine: the first connect, or the end of a backoff. */
+  private connect(on: "connect" | "reconnect-due" = "connect"): void {
     if (this.closing) {
       return;
     }
@@ -186,17 +296,36 @@ export class WebSocketTransport implements Transport {
       return;
     }
 
-    this.setState(WebSocketState.CONNECTING);
+    this.setState(WebSocketState.CONNECTING, on);
 
     try {
-      const ws = new WebSocket(this.options.url);
+      const WebSocketClass = (this.webSocketClass ?? WebSocket) as typeof WebSocket;
+      const ws = new WebSocketClass(this.options.url);
       this.ws = ws;
+      // The calls of the server on this socket (roadmap R24)
+      this.incoming = this.servedCallsOf(ws);
+
+      // The handshake has a time limit: an address that never answers does not keep the socket
+      // in CONNECTING (roadmap R3)
+      this.clearHandshakeTimer();
+      this.handshakeTimer = this.clock.after(this.options.connectionTimeout, () => {
+        this.handshakeTimer = undefined;
+        if (this.ws === ws && this.state === WebSocketState.CONNECTING) {
+          console.error(`[${this.name}] Handshake timeout after ${this.options.connectionTimeout}ms`);
+          this.dropConnection("Handshake timeout");
+        }
+      });
 
       // Connection opened
       ws.onopen = () => {
         if (this.ws !== ws) return;
+        this.clearHandshakeTimer();
         this.reconnectAttempts = 0;
-        this.setState(WebSocketState.CONNECTED);
+        // The protocol version of this client (roadmap R25). An older server answers with an
+        // error frame, which the client ignores.
+        this.serverProtocol = undefined;
+        ws.send(JSON.stringify({ id: "hello", type: "hello", protocol: PROTOCOL_VERSION }));
+        this.setState(WebSocketState.CONNECTED, "open");
         console.error(`[${this.name}] Connected to ${this.options.url}`);
 
         if (this.options.onConnect) {
@@ -235,6 +364,10 @@ export class WebSocketTransport implements Transport {
         if (this.options.onError) {
           this.options.onError(error);
         }
+        // A failed handshake: the WebSocket of Node 22 gives no close event after this error, and
+        // stays in CONNECTING. The transport closes it now, so the reconnect starts at once
+        // (roadmap R30: before, each try waited for the time limit of the handshake).
+        if (this.state === WebSocketState.CONNECTING) this.dropConnection("Connection failed");
       };
     } catch (error) {
       console.error(`[${this.name}] Failed to create WebSocket:`, error);
@@ -252,12 +385,13 @@ export class WebSocketTransport implements Transport {
     const ws = this.ws;
     this.ws = null;
     if (ws) {
-      ws.onopen = null;
-      ws.onmessage = null;
-      ws.onclose = null;
-      ws.onerror = null;
+      detach(ws);
       try {
-        ws.close();
+        // A socket of the ws package ends at once. close() waits for the answer of a peer that can
+        // be dead (finding of roadmap R36).
+        const terminate = (ws as { terminate?: () => void }).terminate;
+        if (typeof terminate === "function") terminate.call(ws);
+        else ws.close();
       } catch {
         // The socket is unusable: nothing more to do
       }
@@ -269,9 +403,7 @@ export class WebSocketTransport implements Transport {
   private failPending(reason: string): void {
     for (const pending of this.pendingRequests.values()) {
       pending.queue.fail(new Error(reason));
-      if (pending.timeout) {
-        clearTimeout(pending.timeout);
-      }
+      pending.timeout?.();
     }
     this.pendingRequests.clear();
   }
@@ -281,11 +413,14 @@ export class WebSocketTransport implements Transport {
    */
   private handleClose(reason?: string): void {
     this.stopHeartbeat();
+    this.incoming?.abortAll();
+    this.incoming = undefined;
+    this.clearHandshakeTimer();
 
     // An intentional close() must not reconnect (BUGS-2026-07 H6)
     const reconnect = this.options.reconnect;
     const willReconnect = !this.closing && reconnect.enabled && this.reconnectAttempts < reconnect.maxAttempts;
-    this.setState(willReconnect ? WebSocketState.RECONNECTING : WebSocketState.DISCONNECTED);
+    this.setState(willReconnect ? WebSocketState.RECONNECTING : WebSocketState.DISCONNECTED, willReconnect ? "drop" : "give-up");
 
     console.error(`[${this.name}] Disconnected${reason ? `: ${reason}` : ""}`);
 
@@ -305,17 +440,13 @@ export class WebSocketTransport implements Transport {
    */
   private scheduleReconnect(): void {
     if (this.reconnectTimer) {
-      clearTimeout(this.reconnectTimer);
+      this.reconnectTimer();
     }
 
     this.reconnectAttempts++;
-    this.setState(WebSocketState.RECONNECTING);
+    this.setState(WebSocketState.RECONNECTING, "drop");
 
-    const reconnect = this.options.reconnect;
-    const delay = Math.min(
-      reconnect.initialDelay * Math.pow(reconnect.backoffMultiplier, this.reconnectAttempts - 1),
-      reconnect.maxDelay
-    );
+    const delay = reconnectDelay(this.reconnectAttempts, this.options.reconnect);
 
     console.error(`[${this.name}] Reconnecting in ${delay}ms (attempt ${this.reconnectAttempts})`);
 
@@ -323,64 +454,95 @@ export class WebSocketTransport implements Transport {
       this.options.onReconnecting(this.reconnectAttempts);
     }
 
-    this.reconnectTimer = setTimeout(() => {
+    this.reconnectTimer = this.clock.after(delay, () => {
       this.reconnectTimer = undefined;
       // connect() returns at once in RECONNECTING only for CONNECTING/CONNECTED
-      this.connect();
-    }, delay);
+      this.connect("reconnect-due");
+    });
   }
 
   /**
-   * Start heartbeat to keep connection alive.
+   * Start the heartbeat of the connection: a ping each interval on the clock, one ping at a time.
+   * A ping without a pong at its timeout is a miss. The connection drops after `misses` misses in
+   * sequence. A ping whose send throws is a miss too.
    */
   private startHeartbeat(): void {
     this.stopHeartbeat();
-
-    this.heartbeatTimer = setInterval(() => {
-      // One ping at a time: a new ping must not replace the timeout of an unanswered one
-      if (this.state === WebSocketState.CONNECTED && this.ws && !this.heartbeatTimeout) {
-        // Send ping
+    this.heartbeat = heartbeat({
+      interval: this.options.heartbeat.interval,
+      timeout: this.options.heartbeat.timeout,
+      misses: this.options.heartbeat.misses,
+      clock: this.clock,
+      due: () => this.state === WebSocketState.CONNECTED && this.ws !== null,
+      ping: () => {
         const ping: WebSocketMessage = {
           id: `ping-${Date.now()}`,
           type: "ping",
         };
-        this.ws.send(JSON.stringify(ping));
-
-        // Set timeout for pong
-        this.heartbeatTimeout = setTimeout(() => {
-          this.heartbeatTimeout = undefined;
-          console.warn(`[${this.name}] Heartbeat timeout - dropping connection`);
-          this.dropConnection("Heartbeat timeout");
-        }, this.options.heartbeat.timeout);
-      }
-    }, this.options.heartbeat.interval);
+        this.ws?.send(JSON.stringify(ping));
+      },
+      onDead: () => {
+        console.warn(`[${this.name}] Heartbeat timeout - dropping connection`);
+        this.dropConnection("Heartbeat timeout");
+      },
+    });
   }
 
-  /**
-   * Stop heartbeat.
-   */
-  private stopHeartbeat(): void {
-    if (this.heartbeatTimer) {
-      clearInterval(this.heartbeatTimer);
-      this.heartbeatTimer = undefined;
-    }
-    if (this.heartbeatTimeout) {
-      clearTimeout(this.heartbeatTimeout);
-      this.heartbeatTimeout = undefined;
+  /** Stop the time limit of the handshake. */
+  private clearHandshakeTimer(): void {
+    if (this.handshakeTimer) {
+      this.handshakeTimer();
+      this.handshakeTimer = undefined;
     }
   }
 
+  /** Stop the heartbeat: its ticks, its timeout and its count of misses. */
+  private stopHeartbeat(): void {
+    this.heartbeat?.stop();
+    this.heartbeat = undefined;
+  }
+
   /**
    * Handle incoming message.
    */
+  /**
+   * The calls of the server on a socket, served by the `serve` option (or by `onServerRequest`, or
+   * with `NOT_FOUND`), with the same frames as the calls of the client (roadmap R24).
+   */
+  private servedCallsOf(ws: WebSocket): IncomingCalls {
+    const handler = this.options.serve ?? legacyHandler(this.options.onServerRequest);
+    return new IncomingCalls({
+      handler,
+      send: (frame) => ws.send(JSON.stringify(frame)),
+      isOpen: () => this.ws === ws && ws.readyState === OPEN,
+      // A call of the server that this client opened: the client trusts it, so it has no
+      // credentials (a ProcedureServer applies no token to it)
+      requestOf: (frame, signal) => ({
+        id: frame.id,
+        method: frame.method!,
+        payload: frame.payload === undefined ? {} : frame.payload,
+        metadata: withoutInternalKeys(frame.metadata),
+        signal,
+      }),
+    });
+  }
+
   private handleMessage(message: WebSocketMessage): void {
+    // The hello of the server, or the error of an older server that does not know it (R25)
+    if (message.id === "hello" && (message.type === "hello" || message.type === "error")) {
+      if (message.type === "hello") this.serverProtocol = protocolVersionOf(message.protocol);
+      else if (message.error?.code === "PROTOCOL_VERSION") this.options.onError?.(new Error(message.error.message));
+      return;
+    }
+    // A call of the server, its cancel or its credit (roadmap R24)
+    if ((message.type === "request" || message.type === "cancel" || message.type === "credit") && this.incoming?.receive(message)) {
+      return;
+    }
+
 
     // Handle pong (heartbeat response)
     if (message.type === "pong") {
-      if (this.heartbeatTimeout) {
-        clearTimeout(this.heartbeatTimeout);
-        this.heartbeatTimeout = undefined;
-      }
+      this.heartbeat?.answer();
       return;
     }
 
@@ -421,7 +583,7 @@ export class WebSocketTransport implements Transport {
 
     // The first frame arrived: the request timeout ends. A stream can stay open longer.
     if (pending.timeout) {
-      clearTimeout(pending.timeout);
+      pending.timeout();
       pending.timeout = undefined;
     }
 
@@ -539,7 +701,7 @@ export class WebSocketTransport implements Transport {
 
     const queue = new ItemQueue<ResponseItem<unknown>>();
     const pending: PendingRequest = { messageId: message.id, queue };
-    pending.timeout = setTimeout(() => {
+    pending.timeout = this.clock.after(this.options.requestTimeout, () => {
       if (this.pendingRequests.get(wireId) !== pending) return;
       this.pendingRequests.delete(wireId);
       this.sendCancel(wireId);
@@ -548,13 +710,13 @@ export class WebSocketTransport implements Transport {
       // so a retry middleware must not repeat it (deep dive TRN-8)
       queue.push(errorItem(message.id, "TIMEOUT", `Request timeout after ${this.options.requestTimeout}ms`, false));
       queue.end();
-    }, this.options.requestTimeout);
+    });
     this.pendingRequests.set(wireId, pending);
 
     const onAbort = (): void => {
       if (this.pendingRequests.get(wireId) !== pending) return;
       this.pendingRequests.delete(wireId);
-      if (pending.timeout) clearTimeout(pending.timeout);
+      pending.timeout?.();
       this.sendCancel(wireId);
       queue.push(abortedItem(message.id));
       queue.end();
@@ -579,7 +741,7 @@ export class WebSocketTransport implements Transport {
       }
     } finally {
       message.signal?.removeEventListener("abort", onAbort);
-      if (pending.timeout) clearTimeout(pending.timeout);
+      pending.timeout?.();
       if (this.pendingRequests.get(wireId) === pending) {
         // The reader stopped before the end: the server stops the stream
         this.pendingRequests.delete(wireId);
@@ -619,7 +781,7 @@ export class WebSocketTransport implements Transport {
 
     return new Promise((resolve, reject) => {
       const finish = (error?: Error): void => {
-        clearTimeout(timeout);
+        timeout();
         this.stateListeners.delete(check);
         signal?.removeEventListener("abort", onAbort);
         if (error) reject(error);
@@ -631,7 +793,7 @@ export class WebSocketTransport implements Transport {
       };
       // The caller aborted: send() then gives the ABORTED item
       const onAbort = (): void => finish();
-      const timeout = setTimeout(() => finish(new Error("Connection timeout")), this.options.connectionTimeout);
+      const timeout = this.clock.after(this.options.connectionTimeout, () => finish(new Error("Connection timeout")));
       this.stateListeners.add(check);
       signal?.addEventListener("abort", onAbort, { once: true });
     });
@@ -691,11 +853,14 @@ export class WebSocketTransport implements Transport {
    */
   async close(): Promise<void> {
     this.closing = true;
-    this.setState(WebSocketState.DISCONNECTING);
+    this.setState(WebSocketState.DISCONNECTING, "close");
     this.stopHeartbeat();
+    this.clearHandshakeTimer();
+    this.incoming?.abortAll();
+    this.incoming = undefined;
 
     if (this.reconnectTimer) {
-      clearTimeout(this.reconnectTimer);
+      this.reconnectTimer();
       this.reconnectTimer = undefined;
     }
 
@@ -703,20 +868,25 @@ export class WebSocketTransport implements Transport {
     if (this.ws) {
       const ws = this.ws;
       this.ws = null;
-      ws.onopen = null;
-      ws.onmessage = null;
-      ws.onclose = null;
-      ws.onerror = null;
+      detach(ws);
       ws.close();
     }
 
     this.failPending("WebSocket connection closed");
-    this.setState(WebSocketState.DISCONNECTED);
+    this.setState(WebSocketState.DISCONNECTED, "closed");
     if (hadSocket && this.options.onDisconnect) {
       this.options.onDisconnect("closed");
     }
   }
 
+  /**
+   * The protocol version of the server: from its hello, or undefined before the hello or for a
+   * server older than protocol v1 (roadmap R25).
+   */
+  getServerProtocol(): number | undefined {
+    return this.serverProtocol;
+  }
+
   /**
    * Get current connection state.
    */