@procedures/client 0.2.3 → 0.4.0

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

@@ -4,8 +4,14 @@
  * Type definitions for WebSocket client adapter.
  */
 
+import type { Duration } from "../../../duration.js";
+import type { Clock } from "../../../clock.js";
+import type { MachineTransition } from "../../../machines.js";
+
+import type { RequestHandler } from "../../../server/types.js";
+
 /**
- * WebSocket client transport options.
+ * WebSocket client transport options. Each time is a `Duration` (roadmap R11).
  */
 export interface WebSocketTransportOptions {
   /**
@@ -31,36 +37,46 @@ export interface WebSocketTransportOptions {
     maxAttempts?: number;
 
     /**
-     * Initial delay before reconnecting (ms).
-     * @default 1000
+     * Initial delay before reconnecting.
+     * @default 1 second
      */
-    initialDelay?: number;
+    initialDelay?: Duration;
 
     /**
-     * Maximum delay between reconnection attempts (ms).
-     * @default 30000
+     * Maximum delay between reconnection attempts.
+     * @default 30 seconds
      */
-    maxDelay?: number;
+    maxDelay?: Duration;
 
     /**
      * Backoff multiplier for reconnection delay.
      * @default 1.5
      */
     backoffMultiplier?: number;
+
+    /**
+     * The random part of each reconnect delay, from 0 to 1. With 1 (full jitter), the delay is a
+     * random time from 0 to the backoff delay, so many clients that lost one server do not
+     * reconnect at the same time (roadmap R3). 0 gives the backoff delay exactly.
+     * @default 1
+     */
+    jitter?: number;
   };
 
   /**
-   * Connection timeout (ms): how long to wait for the WebSocket to open.
-   * @default 10000
+   * Connection timeout: how long to wait for the WebSocket to open. A handshake that takes
+   * longer closes the socket, and the transport reconnects (roadmap R3: before, an address that
+   * never answered kept the socket in CONNECTING).
+   * @default 10 seconds
    */
-  connectionTimeout?: number;
+  connectionTimeout?: Duration;
 
   /**
-   * Request timeout (ms): how long to wait for the response to one request.
+   * Request timeout: how long to wait for the response to one request.
    * (Before, requests used connectionTimeout, so every call was capped at 10s.)
-   * @default 30000
+   * @default 30 seconds
    */
-  requestTimeout?: number;
+  requestTimeout?: Duration;
 
   /**
    * The number of stream items that the transport holds for a reader that has not taken them.
@@ -80,16 +96,23 @@ export interface WebSocketTransportOptions {
     enabled?: boolean;
 
     /**
-     * Heartbeat interval (ms).
-     * @default 30000
+     * Heartbeat interval.
+     * @default 20 seconds (`TIMER_DEFAULTS.webSocketClient.heartbeatIntervalMs`)
      */
-    interval?: number;
+    interval?: Duration;
 
     /**
-     * Heartbeat timeout (ms).
-     * @default 5000
+     * Heartbeat timeout.
+     * @default 5 seconds
      */
-    timeout?: number;
+    timeout?: Duration;
+
+    /**
+     * The number of pings without a pong, one after the other, that drop the connection. The
+     * time to find a dead server is at most `misses × interval + timeout`.
+     * @default 1
+     */
+    misses?: number;
   };
 
   /**
@@ -114,17 +137,51 @@ export interface WebSocketTransportOptions {
 
   /**
    * Handler for server-initiated procedure calls.
-   * Called when the server wants to call a procedure on this client.
+   * Called when the server wants to call a procedure on this client. It gets the path and the
+   * input, and gives the value. `serve` is the full form (roadmap R24).
    */
   onServerRequest?: ServerRequestHandler;
 
+  /**
+   * The handler of the calls that the server sends to this client (roadmap R24), for example a
+   * `ProcedureServer` with the registry of the client. A call gets the same frames as a call of
+   * the client: streaming, credit, cancel, the signal and the deadline (`procedure-timeout`). The
+   * server reaches it with `callConnection()` or `transportFor()`. Without it (and without
+   * `onServerRequest`), the client answers each call of the server with `NOT_FOUND`.
+   */
+  serve?: RequestHandler;
+
   /**
    * Handler for subscription events.
    * Called when the server pushes an event to a subscribed topic.
    */
   onEvent?: EventHandler;
+
+  /**
+   * The clock of each timer of the transport: the handshake, the requests, the heartbeat and the
+   * reconnect (roadmap R35). The default is the clock of the platform. A test gives a fake clock.
+   */
+  clock?: Clock;
+
+  /**
+   * This function gets each change of the state, with its event, as a transition of
+   * `WEBSOCKET_CONNECTION_MACHINE` (roadmap R35). A test replays them against the document.
+   */
+  onTransition?: (transition: MachineTransition) => void;
+
+  /**
+   * The class of the sockets. The default is the global `WebSocket`. The `WebSocketTransport` of
+   * the Node entry `@procedures/client/node` has the `WebSocket` of the `ws` package as its
+   * default. With that class, a drop ends its socket at once with `terminate()`. The global
+   * `WebSocket` has only `close()`, which waits for the answer of the peer. With a dead peer, the
+   * socket stays open until the kernel stops it, at most 15 minutes (the harness cells of R36).
+   */
+  webSocket?: WebSocketClass;
 }
 
+/** A class of WebSockets: the global `WebSocket`, or the `WebSocket` of the `ws` package. */
+export type WebSocketClass = new (url: string) => unknown;
+
 /**
  * WebSocket connection state.
  */
@@ -144,7 +201,10 @@ export interface WebSocketMessage<T = unknown> {
   id: string;
 
   /** Message type */
-  type: "request" | "response" | "error" | "stream" | "cancel" | "credit" | "ping" | "pong" | "server-request" | "server-response" | "event";
+  type: "hello" | "request" | "response" | "error" | "stream" | "cancel" | "credit" | "ping" | "pong" | "server-request" | "server-response" | "event";
+
+  /** The protocol version of a `hello` frame (roadmap R25). */
+  protocol?: number;
 
   /** RPC method (for requests) */
   method?: {