@procedures/client 0.2.3 → 0.4.0

package/dist/adapters/websocket/client/transport.d.ts

@@ -7,6 +7,18 @@
 import type { Transport, Message, ResponseItem } from "../../../client/types.js";
 import type { WebSocketTransportOptions } from "./types.js";
 import { WebSocketState } from "./types.js";
+/**
+ * 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 declare function reconnectDelay(attempt: number, options: {
+    initialDelay: number;
+    backoffMultiplier: number;
+    maxDelay: number;
+    jitter: number;
+}, random?: () => number): number;
 export declare class WebSocketTransport implements Transport {
     readonly name = "websocket";
     private ws;
@@ -26,14 +38,30 @@ export declare class WebSocketTransport implements Transport {
     private closing;
     private reconnectAttempts;
     private reconnectTimer;
-    private heartbeatTimer;
-    private heartbeatTimeout;
+    /** The heartbeat of the connection: `heartbeat` of `@mark1russell7/service/heartbeat` (roadmap R37) */
+    private heartbeat;
+    /** The clock of each timer of the transport (roadmap R35) */
+    private readonly clock;
+    /** The class of the sockets, or undefined for the global `WebSocket` (finding of roadmap R36) */
+    private readonly webSocketClass;
+    /** The observer of the changes of the state (roadmap R35) */
+    private readonly transitionHandler;
+    /** The protocol version of the server, from its hello, or undefined (an older server) (R25) */
+    private serverProtocol;
+    /** The calls that the server sends on the current socket, served by `serve` (roadmap R24) */
+    private incoming;
+    /** The time limit of the handshake of the socket that opens now */
+    private handshakeTimer;
     constructor(options: WebSocketTransportOptions);
-    /** Change the state, and tell the callers that wait for a connection. */
+    /**
+     * 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;
     /**
      * Connect to WebSocket server.
      */
+    /** `on` is the event of the machine: the first connect, or the end of a backoff. */
     private connect;
     /**
      * Leave the current socket without waiting for its close handshake, and handle the close
@@ -52,16 +80,23 @@ export declare class WebSocketTransport implements Transport {
      */
     private scheduleReconnect;
     /**
-     * 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;
-    /**
-     * Stop heartbeat.
-     */
+    /** Stop the time limit of the handshake. */
+    private clearHandshakeTimer;
+    /** Stop the heartbeat: its ticks, its timeout and its count of misses. */
     private stopHeartbeat;
     /**
      * 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;
     private handleMessage;
     /**
      * Send a request and yield its response items as they arrive: one item for a request/response
@@ -94,6 +129,11 @@ export declare class WebSocketTransport implements Transport {
      * Close WebSocket connection. The requests in progress fail.
      */
     close(): Promise<void>;
+    /**
+     * 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;
     /**
      * Get current connection state.
      */

