@actuallab/rpc 12.4.9 → 12.5.2

package/dist/index.cjs

@@ -151,7 +151,8 @@ var RpcSystemCalls = {
   ackEnd: "$sys.AckEnd:1",
   item: "$sys.I:2",
   batch: "$sys.B:2",
-  end: "$sys.End:2"
+  end: "$sys.End:2",
+  disconnect: "$sys.Disconnect:1"
 };
 var ENVELOPE_DELIMITER = "\n";
 var ARG_DELIMITER = "";
@@ -976,7 +977,7 @@ var RpcObjectKind = { Local: 0, Remote: 1 };
 var import_core5 = require("@actuallab/core");
 var { warnLog: warnLog3 } = getLogs("RpcSharedStream");
 var DEFAULT_ACK_PERIOD = 256;
-var DEFAULT_BUFFER_SIZE = 128;
+var DEFAULT_ACK_ADVANCE = 128;
 var RpcStreamSender = class _RpcStreamSender {
   static _emptyGuid = "00000000-0000-0000-0000-000000000000";
   id;
@@ -986,6 +987,18 @@ var RpcStreamSender = class _RpcStreamSender {
   canSkipTo;
   peer;
   ackPeriod;
+  /**
+   * Wire-level flow-control window: the maximum index the sender may
+   * advance past the most recently acknowledged index. Mirrors .NET
+   * `RpcStream.AckAdvance`.
+   */
+  ackAdvance;
+  /**
+   * 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.
+   */
   bufferSize;
   /**
    * If true, the source was produced by a factory `(abortSignal) => AsyncIterable<T>`
@@ -1014,6 +1027,13 @@ var RpcStreamSender = class _RpcStreamSender {
    *  watchdog so it can distinguish "stuck" (no ACK > N s) from
    *  "throttled" (ACKs flowing). */
   onAckProcessed;
+  /** 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;
   get nextIndex() {
     return this._nextIndex;
   }
@@ -1026,7 +1046,7 @@ var RpcStreamSender = class _RpcStreamSender {
   // -- ACK queue (analog of .NET's Channel<(long, bool)>) --
   _acks = [];
   _whenAckReady = null;
-  constructor(peer, ackPeriod = DEFAULT_ACK_PERIOD, bufferSize = DEFAULT_BUFFER_SIZE, allowReconnect = true, isRealTime = false, canSkipTo = () => true, sourceUsesAbortSignal = false) {
+  constructor(peer, ackPeriod = DEFAULT_ACK_PERIOD, ackAdvance = DEFAULT_ACK_ADVANCE, allowReconnect = true, isRealTime = false, canSkipTo = () => true, sourceUsesAbortSignal = false, bufferSize) {
     const localId = peer.sharedObjects.nextId();
     this.id = { hostId: peer.hub.hubId, localId };
     this.allowReconnect = allowReconnect;
@@ -1034,8 +1054,13 @@ var RpcStreamSender = class _RpcStreamSender {
     this.canSkipTo = canSkipTo;
     this.peer = peer;
     this.ackPeriod = ackPeriod;
-    this.bufferSize = bufferSize;
+    this.ackAdvance = ackAdvance;
     this.sourceUsesAbortSignal = sourceUsesAbortSignal;
+    if (bufferSize !== void 0 && bufferSize !== 0 && bufferSize < ackAdvance)
+      warnLog3?.log(
+        `RpcStream bufferSize (${bufferSize}) is below ackAdvance (${ackAdvance}); using ackAdvance as buffer size.`
+      );
+    this.bufferSize = bufferSize !== void 0 && bufferSize >= ackAdvance ? bufferSize : ackAdvance;
   }
   /** AbortSignal that is aborted when the sender is disconnected. */
   get abortSignal() {
@@ -1043,7 +1068,7 @@ var RpcStreamSender = class _RpcStreamSender {
   }
   /** Returns the stream reference string for the $sys.Ok response. */
   toRef() {
-    return `${this.id.hostId},${this.id.localId},${this.ackPeriod},${this.bufferSize},${this.allowReconnect ? "1" : "0"},${this.isRealTime ? "1" : "0"}`;
+    return `${this.id.hostId},${this.id.localId},${this.ackPeriod},${this.ackAdvance},${this.allowReconnect ? "1" : "0"},${this.isRealTime ? "1" : "0"}`;
   }
   /**
    * Called by system call handler when $sys.Ack is received from the client.
@@ -1139,8 +1164,10 @@ var RpcStreamSender = class _RpcStreamSender {
   }
   /**
    * 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.
    */
   /* eslint-disable @typescript-eslint/no-unnecessary-condition -- _ended changes across awaits */
   async _run(iterator, state) {
@@ -1162,6 +1189,12 @@ var RpcStreamSender = class _RpcStreamSender {
         Promise.resolve(pending)
       ]);
     };
+    const fireBuffered = () => {
+      try {
+        this.onBuffered?.(buffer.count);
+      } catch {
+      }
+    };
     const bufferNext = async (onlyIfReady, prefetchNext) => {
       let r;
       try {
@@ -1179,6 +1212,7 @@ var RpcStreamSender = class _RpcStreamSender {
           if (prefetchNext)
             whenMovedNext = iterator.next();
         }
+        fireBuffered();
         return true;
       } catch (e) {
         whenMovedNext = null;
@@ -1188,6 +1222,7 @@ var RpcStreamSender = class _RpcStreamSender {
           kind: "error",
           error: e instanceof Error ? e : new Error(String(e))
         });
+        fireBuffered();
         return true;
       }
     };
@@ -1232,6 +1267,7 @@ var RpcStreamSender = class _RpcStreamSender {
             };
           }
           buffer.pushTail(item);
