@actuallab/rpc 12.3.14 → 12.3.31

package/dist/index.d.cts

@@ -1,5 +1,9 @@
-import { Encoder, Decoder } from '@msgpack/msgpack';
+import * as _actuallab_core from '@actuallab/core';
 import { EventHandlerSet, PromiseSource, RetryDelayer } from '@actuallab/core';
+import { Encoder, Decoder } from '@msgpack/msgpack';
+
+type RpcLogScope = 'RpcCallTracker' | 'RpcClient' | 'RpcClientPeerReconnectDelayer' | 'RpcConnection' | 'RpcHub' | 'RpcInterceptor' | 'RpcMessageChannelConnection' | 'RpcMethodRegistry' | 'RpcOutboundCall' | 'RpcPeer' | 'RpcPeerStateMonitor' | 'RpcRemoteObjectTracker' | 'RpcSerialization' | 'RpcServiceHost' | 'RpcSharedObjectTracker' | 'RpcSharedStream' | 'RpcStream' | 'RpcStreamSender' | 'RpcSystemCallHandler' | 'RpcSystemCallSender' | 'RpcWebSocketClient';
+declare const getLogs: (scope: RpcLogScope) => _actuallab_core.LogScopeFns;
 
 /** Identifies the type of an RPC call on the wire. */
 declare const enum RpcCallTypeId {
@@ -440,7 +444,26 @@ declare class RpcOutboundCall {
     readonly removeOnOk: boolean;
     /** The serialized wire data — stored for re-sending on reconnect. */
     serializedWireData: string | Uint8Array;
+    /**
+     * Bitfield of {@link RpcCallStage} flags indicating how far this call
+     * has progressed. Used by the `$sys.Reconnect` protocol to tell the
+     * remote peer which calls are still pending its attention.
+     *
+     * - 0: brand new, no result yet (the peer is expected to be actively processing).
+     * - `ResultReady` (1): `$sys.Ok` received for this call.
+     * - `Invalidated` (3): result was invalidated (compute calls only).
+     * - `Unregistered` (0x1000): removed from the tracker.
+     */
+    completedStage: number;
     constructor(callId: number, method: string, remoteExecutionMode?: number);
+    /**
+     * Returns the stage to report to the remote peer via `$sys.Reconnect`,
+     * or `null` if this call should not be reconciled and must be aborted.
+     *
+     * Mirrors .NET `RpcOutboundCall.GetReconnectStage` at
+     * src/ActualLab.Rpc/Infrastructure/RpcOutboundCall.cs.
+     */
+    getReconnectStage(isPeerChanged: boolean): number | null;
     /** Called when the connection is lost. Subclasses can override to resolve invalidation promises. */
     onDisconnect(): void;
 }
@@ -479,6 +502,55 @@ declare class RpcInboundCallTracker {
     clear(): void;
 }
 
+/**
+ * Well-known RPC call completion stage constants, used by the
+ * `$sys.Reconnect` protocol to tell the peer which calls have already
+ * reached which stage and therefore don't need to be re-processed.
+ *
+ * Direct port of .NET `ActualLab.Rpc.Infrastructure.RpcCallStage` at
+ * src/ActualLab.Rpc/Infrastructure/RpcCallStage.cs.
+ */
+declare const RpcCallStage: {
+    /** The call's result has been received from the peer. */
+    readonly ResultReady: 1;
+    /** The compute call's result has been invalidated (compute-call specific). */
+    readonly Invalidated: 3;
+    /**
+     * Bit flag added on top of ResultReady/Invalidated when the outbound
+     * call has been removed from the tracker (unregistered).
+     */
+    readonly Unregistered: 4096;
+};
+type RpcCallStage = number;
+
+/**
+ * Compresses and decompresses monotonically increasing sequences of
+ * integers using variable-length LEB128 encoding of successive deltas.
+ *
+ * Wire-compatible with .NET `ActualLab.Rpc.Internal.IncreasingSeqCompressor`
+ * (src/ActualLab.Rpc/Internal/IncreasingSeqCompressor.cs) — which
+ * underlies the `$sys.Reconnect` protocol.
+ *
+ * Inputs MUST be sorted non-decreasing. Maximum supported value is
+ * 2^53 - 1 (JavaScript `Number` safe-integer limit); call IDs in TS
+ * never exceed this because they're generated from a 32-bit counter.
+ */
+declare const IncreasingSeqCompressor: {
+    /**
+     * Serialize a non-decreasing sequence of non-negative integers as
+     * LEB128-encoded deltas.
+     *
+     * Throws `RangeError` if the input is not monotonically non-decreasing,
+     * or if a value exceeds `Number.MAX_SAFE_INTEGER`.
+     */
+    readonly serialize: (values: Iterable<number>) => Uint8Array;
+    /**
+     * Decode bytes produced by {@link serialize} back into the original
+     * sorted sequence of non-negative integers.
+     */
+    readonly deserialize: (data: Uint8Array) => number[];
+};
+
 declare class RpcClientPeerReconnectDelayer extends RetryDelayer {
     constructor();
 }
@@ -686,8 +758,14 @@ declare abstract class RpcPeer {
     get connection(): RpcConnection | undefined;
     get isConnected(): boolean;
     protected setupConnection(conn: RpcConnection): void;
-    /** The serialization format used by this peer. Override in subclasses. */
+    /**
+     * 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);
     call(method: string, args?: unknown[], options?: RpcCallOptions): RpcOutboundCall;
     callNoWait(method: string, args?: unknown[]): void;
     close(): void;
@@ -714,6 +792,12 @@ declare class RpcClientPeer extends RpcPeer {
     private _connectionKind;
     private _tryIndex;
     private _handshakeIndex;
+    /** Index from the MOST RECENTLY RECEIVED server handshake — sent back
+     *  to the server in `$sys.Reconnect:3` so the server can verify we're
+     *  talking about the current connection. Mirrors .NET's
+     *  `connectionState.Handshake.Index` path in
+     *  `RpcOutboundCallTracker.TryReconnect`. */
+    private _remoteHandshakeIndex;
     private _lastRemoteHubId;
     private _pendingHandshake;
     private _reconnectsAt;
@@ -736,22 +820,50 @@ declare class RpcClientPeer extends RpcPeer {
     readonly reconnectsAtChanged: EventHandlerSet<void>;
     get reconnectsAt(): number;
     private _setReconnectsAt;
-    private _format;
     constructor(hub: RpcHub, url: string, serializationFormat?: string);
-    get format(): RpcSerializationFormat;
     get connectionKind(): RpcPeerConnectionKind;
-    /** One-shot connection for tests — no reconnection loop, no handshake. */
-    connectWith(conn: RpcConnection): void;
+    /** One-shot connection for tests — no reconnection loop, no handshake.
+     *  @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>;
-    /** Re-send outbound calls after reconnection + flush pending sends.
-     *  Stage-3 compute calls are always self-invalidated: without $sys.Reconnect
-     *  protocol, the server's invalidation tracking is lost on disconnect, and
-     *  re-sending would get a duplicate $sys.Ok that is ignored (PromiseSource
-     *  already resolved). Self-invalidation forces a fresh recompute that
-     *  establishes new invalidation tracking on the new connection.
-     *  Regular in-flight calls are re-sent transparently. */
+    /**
+     * Reconcile outbound calls after reconnection, then flush pending sends.
+     *
+     * On peer change (different server hubId) or with binary wire format —
+     * we blind-resend every eligible call.
+     *
+     * On a same-peer reconnect with JSON transport, first call
+     * `$sys.Reconnect` to ask the server which call IDs it no longer
+     * recognizes (e.g. inbound tracker was cleared, or the call never
+     * reached the server). Only those get resent; the rest stay in the
+     * tracker awaiting their $sys.Ok. This prevents duplicate server-side
+     * invocation of in-flight streaming calls on every transient
+     * reconnect — mirrors .NET `RpcOutboundCallTracker.Reconnect` at
+     * src/ActualLab.Rpc/Infrastructure/RpcCallTrackers.cs:209-279.
+     *
+     * Stage-3 compute calls (result already resolved, awaiting invalidation)
+     * are always self-invalidated — TS doesn't track compute-call stages
+     * across reconnect, so the safest behavior is to force a fresh compute.
+     */
     private _reconnect;
+    /**
+     * Ask the server which call IDs in `eligible` it no longer recognizes
+     * via `$sys.Reconnect:3`. Returns the set of call IDs that need to be
+     * resent. On any failure, falls back to "resend everything".
+     *
+     * Wire format of the `completedStages` argument is chosen per wire format:
+     *   - JSON (json5np): plain object `{"<stage>": "<base64-of-bytes>"}` —
+     *     matches .NET `System.Text.Json`'s default for `Dictionary<int, byte[]>`.
+     *   - MessagePack (msgpack6/msgpack6c): `Map<number, Uint8Array>` —
+     *     the patched encoder (see `./msgpack-map-patch.ts`) writes this as a
+     *     native msgpack `map<int, bin>`, matching .NET MessagePack-CSharp's
+     *     default for `Dictionary<int, byte[]>`.
+     */
+    private _reconcileReconnect;
     protected _onHandshakeReceived(handshake: RemoteHandshake): void;
     close(): void;
 }
@@ -766,6 +878,18 @@ declare class RpcServerPeer extends RpcPeer {
 /** Handles incoming system call messages — class-based equivalent of the former standalone function. */
 declare class RpcSystemCallHandler {
     handle(message: RpcMessage, args: unknown[], peer: RpcPeer): void;
+    /**
+     * Server-side handler for the `$sys.Reconnect` call. Parses the peer's
+     * report of in-flight call IDs (grouped by stage, IncreasingSeqCompressor-
+     * encoded, base64-wrapped for JSON transport), computes the subset this
+     * peer does not recognize, and replies with a compressed byte[] of the
+     * unknown IDs wrapped in `$sys.Ok`.
+     *
+     * @param relatedId The outbound call ID the client used for this
+     *                  `$sys.Reconnect` invocation — we send `$sys.Ok` back
+     *                  with the same `RelatedId`.
+     */
+    private _handleReconnect;
 }
 
 /** Parsed stream reference from the server's result payload. */
@@ -810,6 +934,15 @@ declare function parseStreamRef(value: unknown): RpcStreamRef | null;
  * This mirrors the .NET RpcStream<T> design where the same type serves both roles.
  */
 declare class RpcStream<T> implements AsyncIterable<T>, IRpcObject {
+    /**
+     * Grace period (ms) given to a factory-form local source to honor its
+     * AbortSignal and exit naturally before the sender force-closes the
+     * iterator via `iterator.return()`.
+     *
+     * Only applies to sources provided as `(abortSignal) => AsyncIterable<T>`.
+     * Plain `AsyncIterable<T>` sources are force-closed immediately on disconnect.
+     */
+    static disconnectGracePeriodMs: number;
     readonly id: RpcObjectId;
     readonly kind: RpcObjectKind;
     readonly allowReconnect: boolean;
@@ -887,6 +1020,17 @@ declare function resolveStreamRefs(value: unknown, peer: RpcPeer): unknown;
  * - Client acks every ackPeriod items for flow control
  * - Server sends End to signal completion (with optional error)
  * - Client sends AckEnd to acknowledge completion
+ *
+ * The pump is ACK-driven: the main loop blocks on `_whenAckReady` until a
+ * client ACK is queued, processes it (updating `_lastAckedIndex`, rewinding
+ * `_index` on mustReset, trimming the replay buffer), then sends items up
+ * to `ack.nextIndex + ackAdvance`. While the peer is disconnected no ACKs
+ * arrive, so the source is never pulled — the sender naturally pauses
+ * instead of spinning.
+ *
+ * Direct port of .NET `RpcSharedStream<T>` at
+ * src/ActualLab.Rpc/Infrastructure/RpcSharedStream.cs — including the
+ * separate non-real-time / real-time pump variants.
  */
 declare class RpcStreamSender<T> implements IRpcObject {
     private static readonly _emptyGuid;
@@ -898,43 +1042,83 @@ declare class RpcStreamSender<T> implements IRpcObject {
     readonly peer: RpcPeer;
     readonly ackPeriod: number;
     readonly ackAdvance: number;
+    /**
+     * If true, the source was produced by a factory `(abortSignal) => AsyncIterable<T>`
+     * and may honor the AbortSignal to exit gracefully. `disconnect()` first aborts
+     * the signal and gives the source up to `RpcStream.disconnectGracePeriodMs` ms
+     * before force-closing via `iterator.return()`.
+     *
+     * If false, the source is a plain AsyncIterable that cannot observe the signal,
+     * so `disconnect()` force-closes immediately.
+     */
+    readonly sourceUsesAbortSignal: boolean;
+    /** Next stream index that will be sent (matches .NET's `index`). */
     private _nextIndex;
     private _ended;
     private _started;
+    /** Highest `nextIndex` observed in an ACK so far (matches .NET's `lastAckNextIndex` idiom). */
     private _lastAckedIndex;
-    private _ackWaiting;
-    private _resetRequested;
     private _abortController;
     private _iterator;
-    constructor(peer: RpcPeer, ackPeriod?: number, ackAdvance?: number, allowReconnect?: boolean, isRealTime?: boolean, canSkipTo?: (item: T) => boolean);
+    private _acks;
+    private _whenAckReady;
+    constructor(peer: RpcPeer, ackPeriod?: number, ackAdvance?: number, allowReconnect?: boolean, isRealTime?: boolean, canSkipTo?: (item: T) => boolean, sourceUsesAbortSignal?: boolean);
     /** AbortSignal that is aborted when the sender is disconnected. */
     get abortSignal(): AbortSignal;
     /** Returns the stream reference string for the $sys.Ok response. */
     toRef(): string;
-    /** Called by system call handler when $sys.Ack is received from the client. */
+    /**
+     * Called by system call handler when $sys.Ack is received from the client.
+     *
+     * Mirrors .NET `RpcSharedStream<T>.OnAck` at
+     * src/ActualLab.Rpc/Infrastructure/RpcSharedStream.cs:68-101.
+     */
     onAck(nextIndex: number, hostId: string): void;
     /** Called by system call handler when $sys.AckEnd is received from the client. */
     onAckEnd(_hostId: string): void;
-    /** Send a single item to the client. */
+    /**
+     * Send a single item to the client at the current `_nextIndex`.
+     *
+     * Advances `_nextIndex` unconditionally — even if the peer is disconnected
+     * the item is considered "sent" from the pump's perspective so the replay
+     * buffer indexing stays consistent. If a connection is absent, the wire
+     * message is dropped; the item will be resent from the replay buffer
+     * after a reconnect (client sends `Ack(N, mustReset=true)`).
+     */
     sendItem(item: T): void;
-    /** Send a batch of items to the client. */
+    /** Send a batch of items to the client. See {@link sendItem} for disconnect semantics. */
     sendBatch(items: T[]): void;
     /** Signal stream completion to the client. */
     sendEnd(error?: Error | null): void;
     /**
      * Consume an AsyncIterable and send all items to the client.
-     * Waits for the client's initial Ack before starting to pump items.
      *
-     * When `isRealTime` is true, applies flow control based on `ackAdvance`:
-     * if the sender is `ackAdvance` items ahead of the last ACK, it enters
-     * skip mode — draining the source and discarding items until it finds
-     * one where `canSkipTo` returns true.
+     * Dispatches to the non-real-time or real-time pump, matching .NET
+     * `RpcSharedStream<T>.OnRun` at
+     * src/ActualLab.Rpc/Infrastructure/RpcSharedStream.cs:105-108.
      */
     writeFrom(source: AsyncIterable<T>): Promise<void>;
-    /** Wait until _nextIndex < _lastAckedIndex + ackAdvance. */
-    private _waitForAckBudget;
+    /**
+     * Non-real-time pump — back-pressure through buffered ACKs.
+     *
+     * Direct port of .NET `OnRunNonRealTime` at
+     * src/ActualLab.Rpc/Infrastructure/RpcSharedStream.cs:110-217.
+     */
+    private _runNonRealTime;
+    /**
+     * Real-time pump — drops stale items to stay close to the source's head.
+     *
+     * Direct port of .NET `OnRunRealTime` at
+     * src/ActualLab.Rpc/Infrastructure/RpcSharedStream.cs:219-420.
+     */
+    private _runRealTime;
+    /** Drain all queued ACKs, returning the most recent one (or null if none). */
+    private _tryProcessAcks;
+    /** Wait for the ACK queue to have at least one entry (or `_ended`). */
+    private _waitAckReady;
     reconnect(): void;
     disconnect(): void;
+    private _forceCloseIterator;
 }
 
 /** Creates a typed RPC client proxy — intercepts method calls and sends them over RPC. */
@@ -1002,4 +1186,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, type MethodMeta, RPC_CLOSE_CODE_UNSUPPORTED_FORMAT, type RemoteHandshake, type RpcCallOptions, RpcCallTypeId, RpcClientPeer, RpcClientPeerReconnectDelayer, type RpcConnection, type RpcConnectionUrlResolver, type RpcDeserializedMessage, type RpcDispatchContext, RpcHub, RpcInboundCall, RpcInboundCallTracker, RpcJsonSerializationFormat, 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, 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, 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 };