@zlink-systems/stream-connector 0.14.0 → 0.15.0

package/dist/browser/Runtime/ZlinkStreamConnectorLifecycle.d.ts

@@ -5,15 +5,20 @@ import type { ZlinkStreamConnectorEvents } from './ZlinkStreamConnectorEvents';
 import type { ZlinkStreamFrameSender } from './ZlinkStreamFrameSender';
 import type { ZlinkStreamPendingRequests } from './ZlinkStreamPendingRequests';
 import type { ZlinkStreamReceiveDispatcher } from './ZlinkStreamReceiveDispatcher';
+import type { ZlinkStreamReceivedMessages } from './ZlinkStreamReceivedMessages';
 import type { ZlinkStreamRuntimeMetrics } from './ZlinkStreamRuntimeMetrics';
 export declare class ZlinkStreamConnectorLifecycle {
     private readonly options;
     private readonly pendingRequests;
     private readonly frameSender;
     private readonly receiveDispatcher;
+    private readonly receivedMessages;
     private readonly events;
     private readonly metrics;
     private receiveLoopAbort;
+    private receiveLoopSleeping;
+    private receiveLoopWake;
+    private readonly receiveLoopSettled;
     private currentConnection;
     private connectionGeneration;
     private currentState;
@@ -26,7 +31,7 @@ export declare class ZlinkStreamConnectorLifecycle {
     private disconnectedPublished;
     private closeReasonValue?;
     private lateConnectCleanupError;
-    constructor(options: RequiredZlinkStreamConnectorOptions, pendingRequests: ZlinkStreamPendingRequests, frameSender: ZlinkStreamFrameSender, receiveDispatcher: ZlinkStreamReceiveDispatcher, events: ZlinkStreamConnectorEvents, metrics: ZlinkStreamRuntimeMetrics);
+    constructor(options: RequiredZlinkStreamConnectorOptions, pendingRequests: ZlinkStreamPendingRequests, frameSender: ZlinkStreamFrameSender, receiveDispatcher: ZlinkStreamReceiveDispatcher, receivedMessages: ZlinkStreamReceivedMessages, events: ZlinkStreamConnectorEvents, metrics: ZlinkStreamRuntimeMetrics);
     get isConnected(): boolean;
     get state(): ZlinkStreamConnectionState;
     get closeReason(): ZlinkStreamCloseReason | undefined;
@@ -35,6 +40,15 @@ export declare class ZlinkStreamConnectorLifecycle {
     close(signal?: AbortSignal): Promise<void>;
     serverClosing(reason: ZlinkStreamCloseReason): Promise<void>;
     private closeOnce;
+    /**
+     * 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.
+     */
     dispatch(signal?: AbortSignal): Promise<void>;
     connectionForSend(): ZlinkStreamConnection;
     private dispatchAvailable;
@@ -44,6 +58,9 @@ export declare class ZlinkStreamConnectorLifecycle {
     private startReceiveLoop;
     private stopReceiveLoop;
     private runReceiveLoop;
+    private sleepUntilWork;
+    private settleReceiveLoop;
+    private releaseReceiveLoopSettled;
     private shouldContinueReceiveLoop;
     private runHeartbeatTick;
     private disconnectForTransportFailure;

package/dist/browser/Runtime/ZlinkStreamReceivedMessages.d.ts

@@ -1,18 +1,48 @@
 import { Disposable, ZlinkStreamEncodedPayload, ZlinkStreamMessage } from '../Contracts';
 import type { ZlinkStreamConnectorEvents } from './ZlinkStreamConnectorEvents';
 type EncodedMessageHandler = (message: ZlinkStreamMessage<ZlinkStreamEncodedPayload>, signal?: AbortSignal) => Promise<void> | void;
+/**
+ * A wait surface (`waitFor`, `expectNone`, `waitForSequence`) reading the queue
+ * directly. It returns true when it consumed the message and must not throw:
+ * a failed predicate is reported through the waiting call, not to the queue.
+ */
+type EncodedMessageObserver = (message: ZlinkStreamMessage<ZlinkStreamEncodedPayload>) => boolean;
 export declare class ZlinkStreamReceivedMessages {
     private readonly events;
+    private readonly deliverOnArrival;
     private readonly handlers;
+    private readonly observers;
     private readonly queue;
     private queueHead;
     private queuedCount;
     private drainTask;
-    constructor(events: ZlinkStreamConnectorEvents);
+    /**
+     * @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: ZlinkStreamConnectorEvents, deliverOnArrival: boolean);
     on(name: string, handler: EncodedMessageHandler): Disposable;
+    /**
+     * 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: string, observer: EncodedMessageObserver): Disposable;
     enqueue(message: ZlinkStreamMessage<ZlinkStreamEncodedPayload>, signal?: AbortSignal): void;
+    /**
+     * Runs the registered handlers the receive path left queued. `Manual` calls
+     * this from `dispatch`; `Immediate` has already drained on arrival.
+     */
+    pump(): Promise<void>;
+    private offerQueued;
     private scheduleDrain;
     private drain;
+    private removeAt;
     private findDeliverableIndex;
     private hasQueuedMessage;
     private advanceHead;