@actuallab/rpc 12.3.31 → 12.3.49

package/dist/index.cjs

@@ -33,12 +33,14 @@ __export(index_exports, {
   ARG_DELIMITER: () => ARG_DELIMITER,
   ENVELOPE_DELIMITER: () => ENVELOPE_DELIMITER,
   FRAME_DELIMITER: () => FRAME_DELIMITER,
+  HANDSHAKE_TIMEOUT_MS: () => HANDSHAKE_TIMEOUT_MS,
   IncreasingSeqCompressor: () => IncreasingSeqCompressor,
   RPC_CLOSE_CODE_UNSUPPORTED_FORMAT: () => RPC_CLOSE_CODE_UNSUPPORTED_FORMAT,
   RpcCallStage: () => RpcCallStage,
   RpcCallTypeId: () => RpcCallTypeId,
   RpcClientPeer: () => RpcClientPeer,
   RpcClientPeerReconnectDelayer: () => RpcClientPeerReconnectDelayer,
+  RpcConnectionState: () => RpcConnectionState,
   RpcHub: () => RpcHub,
   RpcInboundCall: () => RpcInboundCall,
   RpcInboundCallTracker: () => RpcInboundCallTracker,
@@ -51,7 +53,7 @@ __export(index_exports, {
   RpcOutboundCall: () => RpcOutboundCall,
   RpcOutboundCallTracker: () => RpcOutboundCallTracker,
   RpcPeer: () => RpcPeer,
-  RpcPeerConnectionKind: () => RpcPeerConnectionKind,
+  RpcPeerRefBuilder: () => RpcPeerRefBuilder,
   RpcPeerStateKind: () => RpcPeerStateKind,
   RpcPeerStateMonitor: () => RpcPeerStateMonitor,
   RpcRemoteExecutionMode: () => RpcRemoteExecutionMode,
@@ -1058,7 +1060,7 @@ var RpcStreamSender = class _RpcStreamSender {
     if (conn) {
       this.peer.hub.systemCallSender.item(
         conn,
-        this.peer.format,
+        this.peer.serializationFormat,
         this.id.localId,
         this._nextIndex,
         item
@@ -1073,7 +1075,7 @@ var RpcStreamSender = class _RpcStreamSender {
     if (conn) {
       this.peer.hub.systemCallSender.batch(
         conn,
-        this.peer.format,
+        this.peer.serializationFormat,
         this.id.localId,
         this._nextIndex,
         items
@@ -1090,7 +1092,7 @@ var RpcStreamSender = class _RpcStreamSender {
     const errorInfo = error ? { TypeRef: "System.Exception", Message: error.message } : { TypeRef: "", Message: "" };
     this.peer.hub.systemCallSender.end(
       conn,
-      this.peer.format,
+      this.peer.serializationFormat,
       this.id.localId,
       this._nextIndex,
       errorInfo
@@ -1545,7 +1547,7 @@ var RpcStream = class _RpcStream {
     this._sender = sender;
     const source = isFactory ? this.localSource(sender.abortSignal) : this.localSource;
     this._whenSent = sender.writeFrom(source);
-    this._toRefValue = peer.format.isBinary ? {
+    this._toRefValue = peer.serializationFormat.isBinary ? {
       SerializedId: [sender.id.hostId, sender.id.localId],
       AckPeriod: sender.ackPeriod,
       AckAdvance: sender.ackAdvance,
@@ -1695,7 +1697,7 @@ var RpcStream = class _RpcStream {
       const hostId = mustReset ? this.id.hostId : _RpcStream._emptyGuid;
       this.peer.hub.systemCallSender.ack(
         conn,
-        this.peer.format,
+        this.peer.serializationFormat,
         this.id.localId,
         nextIndex,
         hostId
@@ -1707,7 +1709,7 @@ var RpcStream = class _RpcStream {
     if (conn) {
       this.peer.hub.systemCallSender.ackEnd(
         conn,
-        this.peer.format,
+        this.peer.serializationFormat,
         this.id.localId,
         this.id.hostId
       );
@@ -1754,9 +1756,8 @@ function base64Encode(bytes) {
   const chunkSize = 32768;
   let binary = "";
   for (let i = 0; i < bytes.length; i += chunkSize) {
-    binary += String.fromCharCode.apply(
-      null,
-      bytes.subarray(i, Math.min(bytes.length, i + chunkSize))
+    binary += String.fromCharCode(
+      ...bytes.subarray(i, Math.min(bytes.length, i + chunkSize))
     );
   }
   return btoa(binary);
@@ -1777,11 +1778,11 @@ var RpcSystemCallHandler = class {
     debugLog?.log(`'${peer.ref}': handle ${method}#${relatedId}`);
     switch (method) {
       case RpcSystemCalls.ok: {
-        const call = peer.outbound.get(relatedId);
+        const call = peer.outboundCalls.get(relatedId);
         if (call !== void 0) {
           call.completedStage |= RpcCallStage.ResultReady;
           if (call.removeOnOk) {
-            peer.outbound.remove(relatedId);
+            peer.outboundCalls.remove(relatedId);
           }
           call.result.resolve(args[0]);
         }
@@ -1792,7 +1793,7 @@ var RpcSystemCallHandler = class {
         break;
       }
       case RpcSystemCalls.error: {
-        const call = peer.outbound.remove(relatedId);
+        const call = peer.outboundCalls.remove(relatedId);
         if (call !== void 0) {
           const errorInfo = args[0];
           const msg = errorInfo?.Message ?? errorInfo?.message ?? "RPC error";
@@ -1807,10 +1808,11 @@ var RpcSystemCallHandler = class {
         break;
       }
       case RpcSystemCalls.cancel: {
-        peer.inbound.remove(relatedId);
+        peer.inboundCalls.remove(relatedId);
         break;
       }
       case RpcSystemCalls.keepAlive: {
+        peer.notifyKeepAliveReceived();
         break;
       }
       case RpcSystemCalls.item: {
@@ -1901,7 +1903,7 @@ var RpcSystemCallHandler = class {
           if (bytes === null) continue;
           const callIds = IncreasingSeqCompressor.deserialize(bytes);
           for (const callId of callIds) {
-            if (peer.inbound.get(callId) === void 0) {
+            if (peer.inboundCalls.get(callId) === void 0) {
               unknownSet.add(callId);
             }
           }
@@ -1911,8 +1913,8 @@ var RpcSystemCallHandler = class {
     } catch {
     }
     const responseBytes = IncreasingSeqCompressor.serialize(unknownIds);
-    const responseValue = peer.format.isBinary ? responseBytes : base64Encode(responseBytes);
-    peer.hub.systemCallSender.ok(peer.connection, peer.format, relatedId, responseValue);
+    const responseValue = peer.serializationFormat.isBinary ? responseBytes : base64Encode(responseBytes);
+    peer.hub.systemCallSender.ok(peer.connection, peer.serializationFormat, relatedId, responseValue);
   }
 };
 function _toBytes(value) {
@@ -2107,16 +2109,7 @@ var RpcSharedObjectTracker = class {
 };
 
 // src/rpc-peer.ts
-var import_core8 = require("@actuallab/core");
-
-// src/rpc-client-peer-reconnect-delayer.ts
 var import_core7 = require("@actuallab/core");
-var RpcClientPeerReconnectDelayer = class extends import_core7.RetryDelayer {
-  constructor() {
-    super();
-    this.delays = import_core7.RetryDelaySeq.exp(1e3, 6e4);
-  }
-};
 
 // src/rpc-serialization-format.ts
 var import_msgpack4 = require("@msgpack/msgpack");
@@ -2277,55 +2270,106 @@ var RpcSerializationFormatResolver = class _RpcSerializationFormatResolver {
 
 // src/rpc-peer.ts
 var RPC_CLOSE_CODE_UNSUPPORTED_FORMAT = 4001;
+var HANDSHAKE_TIMEOUT_MS = 1e4;
+var KEEP_ALIVE_PERIOD_MS = 15e3;
+var KEEP_ALIVE_TIMEOUT_MS = 55e3;
 var { debugLog: debugLog2, infoLog, warnLog: warnLog6, errorLog: errorLog2 } = getLogs("RpcPeer");
 var defaultConnectionUrlResolver = (peer) => {
-  const sep = peer.ref.includes("?") ? "&" : "?";
-  return peer.ref + sep + `clientId=${peer.clientId}&f=${peer.serializationFormat}`;
+  const formatKey = peer.serializationFormat.key;
+  try {
+    const url = new URL(peer.ref);
+    url.searchParams.set("clientId", peer.clientId);
+    url.searchParams.set("f", formatKey);
+    return url.toString();
+  } catch {
+    const sep = peer.ref.includes("?") ? "&" : "?";
+    return peer.ref + sep + `clientId=${peer.clientId}&f=${formatKey}`;
+  }
 };
+function parseFormatFromUrl(url) {
+  try {
+    const f = new URL(url).searchParams.get("f");
+    return f ?? void 0;
+  } catch {
+    return void 0;
+  }
+}
 var RpcPeer = class {
+  hub;
   /** Routing/addressing key — used as key in hub.peers (URL for clients, "server://{uuid}" for servers). */
   ref;
   /** Auto-generated GUID — used in handshakes only. */
   id = crypto.randomUUID();
-  _hub;
-  _connection;
-  outbound = new RpcOutboundCallTracker();
-  inbound = new RpcInboundCallTracker();
+  outboundCalls = new RpcOutboundCallTracker();
+  inboundCalls = new RpcInboundCallTracker();
   remoteObjects = new RpcRemoteObjectTracker();
   sharedObjects = new RpcSharedObjectTracker();
-  connected = new import_core8.EventHandlerSet();
-  disconnected = new import_core8.EventHandlerSet();
+  /** Fired on every state transition with the new value. Initial state is
+   *  `Disconnected`; `Connecting` is entered when the peer starts an
+   *  attempt (the reconnect delay is part of this phase); `Connected` is
+   *  entered only after the handshake has succeeded. */
+  connectionStateChanged = new import_core7.EventHandlerSet();
+  _connection;
+  _connectionState = 0 /* Disconnected */;
   _pendingSends = [];
   _keepAliveTimer;
-  constructor(ref, hub) {
+  _keepAliveWatchdog;
+  /** Wall-clock time of the last inbound `$sys.KeepAlive`, or 0 if none yet
+   *  for the current connection. Useful for diagnostics. */
+  _lastKeepAliveAt = 0;
+  /** Outbound keep-alive send period (per-peer override for tests). */
+  keepAlivePeriodMs = KEEP_ALIVE_PERIOD_MS;
+  /** Inbound keep-alive silence tolerance (per-peer override for tests). */
+  keepAliveTimeoutMs = KEEP_ALIVE_TIMEOUT_MS;
+  constructor(hub, ref) {
+    this.hub = hub;
     this.ref = ref;
-    this._hub = hub;
-  }
-  get hub() {
-    return this._hub;
   }
   get connection() {
     return this._connection;
   }
+  get connectionState() {
+    return this._connectionState;
+  }
   get isConnected() {
     return this._connection?.isOpen ?? false;
   }
+  _setConnectionState(value) {
+    if (this._connectionState === value) return;
+    this._connectionState = value;
+    if (value === 2 /* Connected */)
+      this._armKeepAliveWatchdog();
+    else if (value === 0 /* Disconnected */)
+      this._disarmKeepAliveWatchdog();
+    this.connectionStateChanged.trigger(value);
+  }
+  /** Resolves on the next transition into `Connected` — or immediately if
+   *  already in that state. */
+  whenConnected() {
+    if (this._connectionState === 2 /* Connected */)
+      return Promise.resolve();
+    return new Promise((resolve) => {
+      const handler = (state) => {
+        if (state !== 2 /* Connected */) return;
+        this.connectionStateChanged.remove(handler);
+        resolve();
+      };
+      this.connectionStateChanged.add(handler);
+    });
+  }
   setupConnection(conn) {
     this._connection = conn;
     conn.messageReceived.add((raw) => this._handleMessage(raw));
     conn.closed.add((ev) => {
       this._connection = void 0;
-      this._stopKeepAlive();
       if (ev.reason)
         infoLog?.log(`'${this.ref}': Disconnected: ${ev.reason} (code=${ev.code})`);
       else
         infoLog?.log(`'${this.ref}': Disconnected`);
-      this.disconnected.trigger(ev);
+      this._setConnectionState(0 /* Disconnected */);
     });
     void conn.whenConnected.then(() => {
-      infoLog?.log(`'${this.ref}': Connected`);
-      this.connected.trigger();
-      this._startKeepAlive();
+      infoLog?.log(`'${this.ref}': WS open`);
     });
   }
   /**
@@ -2333,29 +2377,29 @@ var RpcPeer = class {
    * If not set explicitly, defaults to the resolver's default (JSON /
    * json5np). Subclasses can pre-assign in their constructor.
    */
-  _format;
-  get format() {
-    return this._format ?? RpcSerializationFormatResolver.Default.defaultFormat;
+  _serializationFormat;
+  get serializationFormat() {
+    return this._serializationFormat ?? RpcSerializationFormatResolver.Default.defaultFormat;
   }
-  set format(value) {
-    this._format = value;
+  set serializationFormat(value) {
+    this._serializationFormat = value;
   }
   call(method, args, options) {
-    const callId = this.outbound.nextId();
+    const callId = this.outboundCalls.nextId();
     const outboundCall = options?.outboundCallFactory ? options.outboundCallFactory(callId, method) : new RpcOutboundCall(callId, method, options?.remoteExecutionMode ?? 7);
     const envelope = {
       Method: method,
       RelatedId: callId,
       CallType: options?.callTypeId ?? 0
     };
-    outboundCall.serializedWireData = this.format.serializeMessage(
+    outboundCall.serializedWireData = this.serializationFormat.serializeMessage(
       envelope,
       args,
       this._connection?.encoder,
-      this._hub.registry
+      this.hub.registry
     );
     if (this._connection !== void 0) {
-      this.outbound.register(outboundCall);
+      this.outboundCalls.register(outboundCall);
       this._sendWireData(outboundCall.serializedWireData);
     } else {
       this._pendingSends.push(outboundCall);
@@ -2363,11 +2407,11 @@ var RpcPeer = class {
     const signal = options?.signal;
     if (signal !== void 0) {
       const onAbort = () => {
-        if (this.outbound.remove(callId) !== void 0) {
+        if (this.outboundCalls.remove(callId) !== void 0) {
           outboundCall.result.reject(new Error("Call cancelled."));
           outboundCall.onDisconnect();
           if (this._connection !== void 0)
-            this._hub.systemCallSender.cancel(this._connection, this.format, callId);
+            this.hub.systemCallSender.cancel(this._connection, this.serializationFormat, callId);
         } else {
           const idx = this._pendingSends.findIndex(
             (c) => c.callId === callId
@@ -2389,17 +2433,16 @@ var RpcPeer = class {
   callNoWait(method, args) {
     if (this._connection === void 0) return;
     const envelope = { Method: method, RelatedId: 0 };
-    const wireData = this.format.serializeMessage(
+    const wireData = this.serializationFormat.serializeMessage(
       envelope,
       args,
       this._connection.encoder,
-      this._hub.registry
+      this.hub.registry
     );
     this._sendWireData(wireData);
   }
   close() {
     infoLog?.log(`'${this.ref}': Stopping`);
-    this._stopKeepAlive();
     this.remoteObjects.disconnectAll();
     this.sharedObjects.disconnectAll();
     for (const call of this._pendingSends) {
@@ -2408,10 +2451,11 @@ var RpcPeer = class {
       call.onDisconnect();
     }
     this._pendingSends.length = 0;
-    this.outbound.rejectAll(new Error("Peer closed."));
-    this.outbound.invalidateAll();
+    this.outboundCalls.rejectAll(new Error("Peer closed."));
+    this.outboundCalls.invalidateAll();
     this._connection?.close();
-    this._hub.peers.delete(this.ref);
+    this.hub.peers.delete(this.ref);
+    this._setConnectionState(0 /* Disconnected */);
     infoLog?.log(`'${this.ref}': Stopped`);
   }
   /** Send any messages buffered while disconnected. Call after connection + handshake are ready. */
@@ -2419,7 +2463,7 @@ var RpcPeer = class {
     if (this._pendingSends.length === 0 || this._connection === void 0)
       return;
     for (const call of this._pendingSends) {
-      this.outbound.register(call);
+      this.outboundCalls.register(call);
       this._sendWireData(call.serializedWireData);
     }
     this._pendingSends.length = 0;
@@ -2468,7 +2512,7 @@ var RpcPeer = class {
       return;
     }
     if (method.startsWith("$sys")) {
-      this._hub.systemCallHandler.handle(message, args, this);
+      this.hub.systemCallHandler.handle(message, args, this);
       return;
     }
     this._handleInbound(message, args);
@@ -2477,12 +2521,12 @@ var RpcPeer = class {
     const method = message.Method ?? "";
     const relatedId = message.RelatedId ?? 0;
     const call = new RpcInboundCall(relatedId, method, args);
-    const methodDef = this._hub.serviceHost.getMethodDef(method);
+    const methodDef = this.hub.serviceHost.getMethodDef(method);
     const isNoWait = methodDef?.noWait === true;
     if (!isNoWait) {
-      this.inbound.register(call);
+      this.inboundCalls.register(call);
     }
-    const serviceHost = this._hub.serviceHost;
+    const serviceHost = this.hub.serviceHost;
     void (async () => {
       try {
         const context = this._connection !== void 0 ? {
@@ -2497,25 +2541,25 @@ var RpcPeer = class {
         );
         if (methodDef?.stream === true && this._connection !== void 0) {
           const stream = result instanceof RpcStream ? result : new RpcStream(result);
-          this._hub.systemCallSender.ok(
+          this.hub.systemCallSender.ok(
             this._connection,
-            this.format,
+            this.serializationFormat,
             relatedId,
             stream.toRef(this)
           );
         } else if (!isNoWait && this._connection !== void 0) {
-          this._hub.systemCallSender.ok(
+          this.hub.systemCallSender.ok(
             this._connection,
-            this.format,
+            this.serializationFormat,
             relatedId,
             result
           );
         }
       } catch (e) {
         if (!isNoWait && this._connection !== void 0) {
-          this._hub.systemCallSender.error(
+          this.hub.systemCallSender.error(
             this._connection,
-            this.format,
+            this.serializationFormat,
             relatedId,
             e
           );
@@ -2523,36 +2567,64 @@ var RpcPeer = class {
         debugLog2?.log(`'${this.ref}': Inbound call failed: ${method}#${relatedId}`, e);
       } finally {
         if (!isNoWait) {
-          this.inbound.remove(relatedId);
+          this.inboundCalls.remove(relatedId);
         }
       }
     })();
   }
-  _startKeepAlive() {
-    this._keepAliveTimer = setInterval(() => {
+  /** Start sending `$sys.KeepAlive` pings and arm the silence watchdog.
+   *  Called when the peer transitions into `Connected` (after handshake).
+   *  Each inbound `$sys.KeepAlive` re-arms the watchdog; if it fires, the
+   *  WebSocket is force-closed so the normal disconnect path runs
+   *  (`conn.closed` → `connectionState = Disconnected` → UI).
+   *  Mirrors .NET `RpcObjectTrackers.Maintain`'s `KeepAliveTimeout` branch. */
+  _armKeepAliveWatchdog() {
+    this._keepAliveTimer ??= setInterval(() => {
       if (this._connection !== void 0) {
-        this._hub.systemCallSender.keepAlive(this._connection, this.format, [
+        this.hub.systemCallSender.keepAlive(this._connection, this.serializationFormat, [
           ...this.remoteObjects.keys()
         ]);
       }
-    }, 15e3);
+    }, this.keepAlivePeriodMs);
+    if (this._keepAliveWatchdog !== void 0)
+      clearTimeout(this._keepAliveWatchdog);
+    this._keepAliveWatchdog = setTimeout(() => {
+      this._keepAliveWatchdog = void 0;
+      if (this._connection === void 0) return;
+      warnLog6?.log(
+        `'${this.ref}': no keep-alive for ${this.keepAliveTimeoutMs}ms \u2014 force-closing connection`
+      );
+      this._connection.close();
+    }, this.keepAliveTimeoutMs);
   }
-  _stopKeepAlive() {
+  /** Stop sending keep-alives and clear the silence watchdog. Called when
+   *  the peer transitions into `Disconnected`. */
+  _disarmKeepAliveWatchdog() {
     if (this._keepAliveTimer !== void 0) {
       clearInterval(this._keepAliveTimer);
       this._keepAliveTimer = void 0;
     }
+    if (this._keepAliveWatchdog !== void 0) {
+      clearTimeout(this._keepAliveWatchdog);
+      this._keepAliveWatchdog = void 0;
+    }
+  }
+  /** Called by `RpcSystemCallHandler` when a `$sys.KeepAlive` message
+   *  arrives — records the timestamp and re-arms the silence watchdog. */
+  notifyKeepAliveReceived() {
+    this._lastKeepAliveAt = Date.now();
+    if (this._keepAliveWatchdog !== void 0)
+      this._armKeepAliveWatchdog();
   }
 };
-var RpcPeerConnectionKind = /* @__PURE__ */ ((RpcPeerConnectionKind2) => {
-  RpcPeerConnectionKind2[RpcPeerConnectionKind2["Disconnected"] = 0] = "Disconnected";
-  RpcPeerConnectionKind2[RpcPeerConnectionKind2["Connecting"] = 1] = "Connecting";
-  RpcPeerConnectionKind2[RpcPeerConnectionKind2["Connected"] = 2] = "Connected";
-  return RpcPeerConnectionKind2;
-})(RpcPeerConnectionKind || {});
+var RpcConnectionState = /* @__PURE__ */ ((RpcConnectionState2) => {
+  RpcConnectionState2[RpcConnectionState2["Disconnected"] = 0] = "Disconnected";
+  RpcConnectionState2[RpcConnectionState2["Connecting"] = 1] = "Connecting";
+  RpcConnectionState2[RpcConnectionState2["Connected"] = 2] = "Connected";
+  return RpcConnectionState2;
+})(RpcConnectionState || {});
 var RpcClientPeer = class extends RpcPeer {
   _disposed = false;
-  _connectionKind = 0 /* Disconnected */;
   _tryIndex = 0;
   _handshakeIndex = 0;
   /** Index from the MOST RECENTLY RECEIVED server handshake — sent back
@@ -2566,19 +2638,21 @@ var RpcClientPeer = class extends RpcPeer {
   _reconnectsAt = 0;
   /** Base64url-encoded peer ID — matches .NET's RpcClientPeer.ClientId (Guid.ToBase64Url). */
   clientId;
-  /**
-   * Serialization format key sent to the server via `f=` query parameter.
-   * TS uses plain JSON.stringify (no polymorphic type wrapping), so `json5np`
-   * (no-polymorphism) is the correct default.
-   */
-  serializationFormat;
   /** Builds the WebSocket URL for this peer. Replace to customize URL construction. */
   connectionUrlResolver = defaultConnectionUrlResolver;
-  peerChanged = new import_core8.EventHandlerSet();
+  /** Optional WebSocket factory. When set, `run()` uses this instead of the
+   *  global `new WebSocket(url)` constructor. Used by tests (to inject mock
+   *  sockets) and by the Node load-test harness (to attach `Session` /
+   *  `Cookie` headers to the WS upgrade, which the browser `WebSocket`
+   *  constructor can't do). Must be set before `start()`. */
+  webSocketFactory;
+  /** Max time to wait for the server's handshake response before aborting
+   *  the connection attempt. Mirrors .NET's `Hub.Limits.HandshakeTimeout`. */
+  handshakeTimeoutMs = HANDSHAKE_TIMEOUT_MS;
+  peerChanged = new import_core7.EventHandlerSet();
   /** Fired when the server rejects the connection due to an unsupported serialization format (close code 4010). */
-  unsupportedFormat = new import_core8.EventHandlerSet();
-  reconnectDelayer = new RpcClientPeerReconnectDelayer();
-  reconnectsAtChanged = new import_core8.EventHandlerSet();
+  unsupportedFormat = new import_core7.EventHandlerSet();
+  reconnectsAtChanged = new import_core7.EventHandlerSet();
   get reconnectsAt() {
     return this._reconnectsAt;
   }
@@ -2587,17 +2661,32 @@ var RpcClientPeer = class extends RpcPeer {
     this._reconnectsAt = value;
     this.reconnectsAtChanged.trigger();
   }
-  constructor(hub, url, serializationFormat) {
-    super(url, hub);
+  /** The promise returned by the reconnect loop. `undefined` until
+   *  `start()` is invoked (which happens automatically when
+   *  `mustStart = true` is passed to the ctor). */
+  whenRunning;
+  /**
+   * @param hub RpcHub instance this peer will be tracked by
+   * @param url Full WebSocket URL — the serialization format is taken from
+   *            the `f=` query parameter (e.g. `wss://host/rpc/ws?f=msgpack6`);
+   *            falls back to the resolver's default when absent. Use
+   *            {@link RpcPeerRefBuilder.forClient} to compose URLs with a format.
+   * @param mustStart Kick off the reconnect loop automatically at the end of
+   *            construction (default `true`). Pass `false` if you need to
+   *            tweak `reconnectDelayer`, `handshakeTimeoutMs`, or similar
+   *            options before the loop starts — then call `peer.start()`
+   *            manually.
+   */
+  constructor(hub, url, mustStart = true) {
+    super(hub, url);
     this.clientId = guidToBase64Url(this.id);
     const resolver = RpcSerializationFormatResolver.Default;
-    this.serializationFormat = serializationFormat ?? resolver.defaultFormatKey;
-    this.format = resolver.get(this.serializationFormat);
-  }
-  get connectionKind() {
-    return this._connectionKind;
+    this.serializationFormat = resolver.get(parseFormatFromUrl(url) ?? resolver.defaultFormatKey);
+    if (mustStart)
+      this.start();
   }
   /** One-shot connection for tests — no reconnection loop, no handshake.
+   *  @param conn Rpc connection
    *  @param isPeerChanged Whether to treat this as a peer-identity change
    *  (default `true` — no handshake was exchanged, so stage-3 compute calls
    *  self-invalidate and remote/shared objects are disposed). Pass `false`
@@ -2606,97 +2695,137 @@ var RpcClientPeer = class extends RpcPeer {
     this.setupConnection(conn);
     void this._reconnect(isPeerChanged);
   }
-  /** Start the reconnection loop — runs until disposed. */
-  async run(wsFactory) {
+  /** Kick off the reconnect loop. Idempotent — subsequent calls are
+   *  no-ops; await `peer.whenRunning` if you need the loop's completion
+   *  promise. Customize `peer.webSocketFactory` first if you need a
+   *  non-default WebSocket constructor. */
+  start() {
+    void this.run();
+  }
+  /** The reconnect loop itself. Exposed as `protected` so subclasses (and
+   *  `start()`) can drive it; public callers should use {@link start}. */
+  run() {
+    return this.whenRunning ??= this._runImpl();
+  }
+  async _runImpl() {
+    if (this._disposed) return;
     const connUrl = this.connectionUrlResolver(this);
     infoLog?.log(`'${this.ref}': Started (Client)`);
-    while (!this._disposed) {
-      let lastCloseCode = 0;
-      let lastCloseReason = "";
-      try {
-        infoLog?.log(`'${this.ref}': Connecting to ${connUrl}`);
-        const ws = wsFactory?.(connUrl) ?? new WebSocket(connUrl);
-        const conn = new RpcWebSocketConnection(
-          ws,
-          this.format.isBinary,
-          this.format,
-          this._hub.registry
-        );
-        this._connectionKind = 1 /* Connecting */;
-        conn.closed.add((ev) => {
-          lastCloseCode = ev.code;
-          lastCloseReason = ev.reason;
-        });
-        this._pendingHandshake = new import_core8.PromiseSource();
-        this.setupConnection(conn);
-        this._connection = void 0;
-        const closedRejection = new Promise(
-          (_, reject) => conn.closed.add(
-            () => reject(new Error("Connection failed"))
-          )
-        );
-        closedRejection.catch(() => {
-        });
-        await Promise.race([conn.whenConnected, closedRejection]);
+    try {
+      while (!this._disposed) {
+        this._setConnectionState(1 /* Connecting */);
+        const retryDelay = this.hub.reconnectDelayer.getDelay(this._tryIndex);
+        if (retryDelay.isLimitExceeded) {
+          warnLog6?.log(`'${this.ref}': Reconnect limit exceeded - shutting down`);
+          this._disposed = true;
+          break;
+        }
+        this._setReconnectsAt(retryDelay.endsAt);
+        try {
+          await retryDelay.promise;
+        } finally {
+          this._setReconnectsAt(0);
+        }
+        if (this._disposed) break;
+        let lastCloseCode = 0;
+        let lastCloseReason = "";
         try {
-          this._hub.systemCallSender.handshake(
-            conn,
-            this.format,
-            this.id,
-            this._hub.hubId,
-            ++this._handshakeIndex
+          infoLog?.log(`'${this.ref}': Connecting to ${connUrl}`);
+          const ws = this.webSocketFactory?.(connUrl) ?? new WebSocket(connUrl);
+          const conn = new RpcWebSocketConnection(
+            ws,
+            this.serializationFormat.isBinary,
+            this.serializationFormat,
+            this.hub.registry
           );
+          const whenClosed = new import_core7.PromiseSource();
+          const closedController = new AbortController();
+          conn.closed.add((ev) => {
+            lastCloseCode = ev.code;
+            lastCloseReason = ev.reason;
+            whenClosed.resolve(ev);
+            closedController.abort();
+          });
+          const closedRejection = whenClosed.promise.then(() => {
+            throw new Error("Connection failed");
+          });
+          closedRejection.catch(() => {
+          });
+          this._pendingHandshake = new import_core7.PromiseSource();
+          this.setupConnection(conn);
+          this._connection = void 0;
+          await Promise.race([conn.whenConnected, closedRejection]);
+          try {
+            this.hub.systemCallSender.handshake(
+              conn,
+              this.serializationFormat,
+              this.id,
+              this.hub.hubId,
+              ++this._handshakeIndex
+            );
+          } catch (e) {
+            warnLog6?.log(`'${this.ref}': Failed to send handshake`, e);
+            throw e;
+          }
+          const handshakeTimeoutMs = this.handshakeTimeoutMs;
+          let handshakeTimer;
+          const handshakeTimeout = new Promise((_, reject) => {
+            handshakeTimer = setTimeout(() => {
+              reject(new Error("Handshake timeout"));
+            }, handshakeTimeoutMs);
+          });
+          handshakeTimeout.catch(() => {
+          });
+          let remoteHandshake;
+          try {
+            remoteHandshake = await Promise.race([
+              this._pendingHandshake.promise,
+              closedRejection,
+              handshakeTimeout
+            ]);
+          } catch (e) {
+            if (e instanceof Error && e.message === "Handshake timeout") {
+              warnLog6?.log(`'${this.ref}': Handshake timed out after ${handshakeTimeoutMs}ms`);
+              conn.close();
+            }
+            throw e;
+          } finally {
+            if (handshakeTimer !== void 0) clearTimeout(handshakeTimer);
+            this._pendingHandshake = void 0;
+          }
+          this._remoteHandshakeIndex = remoteHandshake.Index ?? 0;
+          const remoteHubId = remoteHandshake.RemoteHubId;
+          let isPeerChanged = false;
+          if (remoteHubId !== void 0) {
+            isPeerChanged = this._lastRemoteHubId !== void 0 && this._lastRemoteHubId !== remoteHubId;
+            if (isPeerChanged) {
+              this.inboundCalls.clear();
+              infoLog?.log(`'${this.ref}': Peer changed`);
+              this.peerChanged.trigger();
+            }
+            this._lastRemoteHubId = remoteHubId;
+          }
+          infoLog?.log(`'${this.ref}': Handshake succeeded, peerChanged=${isPeerChanged}`);
+          this._connection = conn;
+          this._setConnectionState(2 /* Connected */);
+          this._tryIndex = 0;
+          await this._reconnect(isPeerChanged, closedController.signal);
+          await whenClosed.promise;
         } catch (e) {
-          warnLog6?.log(`'${this.ref}': Failed to send handshake`, e);
-          throw e;
+          debugLog2?.log(`'${this.ref}': run() iteration failed:`, e);
         }
-        const remoteHandshake = await Promise.race([
-          this._pendingHandshake.promise,
-          closedRejection
-        ]);
-        this._pendingHandshake = void 0;
-        this._remoteHandshakeIndex = remoteHandshake.Index ?? 0;
-        const remoteHubId = remoteHandshake.RemoteHubId;
-        let isPeerChanged = false;
-        if (remoteHubId !== void 0) {
-          isPeerChanged = this._lastRemoteHubId !== void 0 && this._lastRemoteHubId !== remoteHubId;
-          if (isPeerChanged) {
-            this.inbound.clear();
-            infoLog?.log(`'${this.ref}': Peer changed`);
-            this.peerChanged.trigger();
-          }
-          this._lastRemoteHubId = remoteHubId;
+        this._setConnectionState(0 /* Disconnected */);
+        if (this._disposed) break;
+        if (lastCloseCode === RPC_CLOSE_CODE_UNSUPPORTED_FORMAT) {
+          warnLog6?.log(`'${this.ref}': Unsupported serialization format - shutting down`);
+          this.unsupportedFormat.trigger({ reason: lastCloseReason });
+          this._disposed = true;
+          break;
         }
-        infoLog?.log(`'${this.ref}': Handshake succeeded, peerChanged=${isPeerChanged}`);
-        this._connection = conn;
-        this._connectionKind = 2 /* Connected */;
-        this._tryIndex = 0;
-        await this._reconnect(isPeerChanged);
-        await new Promise((r) => conn.closed.add(() => r()));
-      } catch (e) {
-        debugLog2?.log(`'${this.ref}': run() iteration failed:`, e);
-      }
-      this._connectionKind = 0 /* Disconnected */;
-      if (this._disposed) break;
-      if (lastCloseCode === RPC_CLOSE_CODE_UNSUPPORTED_FORMAT) {
-        warnLog6?.log(`'${this.ref}': Unsupported serialization format - shutting down`);
-        this.unsupportedFormat.trigger({ reason: lastCloseReason });
-        this._disposed = true;
-        break;
-      }
-      this._tryIndex++;
-      const delay = this.reconnectDelayer.getDelay(this._tryIndex);
-      if (delay.isLimitExceeded) {
-        warnLog6?.log(`'${this.ref}': Reconnect limit exceeded - shutting down`);
-        this._disposed = true;
-        break;
-      }
-      this._setReconnectsAt(delay.endsAt);
-      try {
-        await delay.promise;
-      } finally {
-        this._setReconnectsAt(0);
+        this._tryIndex++;
       }
+    } finally {
+      this._setConnectionState(0 /* Disconnected */);
     }
   }
   /**
@@ -2718,7 +2847,7 @@ var RpcClientPeer = class extends RpcPeer {
    * are always self-invalidated — TS doesn't track compute-call stages
    * across reconnect, so the safest behavior is to force a fresh compute.
    */
-  async _reconnect(isPeerChanged) {
+  async _reconnect(isPeerChanged, closedSignal) {
     if (this._connection === void 0) return;
     if (isPeerChanged) {
       this.remoteObjects.disconnectAll();
@@ -2727,7 +2856,7 @@ var RpcClientPeer = class extends RpcPeer {
       this.remoteObjects.reconnectAll();
     }
     const eligible = [];
-    for (const call of [...this.outbound.values()]) {
+    for (const call of [...this.outboundCalls.values()]) {
       const mode = call.remoteExecutionMode;
       if (!(mode & 2)) {
         if (!call.result.isCompleted)
@@ -2735,7 +2864,7 @@ var RpcClientPeer = class extends RpcPeer {
             "Outbound call failed: disconnected and AllowReconnect is not set."
           ));
         call.onDisconnect();
-        this.outbound.remove(call.callId);
+        this.outboundCalls.remove(call.callId);
         continue;
       }
       if (isPeerChanged && !(mode & 4)) {
@@ -2744,19 +2873,19 @@ var RpcClientPeer = class extends RpcPeer {
             "Outbound call failed: reconnected to a different peer and AllowResend is not set."
           ));
         call.onDisconnect();
-        this.outbound.remove(call.callId);
+        this.outboundCalls.remove(call.callId);
         continue;
       }
       eligible.push(call);
     }
     let unknownIds = null;
     if (!isPeerChanged && eligible.length > 0) {
-      unknownIds = await this._reconcileReconnect(eligible);
+      unknownIds = await this._reconcileReconnect(eligible, closedSignal);
     }
     for (const call of eligible) {
       if (!call.removeOnOk && call.result.isCompleted) {
         call.onDisconnect();
-        this.outbound.remove(call.callId);
+        this.outboundCalls.remove(call.callId);
         continue;
       }
       if (unknownIds !== null && !unknownIds.has(call.callId)) {
@@ -2779,7 +2908,7 @@ var RpcClientPeer = class extends RpcPeer {
    *     native msgpack `map<int, bin>`, matching .NET MessagePack-CSharp's
    *     default for `Dictionary<int, byte[]>`.
    */
-  async _reconcileReconnect(eligible) {
+  async _reconcileReconnect(eligible, closedSignal) {
     try {
       const byStage = /* @__PURE__ */ new Map();
       for (const call of eligible) {
@@ -2795,7 +2924,7 @@ var RpcClientPeer = class extends RpcPeer {
       if (byStage.size === 0) {
         return new Set(eligible.map((c) => c.callId));
       }
-      const isBinary = this.format.isBinary;
+      const isBinary = this.serializationFormat.isBinary;
       const stagesArg = isBinary ? /* @__PURE__ */ new Map() : {};
       for (const [stage, ids] of byStage) {
         ids.sort((a, b) => a - b);
@@ -2810,8 +2939,9 @@ var RpcClientPeer = class extends RpcPeer {
         RpcSystemCalls.reconnect,
         [this._remoteHandshakeIndex, stagesArg],
         {
-          remoteExecutionMode: 1
+          remoteExecutionMode: 1,
           /* AwaitForConnection only; must not itself reconnect */
+          signal: closedSignal
         }
       );
       const result = await reconnectCall.result.promise;
@@ -2831,11 +2961,14 @@ var RpcClientPeer = class extends RpcPeer {
   }
 };
 var RpcServerPeer = class extends RpcPeer {
+  // Needed to widen the base `protected constructor` to public.
+  // eslint-disable-next-line @typescript-eslint/no-useless-constructor
   constructor(hub, ref) {
-    super(ref, hub);
+    super(hub, ref);
   }
   /** Accept an incoming connection — sets up message handling and handshake response. */
   accept(conn) {
+    this._setConnectionState(1 /* Connecting */);
     this.setupConnection(conn);
     conn.closed.add(() => {
       this.sharedObjects.disconnectAll();
@@ -2843,13 +2976,14 @@ var RpcServerPeer = class extends RpcPeer {
   }
   _onHandshakeReceived(_handshake) {
     if (this._connection !== void 0) {
-      this._hub.systemCallSender.handshake(
+      this.hub.systemCallSender.handshake(
         this._connection,
-        this.format,
+        this.serializationFormat,
         this.id,
-        this._hub.hubId,
+        this.hub.hubId,
         0
       );
+      this._setConnectionState(2 /* Connected */);
     }
   }
 };
@@ -2881,6 +3015,15 @@ function _toBytes2(value) {
   return null;
 }
 
+// src/rpc-client-peer-reconnect-delayer.ts
+var import_core8 = require("@actuallab/core");
+var RpcClientPeerReconnectDelayer = class extends import_core8.RetryDelayer {
+  constructor() {
+    super();
+    this.delays = import_core8.RetryDelaySeq.fixed(100);
+  }
+};
+
 // src/rpc-service-host.ts
 var { warnLog: warnLog7 } = getLogs("RpcServiceHost");
 var RpcServiceHost = class {
@@ -3483,6 +3626,16 @@ var RpcHub = class {
   /** Method registry for compact format hash ↔ name resolution.
    *  Created lazily, populated by addService/addClient. */
   registry = new RpcMethodRegistry();
+  /** Shared reconnect delayer used by every client peer in this hub. Swap in
+   *  a custom subclass (e.g. app-level signal-gated) before peers start. */
+  reconnectDelayer = new RpcClientPeerReconnectDelayer();
+  /** URL used by {@link defaultPeer} to resolve / create the default client
+   *  peer. Must be set before the first {@link defaultPeer} access. */
+  defaultPeerUrl;
+  /** Factory used by {@link defaultPeer} when the peer needs to be created.
+   *  If left undefined, `getPeer`'s built-in default (RpcClientPeer with
+   *  format derived from URL or resolver default) is used. */
+  defaultPeerFactory;
   constructor(hubId) {
     this.hubId = hubId ?? crypto.randomUUID();
     this.serviceHost = new RpcServiceHost();
@@ -3491,7 +3644,20 @@ var RpcHub = class {
       this.registry.register(methodName);
     }
   }
+  /** Shortcut for the hub's default client peer. Fails if
+   *  {@link defaultPeerUrl} is not set. */
+  get defaultPeer() {
+    if (this.defaultPeerUrl === void 0)
+      throw new Error("RpcHub.defaultPeerUrl is not set.");
+    return this.getClientPeer(this.defaultPeerUrl, this.defaultPeerFactory);
+  }
+  /** Register a peer under its ref. If a different peer is already registered
+   *  at the same ref, close it first — the hub guarantees at most one live
+   *  peer per ref, and no peer exists outside the hub. */
   addPeer(peer) {
+    const existing = this.peers.get(peer.ref);
+    if (existing !== void 0 && existing !== peer)
+      existing.close();
     this.peers.set(peer.ref, peer);
   }
   removePeer(ref) {
@@ -3502,21 +3668,27 @@ var RpcHub = class {
       warnLog9?.log(`'${ref}': peer is removed from RpcHub`);
     }
   }
-  /** Get or create a peer by ref. Server peers have "server://" prefix, everything else is a client peer. */
-  getPeer(ref) {
-    let peer = this.peers.get(ref);
-    if (peer) return peer;
-    peer = ref.startsWith("server://") ? new RpcServerPeer(this, ref) : new RpcClientPeer(this, ref);
+  /** Get or create a peer by ref. If the peer does not exist:
+   *   - with `factory` provided: it is constructed via `factory(this, ref)`;
+   *   - otherwise: server peers (ref starts with `server://`) get a plain
+   *     RpcServerPeer, anything else gets a default-configured RpcClientPeer.
+   *  The created peer is always registered in this hub. */
+  getPeer(ref, factory) {
+    const existing = this.peers.get(ref);
+    if (existing) return existing;
+    const peer = factory ? factory(this, ref) : ref.startsWith("server://") ? new RpcServerPeer(this, ref) : new RpcClientPeer(this, ref);
     this.addPeer(peer);
     return peer;
   }
-  /** Get or create a client peer for the given URL. */
-  getClientPeer(ref) {
-    return this.getPeer(ref);
+  /** Get or create a client peer for the given URL. See {@link getPeer} for
+   *  the factory semantics. */
+  getClientPeer(ref, factory) {
+    return this.getPeer(ref, factory);
   }
-  /** Get or create a server peer for the given ref. */
-  getServerPeer(ref) {
-    return this.getPeer(ref);
+  /** Get or create a server peer for the given ref. See {@link getPeer} for
+   *  the factory semantics. */
+  getServerPeer(ref, factory) {
+    return this.getPeer(ref, factory);
   }
   /** Register a service with optional server method wrapping for custom call types. */
   addService(defOrContract, impl) {
@@ -3645,6 +3817,25 @@ var RpcHub = class {
   }
 };
 
+// src/rpc-peer-ref-builder.ts
+var RpcPeerRefBuilder = class {
+  /** Build a client peer ref from a WebSocket URL, optionally baking in the
+   *  serialization format as a `f=` query parameter.
+   *  @param url Base WebSocket URL, e.g. `wss://host/rpc/ws`.
+   *  @param serializationFormat Optional format key, e.g. `msgpack6`. When
+   *         provided, replaces any existing `f=` in the URL. */
+  static forClient(url, serializationFormat) {
+    if (serializationFormat === void 0) return url;
+    const u = new URL(url);
+    u.searchParams.set("f", serializationFormat);
+    return u.toString();
+  }
+  /** Build a server peer ref from a peer id — returns `server://{id}`. */
+  static forServer(id) {
+    return `server://${id}`;
+  }
+};
+
 // src/rpc-client.ts
 function createRpcClient(peer, serviceDef) {
   const overloads = /* @__PURE__ */ new Map();
@@ -3746,20 +3937,18 @@ var RpcPeerStateMonitor = class {
   _state;
   _timer;
   // Arrow functions to preserve `this` when used as event handlers
-  _onConnected = () => {
-    this._rawConnected = true;
-    this._connectedAt = Date.now();
-    this._lastError = void 0;
-    this._recompute();
-  };
-  _onDisconnected = (ev) => {
-    const wasConnected = this._rawConnected;
-    this._rawConnected = false;
-    this._lastError = new Error(
-      `Connection closed: ${ev.reason} (code ${ev.code})`
-    );
-    if (wasConnected) {
-      this._disconnectedAt = Date.now();
+  _onConnectionStateChanged = (state) => {
+    if (state === 2 /* Connected */) {
+      this._rawConnected = true;
+      this._connectedAt = Date.now();
+      this._lastError = void 0;
+    } else {
+      const wasConnected = this._rawConnected;
+      this._rawConnected = false;
+      this._lastError = new Error("Connection closed");
+      if (wasConnected) {
+        this._disconnectedAt = Date.now();
+      }
     }
     this._recompute();
   };
@@ -3785,10 +3974,9 @@ var RpcPeerStateMonitor = class {
         reconnectsIn: 0
       };
     }
-    peer.connected.add(this._onConnected);
-    peer.disconnected.add(this._onDisconnected);
+    peer.connectionStateChanged.add(this._onConnectionStateChanged);
     peer.reconnectsAtChanged.add(this._onReconnectsAtChanged);
-    peer.reconnectDelayer.cancelDelaysChanged.add(
+    peer.hub.reconnectDelayer.cancelDelaysChanged.add(
       this._onCancelDelaysChanged
     );
     this._scheduleRecompute(
@@ -3804,10 +3992,9 @@ var RpcPeerStateMonitor = class {
       clearTimeout(this._timer);
       this._timer = void 0;
     }
-    this.peer.connected.remove(this._onConnected);
-    this.peer.disconnected.remove(this._onDisconnected);
+    this.peer.connectionStateChanged.remove(this._onConnectionStateChanged);
     this.peer.reconnectsAtChanged.remove(this._onReconnectsAtChanged);
-    this.peer.reconnectDelayer.cancelDelaysChanged.remove(
+    this.peer.hub.reconnectDelayer.cancelDelaysChanged.remove(
       this._onCancelDelaysChanged
     );
     infoLog2?.log(`'${this.peer.ref}': monitor stopped`);
@@ -3890,12 +4077,14 @@ var RpcPeerStateMonitor = class {
   ARG_DELIMITER,
   ENVELOPE_DELIMITER,
   FRAME_DELIMITER,
+  HANDSHAKE_TIMEOUT_MS,
   IncreasingSeqCompressor,
   RPC_CLOSE_CODE_UNSUPPORTED_FORMAT,
   RpcCallStage,
   RpcCallTypeId,
   RpcClientPeer,
   RpcClientPeerReconnectDelayer,
+  RpcConnectionState,
   RpcHub,
   RpcInboundCall,
   RpcInboundCallTracker,
@@ -3908,7 +4097,7 @@ var RpcPeerStateMonitor = class {
   RpcOutboundCall,
   RpcOutboundCallTracker,
   RpcPeer,
-  RpcPeerConnectionKind,
+  RpcPeerRefBuilder,
   RpcPeerStateKind,
   RpcPeerStateMonitor,
   RpcRemoteExecutionMode,