@zlink-systems/stream-connector 0.14.0 → 0.15.0

package/dist/browser/index.mjs

@@ -9,7 +9,8 @@ function lz4PickleUncompressed(payload) {
   pickled.set(payload, 1);
   return pickled;
 }
-function lz4UnpicklePayload(payload, maxDecompressedSize = defaultMaxDecompressedPayloadSize) {
+function lz4UnpicklePayload(payload, maxSize) {
+  const maxDecompressedSize = maxSize ?? defaultMaxDecompressedPayloadSize;
   if (payload.length === 0) {
     return new Uint8Array();
   }
@@ -152,7 +153,8 @@ function decodeStreamWireFrame(frame) {
     payload: frame.slice(6 + headerLength)
   };
 }
-function encodeStreamWireHeader(header, flags = defaultHeaderFlags) {
+function encodeStreamWireHeader(header, flagOverrides) {
+  const flags = flagOverrides ?? defaultHeaderFlags;
   const reply = isReplyKind(header.kind);
   const packetName = reply ? "" : header.name;
   if (!reply) validateStreamWirePacketName(packetName);
@@ -213,7 +215,8 @@ function encodeStreamWireHeader(header, flags = defaultHeaderFlags) {
   }
   return buffer;
 }
-function decodeStreamWireHeader(header, flags = defaultHeaderFlags, includeFlow = true) {
+function decodeStreamWireHeader(header, flagOverrides, includeFlow = true) {
+  const flags = flagOverrides ?? defaultHeaderFlags;
   let offset = 0;
   if (header.length < 5) {
     throw new Error("Stream header is incomplete.");
@@ -351,8 +354,8 @@ function decodeStreamWireMetadata(metadata) {
 function lz4PickleUncompressed2(payload) {
   return lz4PickleUncompressed(payload);
 }
-function lz4UnpicklePayload2(payload, maxDecompressedSize = defaultMaxDecompressedPayloadSize) {
-  return lz4UnpicklePayload(payload, maxDecompressedSize);
+function lz4UnpicklePayload2(payload, maxDecompressedSize) {
+  return lz4UnpicklePayload(payload, maxDecompressedSize ?? defaultMaxDecompressedPayloadSize);
 }
 function utf8Encode(value) {
   return new TextEncoder().encode(value);
@@ -1464,10 +1467,18 @@ var ZlinkStreamPendingRequests = class {
 
 // packages/stream-connector/src/Runtime/ZlinkStreamReceivedMessages.ts
 var ZlinkStreamReceivedMessages = class {
-  constructor(events) {
+  /**
+   * @param deliverOnArrival `Immediate` runs registered handlers on the receive
+   *   path; `Manual` leaves them queued until {@link pump} runs them on the
+   *   caller's thread (spec stream-connector 32 §7). Wait surfaces observe the
+   *   queue in both modes, so they never depend on this flag.
+   */
+  constructor(events, deliverOnArrival) {
     this.events = events;
+    this.deliverOnArrival = deliverOnArrival;
   }
   handlers = /* @__PURE__ */ new Map();
+  observers = /* @__PURE__ */ new Map();
   // A handler can be registered after messages for another name arrive, so the
   // queue is not a simple FIFO. Tombstones let us remove a deliverable entry
   // without shifting every later message on the hot receive path.
@@ -1483,7 +1494,7 @@ var ZlinkStreamReceivedMessages = class {
       this.handlers.set(name, set);
     }
     set.add(handler);
-    if (this.hasQueuedMessage(name)) {
+    if (this.deliverOnArrival && this.hasQueuedMessage(name)) {
       queueMicrotask(() => this.scheduleDrain());
     }
     return subscription(() => {
@@ -1493,10 +1504,66 @@ var ZlinkStreamReceivedMessages = class {
       }
     });
   }
+  /**
+   * Registers a wait surface over the receive queue. Spec stream-connector 32
+   * §7: these are not registered callbacks — they observe and consume the
+   * packets the queue has not delivered yet, in both dispatch modes, so
+   * `Manual` needs no dispatch pump to complete a wait. The queue is scanned in
+   * a microtask so a message that arrived before the wait started is still
+   * observed, and so the caller has its subscription in hand by then.
+   */
+  observe(name, observer) {
+    validateName(name);
+    let set = this.observers.get(name);
+    if (set === void 0) {
+      set = /* @__PURE__ */ new Set();
+      this.observers.set(name, set);
+    }
+    set.add(observer);
+    queueMicrotask(() => {
+      if (this.observers.get(name)?.has(observer) === true) {
+        this.offerQueued(name, observer);
+      }
+    });
+    return subscription(() => {
+      set.delete(observer);
+      if (set.size === 0 && this.observers.get(name) === set) {
+        this.observers.delete(name);
+      }
+    });
+  }
   enqueue(message, signal) {
+    for (const observer of [...this.observers.get(message.name) ?? []]) {
+      if (observer(message)) {
+        return;
+      }
+    }
     this.queue.push({ message, signal });
     this.queuedCount += 1;
+    if (this.deliverOnArrival) {
+      this.scheduleDrain();
+    }
+  }
+  /**
+   * Runs the registered handlers the receive path left queued. `Manual` calls
+   * this from `dispatch`; `Immediate` has already drained on arrival.
+   */
+  async pump() {
     this.scheduleDrain();
+    await this.drainTask;
+  }
+  offerQueued(name, observer) {
+    for (let index = this.queueHead; index < this.queue.length; index += 1) {
+      const queued = this.queue[index];
+      if (queued === void 0 || queued.message.name !== name) {
+        continue;
+      }
+      if (!observer(queued.message)) {
+        continue;
+      }
+      this.removeAt(index);
+      return;
+    }
   }
   scheduleDrain() {
     if (this.drainTask !== void 0) {
@@ -1504,7 +1571,7 @@ var ZlinkStreamReceivedMessages = class {
     }
     this.drainTask = this.drain().finally(() => {
       this.drainTask = void 0;
-      if (this.findDeliverableIndex() >= 0) {
+      if (this.deliverOnArrival && this.findDeliverableIndex() >= 0) {
         this.scheduleDrain();
       }
     });
@@ -1513,10 +1580,7 @@ var ZlinkStreamReceivedMessages = class {
     for (let index = this.findDeliverableIndex(); index >= 0; index = this.findDeliverableIndex()) {
       const queued = this.queue[index];
       if (queued === void 0) continue;
-      this.queue[index] = void 0;
-      this.queuedCount -= 1;
-      this.advanceHead();
-      this.compactQueue();
+      this.removeAt(index);
       const { message, signal } = queued;
       const handlers = [...this.handlers.get(message.name)];
       for (const handler of handlers) {
@@ -1532,6 +1596,12 @@ var ZlinkStreamReceivedMessages = class {
       }
     }
   }
+  removeAt(index) {
+    this.queue[index] = void 0;
+    this.queuedCount -= 1;
+    this.advanceHead();
+    this.compactQueue();
+  }
   findDeliverableIndex() {
     for (let index = this.queueHead; index < this.queue.length; index += 1) {
       const queued = this.queue[index];
@@ -1785,15 +1855,19 @@ function decodeRemoteError(protocol, header, payload) {
 
 // packages/stream-connector/src/Runtime/ZlinkStreamConnectorLifecycle.ts
 var ZlinkStreamConnectorLifecycle = class {
-  constructor(options, pendingRequests, frameSender, receiveDispatcher, events, metrics) {
+  constructor(options, pendingRequests, frameSender, receiveDispatcher, receivedMessages, events, metrics) {
     this.options = options;
     this.pendingRequests = pendingRequests;
     this.frameSender = frameSender;
     this.receiveDispatcher = receiveDispatcher;
+    this.receivedMessages = receivedMessages;
     this.events = events;
     this.metrics = metrics;
   }
   receiveLoopAbort;
+  receiveLoopSleeping = false;
+  receiveLoopWake;
+  receiveLoopSettled = [];
   currentConnection;
   connectionGeneration = 0;
   currentState = "created" /* Created */;
@@ -1910,16 +1984,21 @@ var ZlinkStreamConnectorLifecycle = class {
     if (errors.length === 1) throw errors[0];
     if (errors.length > 1) throw new AggregateError(errors, "Stream connector close failed.");
   }
+  /**
+   * Spec stream-connector 32 §7: `dispatch` runs the callbacks the receive loop
+   * queued, it does not drive the transport. Receiving is the receive loop's
+   * job in both dispatch modes, which is what lets a `Manual` consumer complete
+   * a `waitFor` without pumping, and what keeps this call from blocking on an
+   * idle connection. In `Manual` it first lets the loop settle whatever has
+   * already arrived, so a packet the transport is holding is delivered by this
+   * pump rather than the next one.
+   */
   async dispatch(signal) {
-    const connection = this.currentConnection;
-    const generation = this.connectionGeneration;
-    try {
-      await this.dispatchAvailable(connection, generation, signal);
-    } catch (cause) {
-      const error = toStreamError(cause, "frameDecodeFailed" /* FrameDecodeFailed */, "Stream dispatch failed.");
-      await this.disconnectForTransportFailure(error, connection, generation);
-      throw new ZlinkStreamException(error);
+    throwIfAborted(signal);
+    if (this.options.dispatchMode !== "immediate" /* Immediate */) {
+      await this.settleReceiveLoop();
     }
+    await this.receivedMessages.pump();
   }
   connectionForSend() {
     if (this.currentConnection === void 0 || this.currentState !== "connected" /* Connected */) {
@@ -1988,8 +2067,12 @@ var ZlinkStreamConnectorLifecycle = class {
       this.heartbeatTimer = void 0;
     }
   }
+  // Spec stream-connector 32 §7: the receive loop runs in both dispatch modes.
+  // `Manual` only changes what the loop does with a frame — it queues the
+  // registered callbacks instead of running them — never whether frames are
+  // read off the transport.
   startReceiveLoop() {
-    if (this.options.dispatchMode !== "immediate" /* Immediate */ || this.currentConnection?.read === void 0) {
+    if (this.currentConnection?.read === void 0) {
       return;
     }
     this.stopReceiveLoop();
@@ -2002,19 +2085,66 @@ var ZlinkStreamConnectorLifecycle = class {
   stopReceiveLoop() {
     this.receiveLoopAbort?.abort();
     this.receiveLoopAbort = void 0;
+    this.receiveLoopSleeping = false;
+    this.releaseReceiveLoopSettled();
   }
   async runReceiveLoop(connection, generation, signal) {
     try {
       while (this.shouldContinueReceiveLoop(connection, generation, signal)) {
         const dispatched = await this.dispatchAvailable(connection, generation, signal);
         if (!dispatched && this.shouldContinueReceiveLoop(connection, generation, signal)) {
-          await delay(1, signal);
+          await this.sleepUntilWork(signal);
         }
       }
     } catch (cause) {
       if (signal.aborted) return;
       const error = toStreamError(cause, "frameDecodeFailed" /* FrameDecodeFailed */, "Receive loop failed.");
       await this.disconnectForTransportFailure(error, connection, generation);
+    } finally {
+      this.receiveLoopSleeping = false;
+      this.releaseReceiveLoopSettled();
+    }
+  }
+  // A transport whose read resolves only when a frame arrives parks the loop
+  // inside that read; one that reports "nothing available" instead parks it
+  // here. Both are the loop waiting for new data, and `dispatch` treats them
+  // the same way.
+  async sleepUntilWork(signal) {
+    this.receiveLoopSleeping = true;
+    this.releaseReceiveLoopSettled();
+    try {
+      await new Promise((resolve) => {
+        const finish = () => {
+          clearTimeout(timer);
+          signal.removeEventListener("abort", onAbort);
+          this.receiveLoopWake = void 0;
+          resolve();
+        };
+        const onAbort = () => finish();
+        const timer = setTimeout(finish, 1);
+        signal.addEventListener("abort", onAbort, { once: true });
+        this.receiveLoopWake = finish;
+      });
+    } finally {
+      this.receiveLoopSleeping = false;
+    }
+  }
+  // Returns once the loop has consumed everything the transport already had.
+  // A loop that is mid-batch, or parked inside a read that has not produced a
+  // frame, is already caught up, so only a sleeping loop is woken and awaited.
+  async settleReceiveLoop() {
+    if (this.receiveLoopAbort === void 0 || !this.receiveLoopSleeping) {
+      return;
+    }
+    const settled = new Promise((resolve) => {
+      this.receiveLoopSettled.push(resolve);
+    });
+    this.receiveLoopWake?.();
+    await settled;
+  }
+  releaseReceiveLoopSettled() {
+    for (const resolve of this.receiveLoopSettled.splice(0)) {
+      resolve();
     }
   }
   shouldContinueReceiveLoop(connection, generation, signal) {
@@ -2417,7 +2547,10 @@ var DefaultZlinkStreamConnector = class {
     const metrics = new ZlinkStreamRuntimeMetrics(this.options);
     const protocol = new ZlinkStreamFrameProtocol(this.options);
     this.frameSender = new ZlinkStreamFrameSender(protocol, flowContext, metrics);
-    this.receivedMessages = new ZlinkStreamReceivedMessages(this.events);
+    this.receivedMessages = new ZlinkStreamReceivedMessages(
+      this.events,
+      this.options.dispatchMode === "immediate" /* Immediate */
+    );
     this.receiveDispatcher = new ZlinkStreamReceiveDispatcher(
       protocol,
       this.pendingRequests,
@@ -2433,6 +2566,7 @@ var DefaultZlinkStreamConnector = class {
       this.pendingRequests,
       this.frameSender,
       this.receiveDispatcher,
+      this.receivedMessages,
       this.events,
       metrics
     );
@@ -2553,7 +2687,10 @@ var DefaultZlinkStreamConnector = class {
         finish(connectorError("requestTimeout" /* RequestTimeout */, "Wait for stream message timed out."));
       }, timeoutMs);
       signal?.addEventListener("abort", onAbort, { once: true });
-      disposable = this.receivedMessages.on(name, (message) => {
+      disposable = this.receivedMessages.observe(name, (message) => {
+        if (done) {
+          return false;
+        }
         try {
           const decoded = {
             name: message.name,
@@ -2562,12 +2699,14 @@ var DefaultZlinkStreamConnector = class {
             flowId: message.flowId,
             flowOrigin: message.flowOrigin
           };
-          if (predicate(decoded)) {
-            finish(void 0, decoded);
+          if (!predicate(decoded)) {
+            return false;
           }
+          finish(void 0, decoded);
         } catch (cause) {
           finish(cause);
         }
+        return true;
       });
     });
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zlink-systems/stream-connector",
-  "version": "0.14.0",
+  "version": "0.15.0",
   "license": "SEE LICENSE IN LICENSE",
   "repository": {
     "type": "git",
@@ -21,6 +21,6 @@
     }
   },
   "dependencies": {
-    "@zlink-systems/stream-wire": "0.14.0"
+    "@zlink-systems/stream-wire": "0.15.0"
   }
 }