@actuallab/rpc 12.2.23 → 12.3.2

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 {
+      while (true) {
+        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,6 +1045,9 @@ 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;
@@ -806,7 +1067,7 @@ var RpcStream = class _RpcStream {
             if (self._completionError) throw self._completionError;
             return { value: void 0, done: true };
           }
-          self._consumerWaiting = new PromiseSource3();
+          self._consumerWaiting = new PromiseSource4();
           await self._consumerWaiting.promise;
         }
       },
@@ -821,7 +1082,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 +1128,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 +1385,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();
@@ -1710,15 +1805,13 @@ var RpcPeer = class {
             context
           );
           if (methodDef?.stream === true && this._connection !== void 0) {
-            const sender = new RpcStreamSender(this);
-            this.sharedObjects.register(sender);
+            const stream = result instanceof RpcStream ? result : new RpcStream(result);
             this._hub.systemCallSender.ok(
               this._connection,
               this.format,
               relatedId,
-              sender.toRef()
+              stream.toRef(this)
             );
-            void sender.writeFrom(result);
           } else if (!isNoWait && this._connection !== void 0) {
             this._hub.systemCallSender.ok(
               this._connection,