@actuallab/rpc 12.4.9 → 13.0.4

package/dist/index.d.cts

@@ -23,6 +23,7 @@ declare const RpcSystemCalls: {
     readonly item: "$sys.I:2";
     readonly batch: "$sys.B:2";
     readonly end: "$sys.End:2";
+    readonly disconnect: "$sys.Disconnect:1";
 };
 /** Wire-format RPC message envelope. */
 interface RpcMessage {
@@ -788,16 +789,14 @@ declare abstract class RpcPeer {
      *  entered only after the handshake has succeeded. */
     readonly connectionStateChanged: EventHandlerSet<RpcConnectionState>;
     protected _connection: RpcConnection | undefined;
-    /** Mirror of `_connectionState === Connected` — true only after the
-     *  handshake round-trip completes. Kept as its own field (rather than
-     *  derived from `_connection`) so outbound calls can be gated on
-     *  handshake completion, not merely WS-open: previously the run loop
-     *  nulled `_connection` during the handshake window to suppress calls,
-     *  which made `close()` a silent no-op and left a zombie peer when the
-     *  hub removed it mid-handshake. */
+    /** Mirror of `_connectionState === Connected`. True only after the
+     *  handshake round-trip completes; outbound `call()` checks this to
+     *  decide between sending now and deferring until the next `Connected`
+     *  transition. Kept as its own field so it can stay false through the
+     *  Handshaking phase without exposing the run loop's `_connection`
+     *  bookkeeping. */
     protected _isConnected: boolean;
     protected _connectionState: RpcConnectionState;
-    protected _pendingSends: RpcOutboundCall[];
     private _keepAliveTimer;
     private _keepAliveWatchdog;
     /** Wall-clock time of the last inbound `$sys.KeepAlive`, or 0 if none yet
@@ -832,8 +831,6 @@ declare abstract class RpcPeer {
      *  stays in the hub and all client proxies bound to it remain valid. */
     disconnect(): void;
     close(): void;
-    /** Send any messages buffered while disconnected. Call after connection + handshake are ready. */
-    protected _flushPendingSends(): void;
     /** Send pre-serialized wire data through the current connection. */
     protected _sendWireData(data: string | Uint8Array): void;
     /** Override in subclasses to handle the remote peer's handshake response. */
@@ -854,11 +851,16 @@ declare abstract class RpcPeer {
      *  arrives — records the timestamp and re-arms the silence watchdog. */
     notifyKeepAliveReceived(): void;
 }
-/** Connection state for RpcClientPeer. */
+/** Connection state for RpcPeer. Mirrors .NET `RpcPeerConnectionState`'s
+ *  observable phases: the transport is `Connecting` until the WebSocket
+ *  opens, `Handshaking` from WS-open until the server's handshake reply
+ *  arrives, and `Connected` once the handshake completes. Outbound calls
+ *  are gated on `Connected`. */
 declare const enum RpcConnectionState {
     Disconnected = 0,
     Connecting = 1,
-    Connected = 2
+    Handshaking = 2,
+    Connected = 3
 }
 /** Client-side RPC peer — initiates WebSocket connection. ref = URL. */
 declare class RpcClientPeer extends RpcPeer {
@@ -1002,12 +1004,17 @@ declare class RpcSystemCallHandler {
  * - 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 + bufferSize`. While the peer is disconnected no ACKs
- * arrive, so the source is never pulled — the sender naturally pauses
- * instead of spinning.
+ * The sender uses a single ACK-driven loop:
+ *  - On each ACK, drain the source synchronously into the ring buffer up to
+ *    `effectiveBufferSize` (this lets us pre-buffer past `ackAdvance`).
+ *  - For real-time, optionally compact the unsent suffix to the latest
+ *    buffered `canSkipTo` item.
+ *  - Send items up to the `ackAdvance` flow-control window.
+ *  - Wait for the next ACK.
+ *
+ * Setting `bufferSize > ackAdvance` lets the sender pre-buffer items past
+ * the in-flight window so a fresh ACK can be served from RAM instead of
+ * waiting on the source.
  *
  * Direct port of .NET `RpcSharedStream<T>` at
  * src/ActualLab.Rpc/Infrastructure/RpcSharedStream.cs.
@@ -1021,6 +1028,18 @@ declare class RpcStreamSender<T> implements IRpcObject {
     readonly canSkipTo: (item: T) => boolean;
     readonly peer: RpcPeer;
     readonly ackPeriod: number;
+    /**
+     * Wire-level flow-control window: the maximum index the sender may
+     * advance past the most recently acknowledged index. Mirrors .NET
+     * `RpcStream.AckAdvance`.
+     */
+    readonly ackAdvance: number;
+    /**
+     * Effective local ring buffer capacity used by the pump. Set larger
+     * than `ackAdvance` to pre-buffer items beyond the in-flight window;
+     * values below `ackAdvance` are clamped up (with a warning) at
+     * construction time. Not transmitted on the wire.
+     */
     readonly bufferSize: number;
     /**
      * If true, the source was produced by a factory `(abortSignal) => AsyncIterable<T>`
@@ -1047,12 +1066,19 @@ declare class RpcStreamSender<T> implements IRpcObject {
      *  watchdog so it can distinguish "stuck" (no ACK > N s) from
      *  "throttled" (ACKs flowing). */
     onAckProcessed?: () => void;
+    /** Fires after each item is pushed onto the local ring buffer. The
+     *  argument is the buffer count *after* the push. Together with
+     *  `onAckProcessed` (which is the only place items leave the buffer),
+     *  this gives controllers a complete picture of buffer utilization.
+     *  When `bufferedCount === bufferSize`, the source pull is paused
+     *  until the next ACK frees space. Listener errors are swallowed. */
+    onBuffered?: (bufferedCount: number) => void;
     get nextIndex(): number;
     get lastAckIndex(): number;
     get skipCount(): number;
     private _acks;
     private _whenAckReady;
-    constructor(peer: RpcPeer, ackPeriod?: number, bufferSize?: number, allowReconnect?: boolean, isRealTime?: boolean, canSkipTo?: (item: T) => boolean, sourceUsesAbortSignal?: boolean);
+    constructor(peer: RpcPeer, ackPeriod?: number, ackAdvance?: number, allowReconnect?: boolean, isRealTime?: boolean, canSkipTo?: (item: T) => boolean, sourceUsesAbortSignal?: boolean, bufferSize?: number);
     /** AbortSignal that is aborted when the sender is disconnected. */
     get abortSignal(): AbortSignal;
     /** Returns the stream reference string for the $sys.Ok response. */
@@ -1089,8 +1115,10 @@ declare class RpcStreamSender<T> implements IRpcObject {
     writeFrom(source: AsyncIterable<T>): Promise<void>;
     /**
      * ACK-driven pump. Non-real-time streams apply normal backpressure at
-     * `bufferSize`; real-time streams may compact the already-buffered unsent
+     * `ackAdvance`; real-time streams may compact the already-buffered unsent
      * suffix to the latest buffered `canSkipTo` item after the consumer ACKs.
+     * With `bufferSize > ackAdvance` the local ring buffer holds more than the
+     * in-flight window — real-time mode uses the extra space to pre-buffer.
      */
     private _run;
     /** Drain all queued ACKs, returning the most recent one (or null if none). */
@@ -1107,7 +1135,7 @@ interface RpcStreamRef {
     readonly hostId: string;
     readonly localId: number;
     readonly ackPeriod: number;
-    readonly bufferSize: number;
+    readonly ackAdvance: number;
     readonly allowReconnect: boolean;
     readonly isRealTime: boolean;
 }
@@ -1121,13 +1149,24 @@ type RpcStreamSource<T> = AsyncIterable<T> | ((abortSignal: AbortSignal) => Asyn
 /** Configuration options for creating a local (origin-side) RpcStream. */
 interface RpcStreamOptions<T> {
     ackPeriod?: number;
+    /**
+     * Wire-level flow-control window: the maximum index the sender may advance
+     * past the last acknowledged index. Mirrors .NET `RpcStream.AckAdvance`.
+     */
+    ackAdvance?: number;
+    /**
+     * Local-only sender ring buffer capacity. When undefined (or smaller than
+     * `ackAdvance`), `ackAdvance` is used as the buffer size.
+     * Set this larger than `ackAdvance` to let the sender pre-buffer items
+     * beyond the in-flight window. Not transmitted on the wire.
+     */
     bufferSize?: number;
     allowReconnect?: boolean;
     isRealTime?: boolean;
     canSkipTo?: (item: T) => boolean;
 }
 /**
- * Parses a stream reference string of the form "{hostId},{localId},{ackPeriod},{bufferSize}".
+ * Parses a stream reference string of the form "{hostId},{localId},{ackPeriod},{ackAdvance}".
  * Returns null if the value is not a valid stream reference.
  */
 declare function parseStreamRef(value: unknown): RpcStreamRef | null;
@@ -1159,7 +1198,12 @@ declare class RpcStream<T> implements AsyncIterable<T>, IRpcObject {
     readonly isRealTime: boolean;
     readonly canSkipTo: (item: T) => boolean;
     readonly ackPeriod: number;
-    readonly bufferSize: number;
+    readonly ackAdvance: number;
+    /**
+     * Local-only ring buffer capacity hint for the sender. Undefined means
+     * "use ackAdvance as the buffer size". Not part of the wire ref.
+     */
+    readonly bufferSize?: number;
     readonly localSource?: RpcStreamSource<T>;
     readonly peer: RpcPeer;
     private _sender?;
@@ -1193,7 +1237,7 @@ declare class RpcStream<T> implements AsyncIterable<T>, IRpcObject {
      * stream reference.
      *
      * For binary peers the ref is a MessagePack-compatible object
-     * (`{ SerializedId, AckPeriod, BufferSize, AllowReconnect }`);
+     * (`{ SerializedId, AckPeriod, AckAdvance, AllowReconnect }`);
      * for text peers it is a comma-separated string.
      *
      * Can only be called once per stream.
@@ -1219,7 +1263,7 @@ declare class RpcStream<T> implements AsyncIterable<T>, IRpcObject {
  * Recursively walks a deserialized value and replaces any stream ref strings
  * with live RpcStream<unknown> instances registered on the given peer.
  * This handles nested stream refs inside complex return types (e.g. Table<T>
- * containing RpcStream<Row<T>> fields serialized as "{hostId},{localId},{ackPeriod},{bufferSize}").
+ * containing RpcStream<Row<T>> fields serialized as "{hostId},{localId},{ackPeriod},{ackAdvance}").
  */
 declare function resolveStreamRefs(value: unknown, peer: RpcPeer): unknown;
 

package/dist/index.d.ts

@@ -23,6 +23,7 @@ declare const RpcSystemCalls: {
     readonly item: "$sys.I:2";
     readonly batch: "$sys.B:2";
     readonly end: "$sys.End:2";
+    readonly disconnect: "$sys.Disconnect:1";
 };
 /** Wire-format RPC message envelope. */
 interface RpcMessage {
@@ -788,16 +789,14 @@ declare abstract class RpcPeer {
      *  entered only after the handshake has succeeded. */
     readonly connectionStateChanged: EventHandlerSet<RpcConnectionState>;
     protected _connection: RpcConnection | undefined;
-    /** Mirror of `_connectionState === Connected` — true only after the
-     *  handshake round-trip completes. Kept as its own field (rather than
-     *  derived from `_connection`) so outbound calls can be gated on
-     *  handshake completion, not merely WS-open: previously the run loop
-     *  nulled `_connection` during the handshake window to suppress calls,
-     *  which made `close()` a silent no-op and left a zombie peer when the
-     *  hub removed it mid-handshake. */
+    /** Mirror of `_connectionState === Connected`. True only after the
+     *  handshake round-trip completes; outbound `call()` checks this to
+     *  decide between sending now and deferring until the next `Connected`
+     *  transition. Kept as its own field so it can stay false through the
+     *  Handshaking phase without exposing the run loop's `_connection`
+     *  bookkeeping. */
     protected _isConnected: boolean;
     protected _connectionState: RpcConnectionState;
-    protected _pendingSends: RpcOutboundCall[];
     private _keepAliveTimer;
     private _keepAliveWatchdog;
     /** Wall-clock time of the last inbound `$sys.KeepAlive`, or 0 if none yet
@@ -832,8 +831,6 @@ declare abstract class RpcPeer {
      *  stays in the hub and all client proxies bound to it remain valid. */
     disconnect(): void;
     close(): void;
-    /** Send any messages buffered while disconnected. Call after connection + handshake are ready. */
-    protected _flushPendingSends(): void;
     /** Send pre-serialized wire data through the current connection. */
     protected _sendWireData(data: string | Uint8Array): void;
     /** Override in subclasses to handle the remote peer's handshake response. */
@@ -854,11 +851,16 @@ declare abstract class RpcPeer {
      *  arrives — records the timestamp and re-arms the silence watchdog. */
     notifyKeepAliveReceived(): void;
 }
-/** Connection state for RpcClientPeer. */
+/** Connection state for RpcPeer. Mirrors .NET `RpcPeerConnectionState`'s
+ *  observable phases: the transport is `Connecting` until the WebSocket
+ *  opens, `Handshaking` from WS-open until the server's handshake reply
+ *  arrives, and `Connected` once the handshake completes. Outbound calls
+ *  are gated on `Connected`. */
 declare const enum RpcConnectionState {
     Disconnected = 0,
     Connecting = 1,
-    Connected = 2
+    Handshaking = 2,
+    Connected = 3
 }
 /** Client-side RPC peer — initiates WebSocket connection. ref = URL. */
 declare class RpcClientPeer extends RpcPeer {
@@ -1002,12 +1004,17 @@ declare class RpcSystemCallHandler {
  * - 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 + bufferSize`. While the peer is disconnected no ACKs
- * arrive, so the source is never pulled — the sender naturally pauses
- * instead of spinning.
+ * The sender uses a single ACK-driven loop:
+ *  - On each ACK, drain the source synchronously into the ring buffer up to
+ *    `effectiveBufferSize` (this lets us pre-buffer past `ackAdvance`).
+ *  - For real-time, optionally compact the unsent suffix to the latest
+ *    buffered `canSkipTo` item.
+ *  - Send items up to the `ackAdvance` flow-control window.
+ *  - Wait for the next ACK.
+ *
+ * Setting `bufferSize > ackAdvance` lets the sender pre-buffer items past
+ * the in-flight window so a fresh ACK can be served from RAM instead of
+ * waiting on the source.
  *
  * Direct port of .NET `RpcSharedStream<T>` at
  * src/ActualLab.Rpc/Infrastructure/RpcSharedStream.cs.
@@ -1021,6 +1028,18 @@ declare class RpcStreamSender<T> implements IRpcObject {
     readonly canSkipTo: (item: T) => boolean;
     readonly peer: RpcPeer;
     readonly ackPeriod: number;
+    /**
+     * Wire-level flow-control window: the maximum index the sender may
+     * advance past the most recently acknowledged index. Mirrors .NET
+     * `RpcStream.AckAdvance`.
+     */
+    readonly ackAdvance: number;
+    /**
+     * Effective local ring buffer capacity used by the pump. Set larger
+     * than `ackAdvance` to pre-buffer items beyond the in-flight window;
+     * values below `ackAdvance` are clamped up (with a warning) at
+     * construction time. Not transmitted on the wire.
+     */
     readonly bufferSize: number;
     /**
      * If true, the source was produced by a factory `(abortSignal) => AsyncIterable<T>`
@@ -1047,12 +1066,19 @@ declare class RpcStreamSender<T> implements IRpcObject {
      *  watchdog so it can distinguish "stuck" (no ACK > N s) from
      *  "throttled" (ACKs flowing). */
     onAckProcessed?: () => void;
+    /** Fires after each item is pushed onto the local ring buffer. The
+     *  argument is the buffer count *after* the push. Together with
+     *  `onAckProcessed` (which is the only place items leave the buffer),
+     *  this gives controllers a complete picture of buffer utilization.
+     *  When `bufferedCount === bufferSize`, the source pull is paused
+     *  until the next ACK frees space. Listener errors are swallowed. */
+    onBuffered?: (bufferedCount: number) => void;
     get nextIndex(): number;
     get lastAckIndex(): number;
     get skipCount(): number;
     private _acks;
     private _whenAckReady;
-    constructor(peer: RpcPeer, ackPeriod?: number, bufferSize?: number, allowReconnect?: boolean, isRealTime?: boolean, canSkipTo?: (item: T) => boolean, sourceUsesAbortSignal?: boolean);
+    constructor(peer: RpcPeer, ackPeriod?: number, ackAdvance?: number, allowReconnect?: boolean, isRealTime?: boolean, canSkipTo?: (item: T) => boolean, sourceUsesAbortSignal?: boolean, bufferSize?: number);
     /** AbortSignal that is aborted when the sender is disconnected. */
     get abortSignal(): AbortSignal;
     /** Returns the stream reference string for the $sys.Ok response. */
@@ -1089,8 +1115,10 @@ declare class RpcStreamSender<T> implements IRpcObject {
     writeFrom(source: AsyncIterable<T>): Promise<void>;
     /**
      * ACK-driven pump. Non-real-time streams apply normal backpressure at
-     * `bufferSize`; real-time streams may compact the already-buffered unsent
+     * `ackAdvance`; real-time streams may compact the already-buffered unsent
      * suffix to the latest buffered `canSkipTo` item after the consumer ACKs.
+     * With `bufferSize > ackAdvance` the local ring buffer holds more than the
+     * in-flight window — real-time mode uses the extra space to pre-buffer.
      */
     private _run;
     /** Drain all queued ACKs, returning the most recent one (or null if none). */
@@ -1107,7 +1135,7 @@ interface RpcStreamRef {
     readonly hostId: string;
     readonly localId: number;
     readonly ackPeriod: number;
-    readonly bufferSize: number;
+    readonly ackAdvance: number;
     readonly allowReconnect: boolean;
     readonly isRealTime: boolean;
 }
@@ -1121,13 +1149,24 @@ type RpcStreamSource<T> = AsyncIterable<T> | ((abortSignal: AbortSignal) => Asyn
 /** Configuration options for creating a local (origin-side) RpcStream. */
 interface RpcStreamOptions<T> {
     ackPeriod?: number;
+    /**
+     * Wire-level flow-control window: the maximum index the sender may advance
+     * past the last acknowledged index. Mirrors .NET `RpcStream.AckAdvance`.
+     */
+    ackAdvance?: number;
+    /**
+     * Local-only sender ring buffer capacity. When undefined (or smaller than
+     * `ackAdvance`), `ackAdvance` is used as the buffer size.
+     * Set this larger than `ackAdvance` to let the sender pre-buffer items
+     * beyond the in-flight window. Not transmitted on the wire.
+     */
     bufferSize?: number;
     allowReconnect?: boolean;
     isRealTime?: boolean;
     canSkipTo?: (item: T) => boolean;
 }
 /**
- * Parses a stream reference string of the form "{hostId},{localId},{ackPeriod},{bufferSize}".
+ * Parses a stream reference string of the form "{hostId},{localId},{ackPeriod},{ackAdvance}".
  * Returns null if the value is not a valid stream reference.
  */
 declare function parseStreamRef(value: unknown): RpcStreamRef | null;
@@ -1159,7 +1198,12 @@ declare class RpcStream<T> implements AsyncIterable<T>, IRpcObject {
     readonly isRealTime: boolean;
     readonly canSkipTo: (item: T) => boolean;
     readonly ackPeriod: number;
-    readonly bufferSize: number;
+    readonly ackAdvance: number;
+    /**
+     * Local-only ring buffer capacity hint for the sender. Undefined means
+     * "use ackAdvance as the buffer size". Not part of the wire ref.
+     */
+    readonly bufferSize?: number;
     readonly localSource?: RpcStreamSource<T>;
     readonly peer: RpcPeer;
     private _sender?;
@@ -1193,7 +1237,7 @@ declare class RpcStream<T> implements AsyncIterable<T>, IRpcObject {
      * stream reference.
      *
      * For binary peers the ref is a MessagePack-compatible object
-     * (`{ SerializedId, AckPeriod, BufferSize, AllowReconnect }`);
+     * (`{ SerializedId, AckPeriod, AckAdvance, AllowReconnect }`);
      * for text peers it is a comma-separated string.
      *
      * Can only be called once per stream.
@@ -1219,7 +1263,7 @@ declare class RpcStream<T> implements AsyncIterable<T>, IRpcObject {
  * Recursively walks a deserialized value and replaces any stream ref strings
  * with live RpcStream<unknown> instances registered on the given peer.
  * This handles nested stream refs inside complex return types (e.g. Table<T>
- * containing RpcStream<Row<T>> fields serialized as "{hostId},{localId},{ackPeriod},{bufferSize}").
+ * containing RpcStream<Row<T>> fields serialized as "{hostId},{localId},{ackPeriod},{ackAdvance}").
  */
 declare function resolveStreamRefs(value: unknown, peer: RpcPeer): unknown;