package/dist/adapters/websocket/client/transport.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"transport.d.ts","sourceRoot":"","sources":["../../../../src/adapters/websocket/client/transport.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,OAAO,EAAE,YAAY,EAAE,MAAM,0BAA0B,CAAC;AACjF,OAAO,KAAK,EAAE,yBAAyB,EAAwD,MAAM,YAAY,CAAC;AAClH,OAAO,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAsF5C,qBAAa,kBAAmB,YAAW,SAAS;IAClD,QAAQ,CAAC,IAAI,eAAe;IAE5B,OAAO,CAAC,EAAE,CAA0B;IACpC,OAAO,CAAC,KAAK,CAA+C;IAC5D,OAAO,CAAC,OAAO,CAuBb;IACF,2CAA2C;IAC3C,OAAO,CAAC,eAAe,CAA0C;IACjE;;;;OAIG;IACH,OAAO,CAAC,OAAO,CAAK;IACpB,2FAA2F;IAC3F,OAAO,CAAC,cAAc,CAAyB;IAC/C,0FAA0F;IAC1F,OAAO,CAAC,OAAO,CAAS;IACxB,OAAO,CAAC,iBAAiB,CAAK;IAC9B,OAAO,CAAC,cAAc,CAAwD;IAC9E,OAAO,CAAC,cAAc,CAAwD;IAC9E,OAAO,CAAC,gBAAgB,CAAwD;IAEhF,YAAY,OAAO,EAAE,yBAAyB,EA4B7C;IAED,yEAAyE;IACzE,OAAO,CAAC,QAAQ;IAKhB;;OAEG;IACH,OAAO,CAAC,OAAO;IAiEf;;;;OAIG;IACH,OAAO,CAAC,cAAc;IAiBtB,yEAAyE;IACzE,OAAO,CAAC,WAAW;IAUnB;;OAEG;IACH,OAAO,CAAC,WAAW;IAqBnB;;OAEG;IACH,OAAO,CAAC,iBAAiB;IA2BzB;;OAEG;IACH,OAAO,CAAC,cAAc;IAuBtB;;OAEG;IACH,OAAO,CAAC,aAAa;IAWrB;;OAEG;IACH,OAAO,CAAC,aAAa;IA8HrB;;;;;;;;;;;OAWG;IACI,IAAI,CAAC,IAAI,EAAE,IAAI,EAAE,OAAO,EAAE,OAAO,CAAC,IAAI,CAAC,GAAG,aAAa,CAAC,YAAY,CAAC,IAAI,CAAC,CAAC,CA2EjF;IAED,qFAAqF;IACrF,OAAO,CAAC,UAAU;IAOlB,wEAAwE;IACxE,OAAO,CAAC,UAAU;IAOlB;;;;OAIG;YACW,iBAAiB;IA4B/B;;OAEG;YACW,mBAAmB;IA8CjC;;OAEG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CA0B3B;IAED;;OAEG;IACH,QAAQ,IAAI,cAAc,CAEzB;IAED;;OAEG;IACH,WAAW,IAAI,OAAO,CAErB;CACF"}
+{"version":3,"file":"transport.d.ts","sourceRoot":"","sources":["../../../../src/adapters/websocket/client/transport.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,OAAO,EAAE,YAAY,EAAE,MAAM,0BAA0B,CAAC;AACjF,OAAO,KAAK,EAAE,yBAAyB,EAAwE,MAAM,YAAY,CAAC;AAClI,OAAO,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AA8I5C;;;;;GAKG;AACH,wBAAgB,cAAc,CAC5B,OAAO,EAAE,MAAM,EACf,OAAO,EAAE;IAAE,YAAY,EAAE,MAAM,CAAC;IAAC,iBAAiB,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,EAC9F,MAAM,GAAE,MAAM,MAAoB,GACjC,MAAM,CAaR;AAED,qBAAa,kBAAmB,YAAW,SAAS;IAClD,QAAQ,CAAC,IAAI,eAAe;IAE5B,OAAO,CAAC,EAAE,CAA0B;IACpC,OAAO,CAAC,KAAK,CAA+C;IAC5D,OAAO,CAAC,OAAO,CA0Bb;IACF,2CAA2C;IAC3C,OAAO,CAAC,eAAe,CAA0C;IACjE;;;;OAIG;IACH,OAAO,CAAC,OAAO,CAAK;IACpB,2FAA2F;IAC3F,OAAO,CAAC,cAAc,CAAyB;IAC/C,0FAA0F;IAC1F,OAAO,CAAC,OAAO,CAAS;IACxB,OAAO,CAAC,iBAAiB,CAAK;IAC9B,OAAO,CAAC,cAAc,CAAiC;IACvD,uGAAuG;IACvG,OAAO,CAAC,SAAS,CAAoC;IACrD,6DAA6D;IAC7D,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAQ;IAC9B,iGAAiG;IACjG,OAAO,CAAC,QAAQ,CAAC,cAAc,CAA6B;IAC5D,6DAA6D;IAC7D,OAAO,CAAC,QAAQ,CAAC,iBAAiB,CAAwD;IAC1F,+FAA+F;IAC/F,OAAO,CAAC,cAAc,CAAqB;IAC3C,6FAA6F;IAC7F,OAAO,CAAC,QAAQ,CAA4B;IAC5C,mEAAmE;IACnE,OAAO,CAAC,cAAc,CAAiC;IAEvD,YAAY,OAAO,EAAE,yBAAyB,EAkC7C;IAED;;;OAGG;IACH,OAAO,CAAC,QAAQ;IAShB;;OAEG;IACH,oFAAoF;IACpF,OAAO,CAAC,OAAO;IAwFf;;;;OAIG;IACH,OAAO,CAAC,cAAc;IAkBtB,yEAAyE;IACzE,OAAO,CAAC,WAAW;IAQnB;;OAEG;IACH,OAAO,CAAC,WAAW;IAwBnB;;OAEG;IACH,OAAO,CAAC,iBAAiB;IAuBzB;;;;OAIG;IACH,OAAO,CAAC,cAAc;IAsBtB,4CAA4C;IAC5C,OAAO,CAAC,mBAAmB;IAO3B,0EAA0E;IAC1E,OAAO,CAAC,aAAa;IAKrB;;OAEG;IACH;;;OAGG;IACH,OAAO,CAAC,aAAa;IAkBrB,OAAO,CAAC,aAAa;IAsIrB;;;;;;;;;;;OAWG;IACI,IAAI,CAAC,IAAI,EAAE,IAAI,EAAE,OAAO,EAAE,OAAO,CAAC,IAAI,CAAC,GAAG,aAAa,CAAC,YAAY,CAAC,IAAI,CAAC,CAAC,CA2EjF;IAED,qFAAqF;IACrF,OAAO,CAAC,UAAU;IAOlB,wEAAwE;IACxE,OAAO,CAAC,UAAU;IAOlB;;;;OAIG;YACW,iBAAiB;IA4B/B;;OAEG;YACW,mBAAmB;IA8CjC;;OAEG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CA0B3B;IAED;;;OAGG;IACH,iBAAiB,IAAI,MAAM,GAAG,SAAS,CAEtC;IAED;;OAEG;IACH,QAAQ,IAAI,cAAc,CAEzB;IAED;;OAEG;IACH,WAAW,IAAI,OAAO,CAErB;CACF"}

package/dist/adapters/websocket/client/transport.js

@@ -6,6 +6,15 @@
  */
 import { WebSocketState } from "./types.js";
 import { withoutInternalKeys } from "../../metadata.js";
+import { IncomingCalls } from "../shared/rpc.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 } from "../../../clock.js";
+import { heartbeat } from "@mark1russell7/service/heartbeat";
+import { backoffDelay } from "@mark1russell7/service/backoff";
+import { WEBSOCKET_CONNECTION_MACHINE } from "../../../machines.js";
 /**
  * Pending request waiting for response.
  */
@@ -68,12 +77,68 @@ class ItemQueue {
  * 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 = () => undefined;
+/** This function removes the handlers of the transport from a socket, and keeps `ignoreError`. */
+function detach(ws) {
+    ws.onopen = null;
+    ws.onmessage = null;
+    ws.onclose = null;
+    ws.onerror = ignoreError;
+}
 function errorItem(id, code, message, retryable) {
     return { id, status: { type: "error", code, message, retryable }, payload: null, metadata: {} };
 }
 function abortedItem(id) {
     return errorItem(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) {
+    return {
+        async handle(request) {
+            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, options, random = Math.random) {
+    return Math.round(backoffDelay({
+        base: options.initialDelay,
+        factor: options.backoffMultiplier,
+        cap: options.maxDelay,
+        jitter: { kind: "subtract", fraction: options.jitter },
+    }, attempt, random));
+}
 export class WebSocketTransport {
     name = "websocket";
     ws = null;
@@ -93,62 +158,106 @@ export class WebSocketTransport {
     closing = false;
     reconnectAttempts = 0;
     reconnectTimer = undefined;
-    heartbeatTimer = undefined;
-    heartbeatTimeout = undefined;
+    /** The heartbeat of the connection: `heartbeat` of `@mark1russell7/service/heartbeat` (roadmap R37) */
+    heartbeat = undefined;
+    /** The clock of each timer of the transport (roadmap R35) */
+    clock;
+    /** The class of the sockets, or undefined for the global `WebSocket` (finding of roadmap R36) */
+    webSocketClass;
+    /** The observer of the changes of the state (roadmap R35) */
+    transitionHandler;
+    /** The protocol version of the server, from its hello, or undefined (an older server) (R25) */
+    serverProtocol;
+    /** The calls that the server sends on the current socket, served by `serve` (roadmap R24) */
+    incoming;
+    /** The time limit of the handshake of the socket that opens now */
+    handshakeTimer = undefined;
     constructor(options) {
         this.options = {
             url: options.url,
             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. */
-    setState(state) {
+    /**
+     * 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).
+     */
+    setState(state, on) {
+        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.
      */
-    connect() {
+    /** `on` is the event of the machine: the first connect, or the end of a backoff. */
+    connect(on = "connect") {
         if (this.closing) {
             return;
         }
         if (this.state === WebSocketState.CONNECTING || this.state === WebSocketState.CONNECTED) {
             return;
         }
-        this.setState(WebSocketState.CONNECTING);
+        this.setState(WebSocketState.CONNECTING, on);
         try {
-            const ws = new WebSocket(this.options.url);
+            const WebSocketClass = (this.webSocketClass ?? 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) {
                     this.options.onConnect();
@@ -186,6 +295,11 @@ export class WebSocketTransport {
                 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) {
@@ -203,12 +317,15 @@ export class WebSocketTransport {
         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.terminate;
+                if (typeof terminate === "function")
+                    terminate.call(ws);
+                else
+                    ws.close();
             }
             catch {
                 // The socket is unusable: nothing more to do
@@ -220,9 +337,7 @@ export class WebSocketTransport {
     failPending(reason) {
         for (const pending of this.pendingRequests.values()) {
             pending.queue.fail(new Error(reason));
-            if (pending.timeout) {
-                clearTimeout(pending.timeout);
-            }
+            pending.timeout?.();
         }
         this.pendingRequests.clear();
     }
@@ -231,10 +346,13 @@ export class WebSocketTransport {
      */
     handleClose(reason) {
         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}` : ""}`);
         if (this.options.onDisconnect) {
             this.options.onDisconnect(reason);
@@ -249,68 +367,99 @@ export class WebSocketTransport {
      */
     scheduleReconnect() {
         if (this.reconnectTimer) {
-            clearTimeout(this.reconnectTimer);
+            this.reconnectTimer();
         }
         this.reconnectAttempts++;
-        this.setState(WebSocketState.RECONNECTING);
-        const reconnect = this.options.reconnect;
-        const delay = Math.min(reconnect.initialDelay * Math.pow(reconnect.backoffMultiplier, this.reconnectAttempts - 1), reconnect.maxDelay);
+        this.setState(WebSocketState.RECONNECTING, "drop");
+        const delay = reconnectDelay(this.reconnectAttempts, this.options.reconnect);
         console.error(`[${this.name}] Reconnecting in ${delay}ms (attempt ${this.reconnectAttempts})`);
         if (this.options.onReconnecting) {
             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.
      */
     startHeartbeat() {
         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 = {
                     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.
-     */
-    stopHeartbeat() {
-        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. */
+    clearHandshakeTimer() {
+        if (this.handshakeTimer) {
+            this.handshakeTimer();
+            this.handshakeTimer = undefined;
         }
     }
+    /** Stop the heartbeat: its ticks, its timeout and its count of misses. */
+    stopHeartbeat() {
+        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).
+     */
+    servedCallsOf(ws) {
+        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,
+            }),
+        });
+    }
     handleMessage(message) {
+        // 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;
         }
         // Handle ping (server heartbeat)
@@ -347,7 +496,7 @@ export class WebSocketTransport {
         }
         // 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;
         }
         // A stream frame: one item, or the end of the stream (BUGS-2026-07 H5: before, the
@@ -457,7 +606,7 @@ export class WebSocketTransport {
         };
         const queue = new ItemQueue();
         const pending = { 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);
@@ -467,14 +616,13 @@ export class WebSocketTransport {
             // 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 = () => {
             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();
@@ -500,8 +648,7 @@ export class WebSocketTransport {
         }
         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);
@@ -537,7 +684,7 @@ export class WebSocketTransport {
         }
         return new Promise((resolve, reject) => {
             const finish = (error) => {
-                clearTimeout(timeout);
+                timeout();
                 this.stateListeners.delete(check);
                 signal?.removeEventListener("abort", onAbort);
                 if (error)
@@ -553,7 +700,7 @@ export class WebSocketTransport {
             };
             // The caller aborted: send() then gives the ABORTED item
             const onAbort = () => 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 });
         });
@@ -609,28 +756,35 @@ export class WebSocketTransport {
      */
     async close() {
         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;
         }
         const hadSocket = this.ws !== null;
         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() {
+        return this.serverProtocol;
+    }
     /**
      * Get current connection state.
      */