@actuallab/rpc 12.2.23 → 12.3.4

package/dist/index.js

@@ -645,12 +645,200 @@ var RpcInboundCallTracker = class {
 
 // src/rpc-stream.ts
 import Denque from "denque";
-import { PromiseSource as PromiseSource3 } from "@actuallab/core";
+import { PromiseSource as PromiseSource4 } from "@actuallab/core";
 
 // src/rpc-object.ts
 var RpcObjectKind = { Local: 0, Remote: 1 };
 
+// src/rpc-stream-sender.ts
+import { PromiseSource as PromiseSource3 } from "@actuallab/core";
+var DEFAULT_ACK_PERIOD = 256;
+var DEFAULT_ACK_ADVANCE = 128;
+var RpcStreamSender = class _RpcStreamSender {
+  static _emptyGuid = "00000000-0000-0000-0000-000000000000";
+  id;
+  kind = RpcObjectKind.Local;
+  allowReconnect;
+  isRealTime;
+  canSkipTo;
+  peer;
+  ackPeriod;
+  ackAdvance;
+  _nextIndex = 0;
+  _ended = false;
+  _started = new PromiseSource3();
+  _lastAckedIndex = 0;
+  _ackWaiting = null;
+  _resetRequested = false;
+  constructor(peer, ackPeriod = DEFAULT_ACK_PERIOD, ackAdvance = DEFAULT_ACK_ADVANCE, allowReconnect = true, isRealTime = false, canSkipTo = () => true) {
+    const localId = peer.sharedObjects.nextId();
+    this.id = { hostId: peer.hub.hubId, localId };
+    this.allowReconnect = allowReconnect;
+    this.isRealTime = isRealTime;
+    this.canSkipTo = canSkipTo;
+    this.peer = peer;
+    this.ackPeriod = ackPeriod;
+    this.ackAdvance = ackAdvance;
+  }
+  /** Returns the stream reference string for the $sys.Ok response. */
+  toRef() {
+    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. */
+  onAck(nextIndex, hostId) {
+    const mustReset = hostId !== "" && hostId !== _RpcStreamSender._emptyGuid;
+    if (!this._started.isCompleted) {
+      this._started.resolve();
+    }
+    if (mustReset && this.isRealTime) {
+      this._nextIndex = nextIndex;
+      this._lastAckedIndex = nextIndex;
+      this._resetRequested = true;
+    } else {
+      if (mustReset || nextIndex > this._lastAckedIndex) {
+        this._lastAckedIndex = nextIndex;
+      }
+    }
+    if (this._ackWaiting) {
+      this._ackWaiting.resolve();
+      this._ackWaiting = null;
+    }
+  }
+  /** Called by system call handler when $sys.AckEnd is received from the client. */
+  onAckEnd(_hostId) {
+    this._ended = true;
+    this.peer.sharedObjects.unregister(this);
+  }
+  /** Send a single item to the client. */
+  sendItem(item) {
+    if (this._ended) return;
+    const conn = this.peer.connection;
+    if (!conn) return;
+    this.peer.hub.systemCallSender.item(
+      conn,
+      this.peer.format,
+      this.id.localId,
+      this._nextIndex,
+      item
+    );
+    this._nextIndex++;
+  }
+  /** Send a batch of items to the client. */
+  sendBatch(items) {
+    if (this._ended || items.length === 0) return;
+    const conn = this.peer.connection;
+    if (!conn) return;
+    this.peer.hub.systemCallSender.batch(
+      conn,
+      this.peer.format,
+      this.id.localId,
+      this._nextIndex,
+      items
+    );
+    this._nextIndex += items.length;
+  }
+  /** Signal stream completion to the client. */
+  sendEnd(error) {
+    if (this._ended) return;
+    this._ended = true;
+    const conn = this.peer.connection;
+    if (!conn) return;
+    const errorInfo = error ? { TypeRef: "System.Exception", Message: error.message } : { TypeRef: "", Message: "" };
+    this.peer.hub.systemCallSender.end(
+      conn,
+      this.peer.format,
+      this.id.localId,
+      this._nextIndex,
+      errorInfo
+    );
+  }
+  /**
+   * 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.
+   */
+  async writeFrom(source) {
+    await this._started.promise;
+    const iterator = source[Symbol.asyncIterator]();
+    try {
+      for (; ; ) {
+        const next = await iterator.next();
+        if (next.done || this._ended) break;
+        const item = next.value;
+        if (this._resetRequested) {
+          if (!this.canSkipTo(item)) continue;
+          this._resetRequested = false;
+          this.sendItem(item);
+          continue;
+        }
+        if (this._nextIndex < this._lastAckedIndex + this.ackAdvance) {
+          this.sendItem(item);
+          continue;
+        }
+        if (!this.isRealTime) {
+          await this._waitForAckBudget();
+          if (this._ended) return;
+          this.sendItem(item);
+          continue;
+        }
+        let latestSkipTarget = this.canSkipTo(item) ? item : void 0;
+        let sourceExhausted = false;
+        while (this._nextIndex >= this._lastAckedIndex + this.ackAdvance) {
+          if (this._ended) return;
+          const n = await iterator.next();
+          if (n.done) {
+            sourceExhausted = true;
+            break;
+          }
+          if (this.canSkipTo(n.value)) {
+            latestSkipTarget = n.value;
+          }
+        }
+        if (this._ended) return;
+        if (latestSkipTarget !== void 0) {
+          this.sendItem(latestSkipTarget);
+        }
+        if (sourceExhausted) {
+          if (!this._ended) this.sendEnd();
+          return;
+        }
+      }
+      if (!this._ended) {
+        this.sendEnd();
+      }
+    } catch (e) {
+      if (!this._ended) {
+        this.sendEnd(e instanceof Error ? e : new Error(String(e)));
+      }
+    }
+  }
+  /** Wait until _nextIndex < _lastAckedIndex + ackAdvance. */
+  async _waitForAckBudget() {
+    while (this._nextIndex >= this._lastAckedIndex + this.ackAdvance) {
+      if (this._ended) return;
+      this._ackWaiting = new PromiseSource3();
+      await this._ackWaiting.promise;
+    }
+  }
+  // -- IRpcObject --
+  reconnect() {
+  }
+  disconnect() {
+    this._ended = true;
+    if (!this._started.isCompleted) {
+      this._started.resolve();
+    }
+    this.peer.sharedObjects.unregister(this);
+  }
+};
+
 // src/rpc-stream.ts
+var DEFAULT_ACK_PERIOD2 = 30;
+var DEFAULT_ACK_ADVANCE2 = 61;
 function parseStreamRef(value) {
   if (typeof value === "string") {
     const parts = value.split(",");
@@ -683,17 +871,21 @@ function parseStreamRef(value) {
 }
 var RpcStream = class _RpcStream {
   id;
-  kind = RpcObjectKind.Remote;
+  kind;
   allowReconnect;
-  peer;
+  isRealTime;
+  canSkipTo;
   ackPeriod;
   ackAdvance;
-  // Double-ended queue so consumption via `shift()` is O(1) and the
-  // backing store frees memory as items are drained. The previous
-  // `T[]` buffer kept every item for the life of the stream because
-  // the iterator tracked a read index instead of shifting — fine for
-  // short runs but a slow leak in the browser where a video call can
-  // last an hour.
+  // Local (origin) mode
+  localSource;
+  // Remote (target) mode
+  peer;
+  // Local-only state
+  _sender;
+  _toRefValue;
+  _whenSent;
+  // Remote-only state
   _buffer = new Denque();
   _nextExpectedIndex = 0;
   _consumerWaiting = null;
@@ -703,12 +895,76 @@ var RpcStream = class _RpcStream {
   _started = false;
   _iterating = false;
   _ackSentUpTo = 0;
-  constructor(ref, peer) {
-    this.id = { hostId: ref.hostId, localId: ref.localId };
-    this.allowReconnect = ref.allowReconnect;
-    this.peer = peer;
-    this.ackPeriod = ref.ackPeriod;
-    this.ackAdvance = ref.ackAdvance;
+  constructor(sourceOrRef, optionsOrPeer) {
+    if (_isAsyncIterable(sourceOrRef)) {
+      const options = optionsOrPeer ?? {};
+      this.kind = RpcObjectKind.Local;
+      this.localSource = sourceOrRef;
+      this.id = { hostId: "", localId: 0 };
+      this.allowReconnect = options.allowReconnect ?? true;
+      this.isRealTime = options.isRealTime ?? false;
+      this.canSkipTo = options.canSkipTo ?? (() => true);
+      this.ackPeriod = options.ackPeriod ?? DEFAULT_ACK_PERIOD2;
+      this.ackAdvance = options.ackAdvance ?? DEFAULT_ACK_ADVANCE2;
+    } else {
+      const ref = sourceOrRef;
+      const peer = optionsOrPeer;
+      this.kind = RpcObjectKind.Remote;
+      this.id = { hostId: ref.hostId, localId: ref.localId };
+      this.peer = peer;
+      this.allowReconnect = ref.allowReconnect;
+      this.isRealTime = ref.isRealTime;
+      this.canSkipTo = () => true;
+      this.ackPeriod = ref.ackPeriod;
+      this.ackAdvance = ref.ackAdvance;
+    }
+  }
+  /**
+   * For local streams: resolves when the sender finishes pumping (after `toRef()` was called).
+   * Rejects if the source throws. Throws if `toRef()` hasn't been called yet.
+   */
+  get whenSent() {
+    if (!this._whenSent)
+      throw new Error("toRef() must be called before awaiting whenSent.");
+    return this._whenSent;
+  }
+  /**
+   * For local streams: bind to a peer, create and register an `RpcStreamSender`,
+   * start pumping items from the local source in the background, and return the
+   * stream reference.
+   *
+   * For binary peers the ref is a MessagePack-compatible object
+   * (`{ SerializedId, AckPeriod, AckAdvance, AllowReconnect }`);
+   * for text peers it is a comma-separated string.
+   *
+   * Can only be called once per stream.
+   */
+  toRef(peer) {
+    if (this.kind !== RpcObjectKind.Local)
+      throw new Error("toRef() is only valid for local streams.");
+    if (this._sender) {
+      if (this._sender.peer !== peer)
+        throw new Error("toRef() was already called with a different peer.");
+      return this._toRefValue;
+    }
+    const sender = new RpcStreamSender(
+      peer,
+      this.ackPeriod,
+      this.ackAdvance,
+      this.allowReconnect,
+      this.isRealTime,
+      this.canSkipTo
+    );
+    peer.sharedObjects.register(sender);
+    this._sender = sender;
+    this._whenSent = sender.writeFrom(this.localSource);
+    this._toRefValue = peer.format.isBinary ? {
+      SerializedId: [sender.id.hostId, sender.id.localId],
+      AckPeriod: sender.ackPeriod,
+      AckAdvance: sender.ackAdvance,
+      AllowReconnect: sender.allowReconnect
+    } : sender.toRef();
+    return this._toRefValue;
   }
   /** Called by system call handler when a single item arrives ($sys.I). */
   onItem(index, item) {
@@ -773,6 +1029,7 @@ var RpcStream = class _RpcStream {
   }
   // -- IRpcObject --
   reconnect() {
+    if (this.kind === RpcObjectKind.Local) return;
     if (this.allowReconnect) {
       this._sendAck(this._nextExpectedIndex, true);
     } else {
@@ -780,6 +1037,7 @@ var RpcStream = class _RpcStream {
     }
   }
   disconnect() {
+    if (this.kind === RpcObjectKind.Local) return;
     if (this._completed) return;
     this._completed = true;
     this._completionError = new Error("Peer disconnected.");
@@ -787,33 +1045,35 @@ var RpcStream = class _RpcStream {
   }
   // -- AsyncIterable --
   [Symbol.asyncIterator]() {
+    if (this.kind === RpcObjectKind.Local) {
+      return this.localSource[Symbol.asyncIterator]();
+    }
     if (this._iterating)
       throw new Error("RpcStream can only be iterated once.");
     this._iterating = true;
-    const self = this;
     return {
-      async next() {
-        if (!self._started) {
-          self._started = true;
-          self._sendAck(0, true);
+      next: async () => {
+        if (!this._started) {
+          this._started = true;
+          this._sendAck(0, true);
         }
-        while (true) {
-          if (!self._buffer.isEmpty()) {
-            const value = self._buffer.shift();
+        for (; ; ) {
+          if (!this._buffer.isEmpty()) {
+            const value = this._buffer.shift();
             return { value, done: false };
           }
-          if (self._completed) {
-            if (self._completionError) throw self._completionError;
+          if (this._completed) {
+            if (this._completionError) throw this._completionError;
             return { value: void 0, done: true };
           }
-          self._consumerWaiting = new PromiseSource3();
-          await self._consumerWaiting.promise;
+          this._consumerWaiting = new PromiseSource4();
+          await this._consumerWaiting.promise;
         }
       },
-      async return() {
-        self._sendAckEnd();
-        self.dispose();
-        return { value: void 0, done: true };
+      return: () => {
+        this._sendAckEnd();
+        this.dispose();
+        return Promise.resolve({ value: void 0, done: true });
       }
     };
   }
@@ -821,7 +1081,9 @@ var RpcStream = class _RpcStream {
     if (this._disposed) return;
     this._disposed = true;
     this._completed = true;
-    this.peer.remoteObjects.unregister(this);
+    if (this.kind === RpcObjectKind.Remote) {
+      this.peer.remoteObjects.unregister(this);
+    }
     this._notifyConsumer();
   }
   // -- Private --
@@ -865,6 +1127,9 @@ var RpcStream = class _RpcStream {
     }
   }
 };
+function _isAsyncIterable(value) {
+  return value !== null && typeof value === "object" && Symbol.asyncIterator in value;
+}
 function resolveStreamRefs(value, peer) {
   if (value === null || value === void 0) return value;
   if (typeof value === "string") {
@@ -1119,177 +1384,6 @@ var RpcSystemCallSender = class _RpcSystemCallSender {
   }
 };
 
-// src/rpc-stream-sender.ts
-import { PromiseSource as PromiseSource4 } from "@actuallab/core";
-var DEFAULT_ACK_PERIOD = 256;
-var DEFAULT_ACK_ADVANCE = 128;
-var RpcStreamSender = class {
-  id;
-  kind = RpcObjectKind.Local;
-  allowReconnect;
-  isRealTime;
-  canSkipTo;
-  peer;
-  ackPeriod;
-  ackAdvance;
-  _nextIndex = 0;
-  _ended = false;
-  _started = new PromiseSource4();
-  _lastAckedIndex = 0;
-  _ackWaiting = null;
-  constructor(peer, ackPeriod = DEFAULT_ACK_PERIOD, ackAdvance = DEFAULT_ACK_ADVANCE, allowReconnect = true, isRealTime = false, canSkipTo = () => true) {
-    const localId = peer.sharedObjects.nextId();
-    this.id = { hostId: peer.hub.hubId, localId };
-    this.allowReconnect = allowReconnect;
-    this.isRealTime = isRealTime;
-    this.canSkipTo = canSkipTo;
-    this.peer = peer;
-    this.ackPeriod = ackPeriod;
-    this.ackAdvance = ackAdvance;
-  }
-  /** Returns the stream reference string for the $sys.Ok response. */
-  toRef() {
-    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. */
-  onAck(nextIndex, _hostId) {
-    if (!this._started.isCompleted) {
-      this._started.resolve();
-    }
-    if (nextIndex > this._lastAckedIndex) {
-      this._lastAckedIndex = nextIndex;
-    }
-    if (this._ackWaiting) {
-      this._ackWaiting.resolve();
-      this._ackWaiting = null;
-    }
-  }
-  /** Called by system call handler when $sys.AckEnd is received from the client. */
-  onAckEnd(_hostId) {
-    this._ended = true;
-    this.peer.sharedObjects.unregister(this);
-  }
-  /** Send a single item to the client. */
-  sendItem(item) {
-    if (this._ended) return;
-    const conn = this.peer.connection;
-    if (!conn) return;
-    this.peer.hub.systemCallSender.item(
-      conn,
-      this.peer.format,
-      this.id.localId,
-      this._nextIndex,
-      item
-    );
-    this._nextIndex++;
-  }
-  /** Send a batch of items to the client. */
-  sendBatch(items) {
-    if (this._ended || items.length === 0) return;
-    const conn = this.peer.connection;
-    if (!conn) return;
-    this.peer.hub.systemCallSender.batch(
-      conn,
-      this.peer.format,
-      this.id.localId,
-      this._nextIndex,
-      items
-    );
-    this._nextIndex += items.length;
-  }
-  /** Signal stream completion to the client. */
-  sendEnd(error) {
-    if (this._ended) return;
-    this._ended = true;
-    const conn = this.peer.connection;
-    if (!conn) return;
-    const errorInfo = error ? { TypeRef: "System.Exception", Message: error.message } : { TypeRef: "", Message: "" };
-    this.peer.hub.systemCallSender.end(
-      conn,
-      this.peer.format,
-      this.id.localId,
-      this._nextIndex,
-      errorInfo
-    );
-  }
-  /**
-   * 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.
-   */
-  async writeFrom(source) {
-    await this._started.promise;
-    const iterator = source[Symbol.asyncIterator]();
-    try {
-      while (true) {
-        const next = await iterator.next();
-        if (next.done || this._ended) break;
-        const item = next.value;
-        if (this._nextIndex < this._lastAckedIndex + this.ackAdvance) {
-          this.sendItem(item);
-          continue;
-        }
-        if (!this.isRealTime) {
-          await this._waitForAckBudget();
-          if (this._ended) return;
-          this.sendItem(item);
-          continue;
-        }
-        let latestSkipTarget = this.canSkipTo(item) ? item : void 0;
-        let sourceExhausted = false;
-        while (this._nextIndex >= this._lastAckedIndex + this.ackAdvance) {
-          if (this._ended) return;
-          const n = await iterator.next();
-          if (n.done) {
-            sourceExhausted = true;
-            break;
-          }
-          if (this.canSkipTo(n.value)) {
-            latestSkipTarget = n.value;
-          }
-        }
-        if (this._ended) return;
-        if (latestSkipTarget !== void 0) {
-          this.sendItem(latestSkipTarget);
-        }
-        if (sourceExhausted) {
-          if (!this._ended) this.sendEnd();
-          return;
-        }
-      }
-      if (!this._ended) {
-        this.sendEnd();
-      }
-    } catch (e) {
-      if (!this._ended) {
-        this.sendEnd(e instanceof Error ? e : new Error(String(e)));
-      }
-    }
-  }
-  /** Wait until _nextIndex < _lastAckedIndex + ackAdvance. */
-  async _waitForAckBudget() {
-    while (this._nextIndex >= this._lastAckedIndex + this.ackAdvance) {
-      if (this._ended) return;
-      this._ackWaiting = new PromiseSource4();
-      await this._ackWaiting.promise;
-    }
-  }
-  // -- IRpcObject --
-  reconnect() {
-  }
-  disconnect() {
-    this._ended = true;
-    if (!this._started.isCompleted) {
-      this._started.resolve();
-    }
-    this.peer.sharedObjects.unregister(this);
-  }
-};
-
 // src/rpc-remote-object-tracker.ts
 var RpcRemoteObjectTracker = class {
   _objects = /* @__PURE__ */ new Map();
@@ -1588,21 +1682,18 @@ var RpcPeer = class {
     }
     const signal = options?.signal;
     if (signal !== void 0) {
-      const peer = this;
-      const hub = this._hub;
-      const tracker = this.outbound;
       const onAbort = () => {
-        if (tracker.remove(callId) !== void 0) {
+        if (this.outbound.remove(callId) !== void 0) {
           outboundCall.result.reject(new Error("Call cancelled."));
           outboundCall.onDisconnect();
-          if (peer._connection !== void 0)
-            hub.systemCallSender.cancel(peer._connection, peer.format, callId);
+          if (this._connection !== void 0)
+            this._hub.systemCallSender.cancel(this._connection, this.format, callId);
         } else {
-          const idx = peer._pendingSends.findIndex(
+          const idx = this._pendingSends.findIndex(
             (c) => c.callId === callId
           );
           if (idx !== -1) {
-            peer._pendingSends.splice(idx, 1);
+            this._pendingSends.splice(idx, 1);
             outboundCall.result.reject(
               new Error("Call cancelled.")
             );
@@ -1696,53 +1787,49 @@ var RpcPeer = class {
       this.inbound.register(call);
     }
     const serviceHost = this._hub.serviceHost;
-    if (serviceHost !== void 0) {
-      void (async () => {
-        try {
-          const context = this._connection !== void 0 ? {
-            __rpcDispatch: true,
-            callId: relatedId,
-            connection: this._connection
-          } : void 0;
-          const result = await serviceHost.dispatch(
-            method,
-            args,
-            context
+    void (async () => {
+      try {
+        const context = this._connection !== void 0 ? {
+          __rpcDispatch: true,
+          callId: relatedId,
+          connection: this._connection
+        } : void 0;
+        const result = await serviceHost.dispatch(
+          method,
+          args,
+          context
+        );
+        if (methodDef?.stream === true && this._connection !== void 0) {
+          const stream = result instanceof RpcStream ? result : new RpcStream(result);
+          this._hub.systemCallSender.ok(
+            this._connection,
+            this.format,
+            relatedId,
+            stream.toRef(this)
+          );
+        } else if (!isNoWait && this._connection !== void 0) {
+          this._hub.systemCallSender.ok(
+            this._connection,
+            this.format,
+            relatedId,
+            result
           );
-          if (methodDef?.stream === true && this._connection !== void 0) {
-            const sender = new RpcStreamSender(this);
-            this.sharedObjects.register(sender);
-            this._hub.systemCallSender.ok(
-              this._connection,
-              this.format,
-              relatedId,
-              sender.toRef()
-            );
-            void sender.writeFrom(result);
-          } else if (!isNoWait && this._connection !== void 0) {
-            this._hub.systemCallSender.ok(
-              this._connection,
-              this.format,
-              relatedId,
-              result
-            );
-          }
-        } catch (e) {
-          if (!isNoWait && this._connection !== void 0) {
-            this._hub.systemCallSender.error(
-              this._connection,
-              this.format,
-              relatedId,
-              e
-            );
-          }
-        } finally {
-          if (!isNoWait) {
-            this.inbound.remove(relatedId);
-          }
         }
-      })();
-    }
+      } catch (e) {
+        if (!isNoWait && this._connection !== void 0) {
+          this._hub.systemCallSender.error(
+            this._connection,
+            this.format,
+            relatedId,
+            e
+          );
+        }
+      } finally {
+        if (!isNoWait) {
+          this.inbound.remove(relatedId);
+        }
+      }
+    })();
   }
   _startKeepAlive() {
     this._keepAliveTimer = setInterval(() => {
@@ -2611,6 +2698,7 @@ var RpcHub = class {
     this.registry.registerService(def.name, def.methods);
   }
   /** Create a typed client proxy for a service on a remote peer. */
+  // eslint-disable-next-line @typescript-eslint/no-unnecessary-type-parameters -- T is used for caller-specified proxy type
   addClient(peer, defOrContract) {
     const def = this._resolveServiceDef(defOrContract);
     this.registry.registerService(def.name, def.methods);