+          fireBuffered();
           if (accepted || isFullyBuffered) break;
         }
       }
@@ -1246,7 +1282,7 @@ var RpcStreamSender = class _RpcStreamSender {
         return;
       }
       let bufferIndex = this._nextIndex - bufferStart;
-      const maxIndex = ack.nextIndex + this.bufferSize;
+      const maxIndex = ack.nextIndex + this.ackAdvance;
       while (this._nextIndex < maxIndex) {
         if (this._ended) return;
         if (isRealTime) {
@@ -1380,7 +1416,7 @@ function _compactBufferedUnsentSuffix(buffer, firstUnsentIndex, canSkipTo) {
 // src/rpc-stream.ts
 var { warnLog: warnLog4 } = getLogs("RpcStream");
 var DEFAULT_ACK_PERIOD2 = 30;
-var DEFAULT_BUFFER_SIZE2 = 61;
+var DEFAULT_ACK_ADVANCE2 = 61;
 function parseStreamRef(value) {
   if (typeof value === "string") {
     const parts = value.split(",");
@@ -1388,12 +1424,12 @@ function parseStreamRef(value) {
     const hostId = parts[0];
     const localId = parseInt(parts[1], 10);
     const ackPeriod = parseInt(parts[2], 10);
-    const bufferSize = parseInt(parts[3], 10);
-    if (isNaN(localId) || isNaN(ackPeriod) || isNaN(bufferSize))
+    const ackAdvance = parseInt(parts[3], 10);
+    if (isNaN(localId) || isNaN(ackPeriod) || isNaN(ackAdvance))
       return null;
     const allowReconnect = parts.length < 5 || parts[4] !== "0";
     const isRealTime = parts.length >= 6 && parts[5] === "1";
-    return { hostId, localId, ackPeriod, bufferSize, allowReconnect, isRealTime };
+    return { hostId, localId, ackPeriod, ackAdvance, allowReconnect, isRealTime };
   }
   if (typeof value === "object" && value !== null) {
     const obj = value;
@@ -1404,10 +1440,10 @@ function parseStreamRef(value) {
     const hostId = String(rawHostId);
     const localId = Number(serializedId[1]);
     const ackPeriod = Number(obj.AckPeriod ?? 256);
-    const bufferSize = Number(obj.BufferSize ?? 128);
+    const ackAdvance = Number(obj.AckAdvance ?? 128);
     const allowReconnect = obj.AllowReconnect !== false;
     const isRealTime = obj.IsRealTime === true;
-    return { hostId, localId, ackPeriod, bufferSize, allowReconnect, isRealTime };
+    return { hostId, localId, ackPeriod, ackAdvance, allowReconnect, isRealTime };
   }
   return null;
 }
@@ -1427,6 +1463,11 @@ var RpcStream = class _RpcStream {
   isRealTime;
   canSkipTo;
   ackPeriod;
+  ackAdvance;
+  /**
+   * Local-only ring buffer capacity hint for the sender. Undefined means
+   * "use ackAdvance as the buffer size". Not part of the wire ref.
+   */
   bufferSize;
   // Local (origin) mode
   localSource;
@@ -1457,7 +1498,8 @@ var RpcStream = class _RpcStream {
       this.isRealTime = options.isRealTime ?? false;
       this.canSkipTo = options.canSkipTo ?? (() => true);
       this.ackPeriod = options.ackPeriod ?? DEFAULT_ACK_PERIOD2;
-      this.bufferSize = options.bufferSize ?? DEFAULT_BUFFER_SIZE2;
+      this.ackAdvance = options.ackAdvance ?? DEFAULT_ACK_ADVANCE2;
+      this.bufferSize = options.bufferSize;
     } else {
       const ref = sourceOrRef;
       const peer = optionsOrPeer;
@@ -1468,7 +1510,7 @@ var RpcStream = class _RpcStream {
       this.isRealTime = ref.isRealTime;
       this.canSkipTo = () => true;
       this.ackPeriod = ref.ackPeriod;
-      this.bufferSize = ref.bufferSize;
+      this.ackAdvance = ref.ackAdvance;
     }
   }
   /**
@@ -1491,7 +1533,7 @@ var RpcStream = class _RpcStream {
    * 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.
@@ -1508,11 +1550,12 @@ var RpcStream = class _RpcStream {
     const sender = new RpcStreamSender(
       peer,
       this.ackPeriod,
-      this.bufferSize,
+      this.ackAdvance,
       this.allowReconnect,
       this.isRealTime,
       this.canSkipTo,
-      isFactory
+      isFactory,
+      this.bufferSize
     );
     peer.sharedObjects.register(sender);
     this._sender = sender;
@@ -1521,7 +1564,7 @@ var RpcStream = class _RpcStream {
     this._toRefValue = peer.serializationFormat.isBinary ? {
       SerializedId: [sender.id.hostId, sender.id.localId],
       AckPeriod: sender.ackPeriod,
-      BufferSize: sender.bufferSize,
+      AckAdvance: sender.ackAdvance,
       AllowReconnect: sender.allowReconnect
     } : sender.toRef();
     return this._toRefValue;
@@ -1836,19 +1879,17 @@ var RpcSystemCallHandler = class {
         sender?.onAckEnd(args[0]);
         break;
       }
-      default: {
-        if (method === "$sys.Disconnect" || method?.startsWith("$sys.Disconnect")) {
-          const ids = args[0];
-          if (Array.isArray(ids)) {
-            for (const id of ids) {
-              const remoteObj = peer.remoteObjects.get(id);
-              if (remoteObj && typeof remoteObj.disconnect === "function") {
-                remoteObj.disconnect();
-              }
-              const sharedObj = peer.sharedObjects.get(id);
-              if (sharedObj && typeof sharedObj.disconnect === "function") {
-                sharedObj.disconnect();
-              }
+      case RpcSystemCalls.disconnect: {
+        const ids = args[0];
+        if (Array.isArray(ids)) {
+          for (const id of ids) {
+            const remoteObj = peer.remoteObjects.get(id);
+            if (remoteObj && typeof remoteObj.disconnect === "function") {
+              remoteObj.disconnect();
+            }
+            const sharedObj = peer.sharedObjects.get(id);
+            if (sharedObj && typeof sharedObj.disconnect === "function") {
+              sharedObj.disconnect();
             }
           }
         }
@@ -2245,6 +2286,9 @@ var RpcSerializationFormatResolver = class _RpcSerializationFormatResolver {
 };
 
 // src/rpc-peer.ts
+function yieldToEventLoop() {
+  return new Promise((resolve) => setTimeout(resolve, 0));
+}
 var RPC_CLOSE_CODE_UNSUPPORTED_FORMAT = 4001;
 var HANDSHAKE_TIMEOUT_MS = 1e4;
 var KEEP_ALIVE_PERIOD_MS = 15e3;
@@ -2297,16 +2341,14 @@ var RpcPeer = class {
    *  entered only after the handshake has succeeded. */
   connectionStateChanged = new import_core7.EventHandlerSet();
   _connection;
-  /** 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. */
   _isConnected = false;
   _connectionState = 0 /* Disconnected */;
-  _pendingSends = [];
   _keepAliveTimer;
   _keepAliveWatchdog;
   /** Wall-clock time of the last inbound `$sys.KeepAlive`, or 0 if none yet
@@ -2333,11 +2375,11 @@ var RpcPeer = class {
     if (this._connectionState === value) return;
     const previousState = this._connectionState;
     this._connectionState = value;
-    if (value === 2 /* Connected */) {
+    if (value === 3 /* Connected */) {
       this._isConnected = true;
       this._armKeepAliveWatchdog();
     } else if (value === 0 /* Disconnected */) {
-      if (previousState === 2 /* Connected */)
+      if (previousState === 3 /* Connected */)
         this._isConnected = false;
       this._disarmKeepAliveWatchdog();
     }
@@ -2346,11 +2388,11 @@ var RpcPeer = class {
   /** Resolves on the next transition into `Connected` — or immediately if
    *  already in that state. */
   whenConnected() {
-    if (this._connectionState === 2 /* Connected */)
+    if (this._connectionState === 3 /* Connected */)
       return Promise.resolve();
     return new Promise((resolve) => {
       const handler = (state) => {
-        if (state !== 2 /* Connected */) return;
+        if (state !== 3 /* Connected */) return;
         this.connectionStateChanged.remove(handler);
         resolve();
       };
@@ -2400,11 +2442,18 @@ var RpcPeer = class {
       this._connection?.encoder,
       this.hub.registry
     );
+    this.outboundCalls.register(outboundCall);
     if (this._isConnected) {
-      this.outboundCalls.register(outboundCall);
       this._sendWireData(outboundCall.serializedWireData);
     } else {
-      this._pendingSends.push(outboundCall);
+      const stateHandler = (state) => {
+        if (state !== 3 /* Connected */) return;
+        this.connectionStateChanged.remove(stateHandler);
+        if (outboundCall.result.isCompleted) return;
+        this._sendWireData(outboundCall.serializedWireData);
+      };
+      this.connectionStateChanged.add(stateHandler);
+      outboundCall.result.promise.then(() => this.connectionStateChanged.remove(stateHandler)).catch(() => this.connectionStateChanged.remove(stateHandler));
     }
     const signal = options?.signal;
     if (signal !== void 0) {
@@ -2414,17 +2463,6 @@ var RpcPeer = class {
           outboundCall.onDisconnect();
           if (this._connection !== void 0)
             this.hub.systemCallSender.cancel(this._connection, this.serializationFormat, callId);
-        } else {
-          const idx = this._pendingSends.findIndex(
-            (c) => c.callId === callId
-          );
-          if (idx !== -1) {
-            this._pendingSends.splice(idx, 1);
-            outboundCall.result.reject(
-              new Error("Call cancelled.")
-            );
-            outboundCall.onDisconnect();
-          }
         }
       };
       signal.addEventListener("abort", onAbort, { once: true });
@@ -2455,12 +2493,6 @@ var RpcPeer = class {
     infoLog?.log(`'${this.ref}': Stopping`);
     this.remoteObjects.disconnectAll();
     this.sharedObjects.disconnectAll();
-    for (const call of this._pendingSends) {
-      if (!call.result.isCompleted)
-        call.result.reject(new Error("Peer closed."));
-      call.onDisconnect();
-    }
-    this._pendingSends.length = 0;
     this.outboundCalls.rejectAll(new Error("Peer closed."));
     this.outboundCalls.invalidateAll();
     this._connection?.close();
@@ -2468,16 +2500,6 @@ var RpcPeer = class {
     this._setConnectionState(0 /* Disconnected */);
     infoLog?.log(`'${this.ref}': Stopped`);
   }
-  /** Send any messages buffered while disconnected. Call after connection + handshake are ready. */
-  _flushPendingSends() {
-    if (this._pendingSends.length === 0 || this._connection === void 0)
-      return;
-    for (const call of this._pendingSends) {
-      this.outboundCalls.register(call);
-      this._sendWireData(call.serializedWireData);
-    }
-    this._pendingSends.length = 0;
-  }
   /** Send pre-serialized wire data through the current connection. */
   _sendWireData(data) {
     if (this._connection === void 0) return;
@@ -2630,7 +2652,8 @@ var RpcPeer = class {
 var RpcConnectionState = /* @__PURE__ */ ((RpcConnectionState2) => {
   RpcConnectionState2[RpcConnectionState2["Disconnected"] = 0] = "Disconnected";
   RpcConnectionState2[RpcConnectionState2["Connecting"] = 1] = "Connecting";
-  RpcConnectionState2[RpcConnectionState2["Connected"] = 2] = "Connected";
+  RpcConnectionState2[RpcConnectionState2["Handshaking"] = 2] = "Handshaking";
+  RpcConnectionState2[RpcConnectionState2["Connected"] = 3] = "Connected";
   return RpcConnectionState2;
 })(RpcConnectionState || {});
 var RpcClientPeer = class extends RpcPeer {
@@ -2704,6 +2727,7 @@ var RpcClientPeer = class extends RpcPeer {
   connectWith(conn, isPeerChanged = true) {
     this.setupConnection(conn);
     this._isConnected = true;
+    this.connectionStateChanged.trigger(3 /* Connected */);
     void this._reconnect(isPeerChanged);
   }
   /** Kick off the reconnect loop. Idempotent — subsequent calls are
@@ -2765,6 +2789,7 @@ var RpcClientPeer = class extends RpcPeer {
           this._pendingHandshake = new import_core7.PromiseSource();
           this.setupConnection(conn);
           await Promise.race([conn.whenConnected, closedRejection]);
+          this._setConnectionState(2 /* Handshaking */);
           try {
             this.hub.systemCallSender.handshake(
               conn,
@@ -2816,7 +2841,7 @@ var RpcClientPeer = class extends RpcPeer {
             this._lastRemoteHubId = remoteHubId;
           }
           infoLog?.log(`'${this.ref}': Handshake succeeded, peerChanged=${isPeerChanged}`);
-          this._setConnectionState(2 /* Connected */);
+          this._setConnectionState(3 /* Connected */);
           this._tryIndex = 0;
           await this._reconnect(isPeerChanged, closedController.signal);
           await whenClosed.promise;
@@ -2891,6 +2916,8 @@ var RpcClientPeer = class extends RpcPeer {
     if (!isPeerChanged && eligible.length > 0) {
       unknownIds = await this._reconcileReconnect(eligible, closedSignal);
     }
+    const YIELD_BATCH = 20;
+    let resentSinceYield = 0;
     for (const call of eligible) {
       if (!call.removeOnOk && call.result.isCompleted) {
         call.onDisconnect();
@@ -2901,8 +2928,12 @@ var RpcClientPeer = class extends RpcPeer {
         continue;
       }
       this._sendWireData(call.serializedWireData);
+      resentSinceYield++;
+      if (resentSinceYield >= YIELD_BATCH) {
+        resentSinceYield = 0;
+        await yieldToEventLoop();
+      }
     }
-    this._flushPendingSends();
   }
   /**
    * Ask the server which call IDs in `eligible` it no longer recognizes
@@ -2979,6 +3010,7 @@ var RpcServerPeer = class extends RpcPeer {
   accept(conn) {
     this._setConnectionState(1 /* Connecting */);
     this.setupConnection(conn);
+    this._setConnectionState(2 /* Handshaking */);
     conn.closed.add(() => {
       if (this._connection !== conn && this._connection !== void 0) return;
       this.sharedObjects.disconnectAll();
@@ -2993,7 +3025,7 @@ var RpcServerPeer = class extends RpcPeer {
         this.hub.hubId,
         0
       );
-      this._setConnectionState(2 /* Connected */);
+      this._setConnectionState(3 /* Connected */);
     }
   }
 };
@@ -3948,7 +3980,7 @@ var RpcPeerStateMonitor = class {
   _timer;
   // Arrow functions to preserve `this` when used as event handlers
   _onConnectionStateChanged = (state) => {
-    if (state === 2 /* Connected */) {
+    if (state === 3 /* Connected */) {
       this._rawConnected = true;
       this._connectedAt = Date.now();
       this._lastError = void 0;