@actuallab/rpc 12.3.33 → 12.3.50

package/dist/index.d.cts

@@ -638,6 +638,11 @@ declare class RpcSystemCallSender {
     ackEnd(conn: RpcConnection, format: RpcSerializationFormat, localId: number, hostId: string): void;
 }
 
+/** Factory signature shared by all peer lookup/creation methods. Serialization
+ *  format is encoded in the URL via `?f=...` (see {@link RpcPeerRefBuilder}),
+ *  so the factory doesn't need an extra parameter for it. `getClientPeer` /
+ *  `getServerPeer` cast the result, so the factory returns RpcPeer. */
+type RpcPeerFactory = (hub: RpcHub, ref: string) => RpcPeer;
 /** Central RPC coordinator — manages peers, services, and configuration. */
 declare class RpcHub {
     readonly hubId: string;
@@ -648,15 +653,37 @@ declare class RpcHub {
     /** Method registry for compact format hash ↔ name resolution.
      *  Created lazily, populated by addService/addClient. */
     readonly registry: 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: RpcClientPeerReconnectDelayer;
+    /** URL used by {@link defaultPeer} to resolve / create the default client
+     *  peer. Must be set before the first {@link defaultPeer} access. */
+    defaultPeerUrl: string | undefined;
+    /** 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: RpcPeerFactory | undefined;
     constructor(hubId?: string);
+    /** Shortcut for the hub's default client peer. Fails if
+     *  {@link defaultPeerUrl} is not set. */
+    get defaultPeer(): RpcClientPeer;
+    /** 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: RpcPeer): void;
     removePeer(ref: string): void;
-    /** Get or create a peer by ref. Server peers have "server://" prefix, everything else is a client peer. */
-    getPeer(ref: string): RpcPeer;
-    /** Get or create a client peer for the given URL. */
-    getClientPeer(ref: string): RpcClientPeer;
-    /** Get or create a server peer for the given ref. */
-    getServerPeer(ref: string): RpcServerPeer;
+    /** 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: string, factory?: RpcPeerFactory): RpcPeer;
+    /** Get or create a client peer for the given URL. See {@link getPeer} for
+     *  the factory semantics. */
+    getClientPeer(ref: string, factory?: RpcPeerFactory): RpcClientPeer;
+    /** Get or create a server peer for the given ref. See {@link getPeer} for
+     *  the factory semantics. */
+    getServerPeer(ref: string, factory?: RpcPeerFactory): RpcServerPeer;
     /** Register a service with optional server method wrapping for custom call types. */
     addService(defOrContract: RpcServiceDef | (AnyConstructor), impl: RpcServiceImpl): void;
     /** Create a typed client proxy for a service on a remote peer. */
@@ -712,9 +739,13 @@ declare class RpcSharedObjectTracker {
 
 /** WebSocket close code sent by the server when the client's serialization format is unsupported. */
 declare const RPC_CLOSE_CODE_UNSUPPORTED_FORMAT = 4001;
+/** Maximum time to wait for the server's handshake response after opening the socket. */
+declare const HANDSHAKE_TIMEOUT_MS = 10000;
 /** Builds the WebSocket connection URL for an RpcClientPeer. */
 type RpcConnectionUrlResolver = (peer: RpcClientPeer) => string;
-/** Default connection URL provider — appends `clientId` and `f` query parameters. */
+/** Default connection URL provider — sets `clientId` and `f` query parameters,
+ *  replacing any existing values to keep the wire format consistent with the
+ *  peer's actual `serializationFormat`. */
 declare const defaultConnectionUrlResolver: RpcConnectionUrlResolver;
 /** Options for RpcPeer.call() — allows custom call types and cancellation. */
 interface RpcCallOptions {
@@ -736,36 +767,49 @@ interface RemoteHandshake {
 }
 /** Base class for RPC peers — handles bidirectional message dispatch. */
 declare abstract class RpcPeer {
+    readonly hub: RpcHub;
     /** Routing/addressing key — used as key in hub.peers (URL for clients, "server://{uuid}" for servers). */
     readonly ref: string;
     /** Auto-generated GUID — used in handshakes only. */
     readonly id: string;
-    protected _hub: RpcHub;
-    protected _connection: RpcConnection | undefined;
-    readonly outbound: RpcOutboundCallTracker;
-    readonly inbound: RpcInboundCallTracker;
+    readonly outboundCalls: RpcOutboundCallTracker;
+    readonly inboundCalls: RpcInboundCallTracker;
     readonly remoteObjects: RpcRemoteObjectTracker;
     readonly sharedObjects: RpcSharedObjectTracker;
-    readonly connected: EventHandlerSet<void>;
-    readonly disconnected: EventHandlerSet<{
-        code: number;
-        reason: string;
-    }>;
+    /** 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. */
+    readonly connectionStateChanged: EventHandlerSet<RpcConnectionState>;
+    protected _connection: RpcConnection | undefined;
+    protected _connectionState: RpcConnectionState;
     protected _pendingSends: RpcOutboundCall[];
     private _keepAliveTimer;
-    constructor(ref: string, hub: RpcHub);
-    get hub(): RpcHub;
+    private _keepAliveWatchdog;
+    /** Wall-clock time of the last inbound `$sys.KeepAlive`, or 0 if none yet
+     *  for the current connection. Useful for diagnostics. */
+    private _lastKeepAliveAt;
+    /** Outbound keep-alive send period (per-peer override for tests). */
+    keepAlivePeriodMs: number;
+    /** Inbound keep-alive silence tolerance (per-peer override for tests). */
+    keepAliveTimeoutMs: number;
+    protected constructor(hub: RpcHub, ref: string);
     get connection(): RpcConnection | undefined;
+    get connectionState(): RpcConnectionState;
     get isConnected(): boolean;
+    protected _setConnectionState(value: RpcConnectionState): void;
+    /** Resolves on the next transition into `Connected` — or immediately if
+     *  already in that state. */
+    whenConnected(): Promise<void>;
     protected setupConnection(conn: RpcConnection): void;
     /**
      * The serialization format used by this peer for outgoing messages.
      * If not set explicitly, defaults to the resolver's default (JSON /
      * json5np). Subclasses can pre-assign in their constructor.
      */
-    private _format;
-    get format(): RpcSerializationFormat;
-    set format(value: RpcSerializationFormat);
+    private _serializationFormat;
+    get serializationFormat(): RpcSerializationFormat;
+    set serializationFormat(value: RpcSerializationFormat);
     call(method: string, args?: unknown[], options?: RpcCallOptions): RpcOutboundCall;
     callNoWait(method: string, args?: unknown[]): void;
     close(): void;
@@ -777,11 +821,22 @@ declare abstract class RpcPeer {
     protected _onHandshakeReceived(_handshake: RemoteHandshake): void;
     private _handleMessage;
     private _handleInbound;
-    private _startKeepAlive;
-    private _stopKeepAlive;
+    /** 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. */
+    private _armKeepAliveWatchdog;
+    /** Stop sending keep-alives and clear the silence watchdog. Called when
+     *  the peer transitions into `Disconnected`. */
+    private _disarmKeepAliveWatchdog;
+    /** Called by `RpcSystemCallHandler` when a `$sys.KeepAlive` message
+     *  arrives — records the timestamp and re-arms the silence watchdog. */
+    notifyKeepAliveReceived(): void;
 }
 /** Connection state for RpcClientPeer. */
-declare const enum RpcPeerConnectionKind {
+declare const enum RpcConnectionState {
     Disconnected = 0,
     Connecting = 1,
     Connected = 2
@@ -789,7 +844,6 @@ declare const enum RpcPeerConnectionKind {
 /** Client-side RPC peer — initiates WebSocket connection. ref = URL. */
 declare class RpcClientPeer extends RpcPeer {
     private _disposed;
-    private _connectionKind;
     private _tryIndex;
     private _handshakeIndex;
     /** Index from the MOST RECENTLY RECEIVED server handshake — sent back
@@ -803,33 +857,58 @@ declare class RpcClientPeer extends RpcPeer {
     private _reconnectsAt;
     /** Base64url-encoded peer ID — matches .NET's RpcClientPeer.ClientId (Guid.ToBase64Url). */
     readonly clientId: string;
-    /**
-     * 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.
-     */
-    readonly serializationFormat: string;
     /** Builds the WebSocket URL for this peer. Replace to customize URL construction. */
     connectionUrlResolver: RpcConnectionUrlResolver;
+    /** 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: ((url: string) => WebSocketLike) | undefined;
+    /** Max time to wait for the server's handshake response before aborting
+     *  the connection attempt. Mirrors .NET's `Hub.Limits.HandshakeTimeout`. */
+    handshakeTimeoutMs: number;
     readonly peerChanged: EventHandlerSet<void>;
     /** Fired when the server rejects the connection due to an unsupported serialization format (close code 4010). */
     readonly unsupportedFormat: EventHandlerSet<{
         reason: string;
     }>;
-    readonly reconnectDelayer: RpcClientPeerReconnectDelayer;
     readonly reconnectsAtChanged: EventHandlerSet<void>;
     get reconnectsAt(): number;
     private _setReconnectsAt;
-    constructor(hub: RpcHub, url: string, serializationFormat?: string);
-    get connectionKind(): RpcPeerConnectionKind;
+    /** The promise returned by the reconnect loop. `undefined` until
+     *  `start()` is invoked (which happens automatically when
+     *  `mustStart = true` is passed to the ctor). */
+    whenRunning: Promise<void> | undefined;
+    /**
+     * @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: RpcHub, url: string, mustStart?: boolean);
     /** 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`
      *  to simulate a same-peer reconnect in tests. */
     connectWith(conn: RpcConnection, isPeerChanged?: boolean): void;
-    /** Start the reconnection loop — runs until disposed. */
-    run(wsFactory?: (url: string) => WebSocketLike): Promise<void>;
+    /** 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;
+    /** The reconnect loop itself. Exposed as `protected` so subclasses (and
+     *  `start()`) can drive it; public callers should use {@link start}. */
+    protected run(): Promise<void>;
+    private _runImpl;
     /**
      * Reconcile outbound calls after reconnection, then flush pending sends.
      *
@@ -1121,6 +1200,17 @@ declare class RpcStreamSender<T> implements IRpcObject {
     private _forceCloseIterator;
 }
 
+declare class RpcPeerRefBuilder {
+    /** 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: string, serializationFormat?: string): string;
+    /** Build a server peer ref from a peer id — returns `server://{id}`. */
+    static forServer(id: string): string;
+}
+
 /** Creates a typed RPC client proxy — intercepts method calls and sends them over RPC. */
 declare function createRpcClient<T extends object>(peer: RpcPeer, serviceDef: RpcServiceDef): T;
 
@@ -1154,8 +1244,7 @@ declare class RpcPeerStateMonitor {
     private _lastError;
     private _state;
     private _timer;
-    private _onConnected;
-    private _onDisconnected;
+    private _onConnectionStateChanged;
     private _onReconnectsAtChanged;
     private _onCancelDelaysChanged;
     constructor(peer: RpcClientPeer);
@@ -1186,4 +1275,4 @@ declare function xxh3_64str(input: string, seed?: bigint): bigint;
  */
 declare function computeMethodHash(methodName: string): number;
 
-export { ARG_DELIMITER, ENVELOPE_DELIMITER, FRAME_DELIMITER, type IRpcObject, IncreasingSeqCompressor, type MethodMeta, RPC_CLOSE_CODE_UNSUPPORTED_FORMAT, type RemoteHandshake, type RpcCallOptions, RpcCallStage, RpcCallTypeId, RpcClientPeer, RpcClientPeerReconnectDelayer, type RpcConnection, type RpcConnectionUrlResolver, type RpcDeserializedMessage, type RpcDispatchContext, RpcHub, RpcInboundCall, RpcInboundCallTracker, RpcJsonSerializationFormat, type RpcLogScope, type RpcMessage, RpcMessageChannelConnection, RpcMessagePackCompactSerializationFormat, RpcMessagePackSerializationFormat, type RpcMethodDef, type RpcMethodDefInput, RpcMethodRegistry, type RpcObjectId, RpcObjectKind, RpcOutboundCall, RpcOutboundCallTracker, RpcPeer, RpcPeerConnectionKind, type RpcPeerState, RpcPeerStateKind, RpcPeerStateMonitor, type RpcReceivedMessage, RpcRemoteExecutionMode, RpcRemoteObjectTracker, RpcSerializationFormat, RpcSerializationFormatResolver, RpcServerPeer, type RpcServiceDef, RpcServiceHost, type RpcServiceImpl, RpcSharedObjectTracker, RpcStream, type RpcStreamOptions, type RpcStreamRef, RpcStreamSender, type RpcStreamSource, RpcSystemCallHandler, RpcSystemCallSender, RpcSystemCalls, RpcType, RpcWebSocketConnection, type RpcWireData, type ServiceMeta, type WebSocketLike, type WebSocketServer, WebSocketState, computeMethodHash, createBinaryEncoder, createMessageChannelPair, createRpcClient, defaultBinaryDecoder, defaultBinaryEncoder, defaultConnectionUrlResolver, defineRpcService, deserializeBinaryMessage, deserializeCompactBinaryMessage, deserializeMessage, getLogs, getMethodsMeta, getServiceMeta, getStateDescription, isConnected, likelyConnected, parseStreamRef, resolveStreamRefs, rpcMethod, rpcService, serializeBinaryFrame, serializeBinaryMessage, serializeCompactBinaryMessage, serializeFrame, serializeMessage, splitBinaryFrame, splitCompactBinaryFrame, splitFrame, wireMethodName, xxh3_64, xxh3_64str };
+export { ARG_DELIMITER, ENVELOPE_DELIMITER, FRAME_DELIMITER, HANDSHAKE_TIMEOUT_MS, type IRpcObject, IncreasingSeqCompressor, type MethodMeta, RPC_CLOSE_CODE_UNSUPPORTED_FORMAT, type RemoteHandshake, type RpcCallOptions, RpcCallStage, RpcCallTypeId, RpcClientPeer, RpcClientPeerReconnectDelayer, type RpcConnection, RpcConnectionState, type RpcConnectionUrlResolver, type RpcDeserializedMessage, type RpcDispatchContext, RpcHub, RpcInboundCall, RpcInboundCallTracker, RpcJsonSerializationFormat, type RpcLogScope, type RpcMessage, RpcMessageChannelConnection, RpcMessagePackCompactSerializationFormat, RpcMessagePackSerializationFormat, type RpcMethodDef, type RpcMethodDefInput, RpcMethodRegistry, type RpcObjectId, RpcObjectKind, RpcOutboundCall, RpcOutboundCallTracker, RpcPeer, type RpcPeerFactory, RpcPeerRefBuilder, type RpcPeerState, RpcPeerStateKind, RpcPeerStateMonitor, type RpcReceivedMessage, RpcRemoteExecutionMode, RpcRemoteObjectTracker, RpcSerializationFormat, RpcSerializationFormatResolver, RpcServerPeer, type RpcServiceDef, RpcServiceHost, type RpcServiceImpl, RpcSharedObjectTracker, RpcStream, type RpcStreamOptions, type RpcStreamRef, RpcStreamSender, type RpcStreamSource, RpcSystemCallHandler, RpcSystemCallSender, RpcSystemCalls, RpcType, RpcWebSocketConnection, type RpcWireData, type ServiceMeta, type WebSocketLike, type WebSocketServer, WebSocketState, computeMethodHash, createBinaryEncoder, createMessageChannelPair, createRpcClient, defaultBinaryDecoder, defaultBinaryEncoder, defaultConnectionUrlResolver, defineRpcService, deserializeBinaryMessage, deserializeCompactBinaryMessage, deserializeMessage, getLogs, getMethodsMeta, getServiceMeta, getStateDescription, isConnected, likelyConnected, parseStreamRef, resolveStreamRefs, rpcMethod, rpcService, serializeBinaryFrame, serializeBinaryMessage, serializeCompactBinaryMessage, serializeFrame, serializeMessage, splitBinaryFrame, splitCompactBinaryFrame, splitFrame, wireMethodName, xxh3_64, xxh3_64str };

package/dist/index.d.ts

@@ -638,6 +638,11 @@ declare class RpcSystemCallSender {
     ackEnd(conn: RpcConnection, format: RpcSerializationFormat, localId: number, hostId: string): void;
 }
 
+/** Factory signature shared by all peer lookup/creation methods. Serialization
+ *  format is encoded in the URL via `?f=...` (see {@link RpcPeerRefBuilder}),
+ *  so the factory doesn't need an extra parameter for it. `getClientPeer` /
+ *  `getServerPeer` cast the result, so the factory returns RpcPeer. */
+type RpcPeerFactory = (hub: RpcHub, ref: string) => RpcPeer;
 /** Central RPC coordinator — manages peers, services, and configuration. */
 declare class RpcHub {
     readonly hubId: string;
@@ -648,15 +653,37 @@ declare class RpcHub {
     /** Method registry for compact format hash ↔ name resolution.
      *  Created lazily, populated by addService/addClient. */
     readonly registry: 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: RpcClientPeerReconnectDelayer;
+    /** URL used by {@link defaultPeer} to resolve / create the default client
+     *  peer. Must be set before the first {@link defaultPeer} access. */
+    defaultPeerUrl: string | undefined;
+    /** 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: RpcPeerFactory | undefined;
     constructor(hubId?: string);
+    /** Shortcut for the hub's default client peer. Fails if
+     *  {@link defaultPeerUrl} is not set. */
+    get defaultPeer(): RpcClientPeer;
+    /** 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: RpcPeer): void;
     removePeer(ref: string): void;
-    /** Get or create a peer by ref. Server peers have "server://" prefix, everything else is a client peer. */
-    getPeer(ref: string): RpcPeer;
-    /** Get or create a client peer for the given URL. */
-    getClientPeer(ref: string): RpcClientPeer;
-    /** Get or create a server peer for the given ref. */
-    getServerPeer(ref: string): RpcServerPeer;
+    /** 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: string, factory?: RpcPeerFactory): RpcPeer;
+    /** Get or create a client peer for the given URL. See {@link getPeer} for
+     *  the factory semantics. */
+    getClientPeer(ref: string, factory?: RpcPeerFactory): RpcClientPeer;
+    /** Get or create a server peer for the given ref. See {@link getPeer} for
+     *  the factory semantics. */
+    getServerPeer(ref: string, factory?: RpcPeerFactory): RpcServerPeer;
     /** Register a service with optional server method wrapping for custom call types. */
     addService(defOrContract: RpcServiceDef | (AnyConstructor), impl: RpcServiceImpl): void;
     /** Create a typed client proxy for a service on a remote peer. */
@@ -712,9 +739,13 @@ declare class RpcSharedObjectTracker {
 
 /** WebSocket close code sent by the server when the client's serialization format is unsupported. */
 declare const RPC_CLOSE_CODE_UNSUPPORTED_FORMAT = 4001;
+/** Maximum time to wait for the server's handshake response after opening the socket. */
+declare const HANDSHAKE_TIMEOUT_MS = 10000;
 /** Builds the WebSocket connection URL for an RpcClientPeer. */
 type RpcConnectionUrlResolver = (peer: RpcClientPeer) => string;
-/** Default connection URL provider — appends `clientId` and `f` query parameters. */
+/** Default connection URL provider — sets `clientId` and `f` query parameters,
+ *  replacing any existing values to keep the wire format consistent with the
+ *  peer's actual `serializationFormat`. */
 declare const defaultConnectionUrlResolver: RpcConnectionUrlResolver;
 /** Options for RpcPeer.call() — allows custom call types and cancellation. */
 interface RpcCallOptions {
@@ -736,36 +767,49 @@ interface RemoteHandshake {
 }
 /** Base class for RPC peers — handles bidirectional message dispatch. */
 declare abstract class RpcPeer {
+    readonly hub: RpcHub;
     /** Routing/addressing key — used as key in hub.peers (URL for clients, "server://{uuid}" for servers). */
     readonly ref: string;
     /** Auto-generated GUID — used in handshakes only. */
     readonly id: string;
-    protected _hub: RpcHub;
-    protected _connection: RpcConnection | undefined;
-    readonly outbound: RpcOutboundCallTracker;
-    readonly inbound: RpcInboundCallTracker;
+    readonly outboundCalls: RpcOutboundCallTracker;
+    readonly inboundCalls: RpcInboundCallTracker;
     readonly remoteObjects: RpcRemoteObjectTracker;
     readonly sharedObjects: RpcSharedObjectTracker;
-    readonly connected: EventHandlerSet<void>;
-    readonly disconnected: EventHandlerSet<{
-        code: number;
-        reason: string;
-    }>;
+    /** 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. */
+    readonly connectionStateChanged: EventHandlerSet<RpcConnectionState>;
+    protected _connection: RpcConnection | undefined;
+    protected _connectionState: RpcConnectionState;
     protected _pendingSends: RpcOutboundCall[];
     private _keepAliveTimer;
-    constructor(ref: string, hub: RpcHub);
-    get hub(): RpcHub;
+    private _keepAliveWatchdog;
+    /** Wall-clock time of the last inbound `$sys.KeepAlive`, or 0 if none yet
+     *  for the current connection. Useful for diagnostics. */
+    private _lastKeepAliveAt;
+    /** Outbound keep-alive send period (per-peer override for tests). */
+    keepAlivePeriodMs: number;
+    /** Inbound keep-alive silence tolerance (per-peer override for tests). */
+    keepAliveTimeoutMs: number;
+    protected constructor(hub: RpcHub, ref: string);
     get connection(): RpcConnection | undefined;
+    get connectionState(): RpcConnectionState;
     get isConnected(): boolean;
+    protected _setConnectionState(value: RpcConnectionState): void;
+    /** Resolves on the next transition into `Connected` — or immediately if
+     *  already in that state. */
+    whenConnected(): Promise<void>;
     protected setupConnection(conn: RpcConnection): void;
     /**
      * The serialization format used by this peer for outgoing messages.
      * If not set explicitly, defaults to the resolver's default (JSON /
      * json5np). Subclasses can pre-assign in their constructor.
      */
-    private _format;
-    get format(): RpcSerializationFormat;
-    set format(value: RpcSerializationFormat);
+    private _serializationFormat;
+    get serializationFormat(): RpcSerializationFormat;
+    set serializationFormat(value: RpcSerializationFormat);
     call(method: string, args?: unknown[], options?: RpcCallOptions): RpcOutboundCall;
     callNoWait(method: string, args?: unknown[]): void;
     close(): void;
@@ -777,11 +821,22 @@ declare abstract class RpcPeer {
     protected _onHandshakeReceived(_handshake: RemoteHandshake): void;
     private _handleMessage;
     private _handleInbound;
-    private _startKeepAlive;
-    private _stopKeepAlive;
+    /** 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. */
+    private _armKeepAliveWatchdog;
+    /** Stop sending keep-alives and clear the silence watchdog. Called when
+     *  the peer transitions into `Disconnected`. */
+    private _disarmKeepAliveWatchdog;
+    /** Called by `RpcSystemCallHandler` when a `$sys.KeepAlive` message
+     *  arrives — records the timestamp and re-arms the silence watchdog. */
+    notifyKeepAliveReceived(): void;
 }
 /** Connection state for RpcClientPeer. */
-declare const enum RpcPeerConnectionKind {
+declare const enum RpcConnectionState {
     Disconnected = 0,
     Connecting = 1,
     Connected = 2
@@ -789,7 +844,6 @@ declare const enum RpcPeerConnectionKind {
 /** Client-side RPC peer — initiates WebSocket connection. ref = URL. */
 declare class RpcClientPeer extends RpcPeer {
     private _disposed;
-    private _connectionKind;
     private _tryIndex;
     private _handshakeIndex;
     /** Index from the MOST RECENTLY RECEIVED server handshake — sent back
@@ -803,33 +857,58 @@ declare class RpcClientPeer extends RpcPeer {
     private _reconnectsAt;
     /** Base64url-encoded peer ID — matches .NET's RpcClientPeer.ClientId (Guid.ToBase64Url). */
     readonly clientId: string;
-    /**
-     * 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.
-     */
-    readonly serializationFormat: string;
     /** Builds the WebSocket URL for this peer. Replace to customize URL construction. */
     connectionUrlResolver: RpcConnectionUrlResolver;
+    /** 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: ((url: string) => WebSocketLike) | undefined;
+    /** Max time to wait for the server's handshake response before aborting
+     *  the connection attempt. Mirrors .NET's `Hub.Limits.HandshakeTimeout`. */
+    handshakeTimeoutMs: number;
     readonly peerChanged: EventHandlerSet<void>;
     /** Fired when the server rejects the connection due to an unsupported serialization format (close code 4010). */
     readonly unsupportedFormat: EventHandlerSet<{
         reason: string;
     }>;
-    readonly reconnectDelayer: RpcClientPeerReconnectDelayer;
     readonly reconnectsAtChanged: EventHandlerSet<void>;
     get reconnectsAt(): number;
     private _setReconnectsAt;
-    constructor(hub: RpcHub, url: string, serializationFormat?: string);
-    get connectionKind(): RpcPeerConnectionKind;
+    /** The promise returned by the reconnect loop. `undefined` until
+     *  `start()` is invoked (which happens automatically when
+     *  `mustStart = true` is passed to the ctor). */
+    whenRunning: Promise<void> | undefined;
+    /**
+     * @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: RpcHub, url: string, mustStart?: boolean);
     /** 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`
      *  to simulate a same-peer reconnect in tests. */
     connectWith(conn: RpcConnection, isPeerChanged?: boolean): void;
-    /** Start the reconnection loop — runs until disposed. */
-    run(wsFactory?: (url: string) => WebSocketLike): Promise<void>;
+    /** 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;
+    /** The reconnect loop itself. Exposed as `protected` so subclasses (and
+     *  `start()`) can drive it; public callers should use {@link start}. */
+    protected run(): Promise<void>;
+    private _runImpl;
     /**
      * Reconcile outbound calls after reconnection, then flush pending sends.
      *
@@ -1121,6 +1200,17 @@ declare class RpcStreamSender<T> implements IRpcObject {
     private _forceCloseIterator;
 }
 
+declare class RpcPeerRefBuilder {
+    /** 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: string, serializationFormat?: string): string;
+    /** Build a server peer ref from a peer id — returns `server://{id}`. */
+    static forServer(id: string): string;
+}
+
 /** Creates a typed RPC client proxy — intercepts method calls and sends them over RPC. */
 declare function createRpcClient<T extends object>(peer: RpcPeer, serviceDef: RpcServiceDef): T;
 
@@ -1154,8 +1244,7 @@ declare class RpcPeerStateMonitor {
     private _lastError;
     private _state;
     private _timer;
-    private _onConnected;
-    private _onDisconnected;
+    private _onConnectionStateChanged;
     private _onReconnectsAtChanged;
     private _onCancelDelaysChanged;
     constructor(peer: RpcClientPeer);
@@ -1186,4 +1275,4 @@ declare function xxh3_64str(input: string, seed?: bigint): bigint;
  */
 declare function computeMethodHash(methodName: string): number;
 
-export { ARG_DELIMITER, ENVELOPE_DELIMITER, FRAME_DELIMITER, type IRpcObject, IncreasingSeqCompressor, type MethodMeta, RPC_CLOSE_CODE_UNSUPPORTED_FORMAT, type RemoteHandshake, type RpcCallOptions, RpcCallStage, RpcCallTypeId, RpcClientPeer, RpcClientPeerReconnectDelayer, type RpcConnection, type RpcConnectionUrlResolver, type RpcDeserializedMessage, type RpcDispatchContext, RpcHub, RpcInboundCall, RpcInboundCallTracker, RpcJsonSerializationFormat, type RpcLogScope, type RpcMessage, RpcMessageChannelConnection, RpcMessagePackCompactSerializationFormat, RpcMessagePackSerializationFormat, type RpcMethodDef, type RpcMethodDefInput, RpcMethodRegistry, type RpcObjectId, RpcObjectKind, RpcOutboundCall, RpcOutboundCallTracker, RpcPeer, RpcPeerConnectionKind, type RpcPeerState, RpcPeerStateKind, RpcPeerStateMonitor, type RpcReceivedMessage, RpcRemoteExecutionMode, RpcRemoteObjectTracker, RpcSerializationFormat, RpcSerializationFormatResolver, RpcServerPeer, type RpcServiceDef, RpcServiceHost, type RpcServiceImpl, RpcSharedObjectTracker, RpcStream, type RpcStreamOptions, type RpcStreamRef, RpcStreamSender, type RpcStreamSource, RpcSystemCallHandler, RpcSystemCallSender, RpcSystemCalls, RpcType, RpcWebSocketConnection, type RpcWireData, type ServiceMeta, type WebSocketLike, type WebSocketServer, WebSocketState, computeMethodHash, createBinaryEncoder, createMessageChannelPair, createRpcClient, defaultBinaryDecoder, defaultBinaryEncoder, defaultConnectionUrlResolver, defineRpcService, deserializeBinaryMessage, deserializeCompactBinaryMessage, deserializeMessage, getLogs, getMethodsMeta, getServiceMeta, getStateDescription, isConnected, likelyConnected, parseStreamRef, resolveStreamRefs, rpcMethod, rpcService, serializeBinaryFrame, serializeBinaryMessage, serializeCompactBinaryMessage, serializeFrame, serializeMessage, splitBinaryFrame, splitCompactBinaryFrame, splitFrame, wireMethodName, xxh3_64, xxh3_64str };
+export { ARG_DELIMITER, ENVELOPE_DELIMITER, FRAME_DELIMITER, HANDSHAKE_TIMEOUT_MS, type IRpcObject, IncreasingSeqCompressor, type MethodMeta, RPC_CLOSE_CODE_UNSUPPORTED_FORMAT, type RemoteHandshake, type RpcCallOptions, RpcCallStage, RpcCallTypeId, RpcClientPeer, RpcClientPeerReconnectDelayer, type RpcConnection, RpcConnectionState, type RpcConnectionUrlResolver, type RpcDeserializedMessage, type RpcDispatchContext, RpcHub, RpcInboundCall, RpcInboundCallTracker, RpcJsonSerializationFormat, type RpcLogScope, type RpcMessage, RpcMessageChannelConnection, RpcMessagePackCompactSerializationFormat, RpcMessagePackSerializationFormat, type RpcMethodDef, type RpcMethodDefInput, RpcMethodRegistry, type RpcObjectId, RpcObjectKind, RpcOutboundCall, RpcOutboundCallTracker, RpcPeer, type RpcPeerFactory, RpcPeerRefBuilder, type RpcPeerState, RpcPeerStateKind, RpcPeerStateMonitor, type RpcReceivedMessage, RpcRemoteExecutionMode, RpcRemoteObjectTracker, RpcSerializationFormat, RpcSerializationFormatResolver, RpcServerPeer, type RpcServiceDef, RpcServiceHost, type RpcServiceImpl, RpcSharedObjectTracker, RpcStream, type RpcStreamOptions, type RpcStreamRef, RpcStreamSender, type RpcStreamSource, RpcSystemCallHandler, RpcSystemCallSender, RpcSystemCalls, RpcType, RpcWebSocketConnection, type RpcWireData, type ServiceMeta, type WebSocketLike, type WebSocketServer, WebSocketState, computeMethodHash, createBinaryEncoder, createMessageChannelPair, createRpcClient, defaultBinaryDecoder, defaultBinaryEncoder, defaultConnectionUrlResolver, defineRpcService, deserializeBinaryMessage, deserializeCompactBinaryMessage, deserializeMessage, getLogs, getMethodsMeta, getServiceMeta, getStateDescription, isConnected, likelyConnected, parseStreamRef, resolveStreamRefs, rpcMethod, rpcService, serializeBinaryFrame, serializeBinaryMessage, serializeCompactBinaryMessage, serializeFrame, serializeMessage, splitBinaryFrame, splitCompactBinaryFrame, splitFrame, wireMethodName, xxh3_64, xxh3_64str };