@zlink-systems/stream-connector 0.13.0 → 0.15.0

package/dist/browser/Contracts/IZlinkStreamConnector.d.ts

@@ -1,7 +1,7 @@
 import type { Disposable } from './ZlinkStreamInterfaces';
 import type { RequiredZlinkStreamConnectorOptions } from './ZlinkStreamConnectorOptions';
 import type { ZlinkStreamRequestCall, ZlinkStreamSendCall, ZlinkStreamExpectNoneCall, ZlinkStreamSequenceCall, ZlinkStreamWaitCall } from './Calls/ZlinkStreamCalls';
-import type { ZlinkStreamConnectionStateChanged, ZlinkStreamEncodedPayload, ZlinkStreamError, ZlinkStreamInboundObservation, ZlinkStreamMessage } from './ZlinkStreamModels';
+import type { ZlinkStreamConnectionStateChanged, ZlinkStreamEncodedPayload, ZlinkStreamError, ZlinkStreamMessage } from './ZlinkStreamModels';
 import type { ZlinkStreamCloseReason, ZlinkStreamConnectionState, ZlinkStreamDiagnosticsLevel } from './ZlinkStreamEnums';
 export interface ZlinkStreamConnector {
     readonly isConnected: boolean;
@@ -30,7 +30,6 @@ export interface ZlinkStreamConnector {
     dispatch(signal?: AbortSignal): Promise<void>;
     send(payload: unknown, messageType?: Function): ZlinkStreamSendCall;
     request(payload: unknown, messageType?: Function): ZlinkStreamRequestCall;
-    observeInbound(observer: (observation: ZlinkStreamInboundObservation, signal?: AbortSignal) => Promise<void> | void): Disposable;
     on<TPayload = ZlinkStreamEncodedPayload>(name: string, handler: (message: ZlinkStreamMessage<TPayload>, signal?: AbortSignal) => Promise<void> | void, messageType?: Function): Disposable;
     waitFor<TPayload = ZlinkStreamEncodedPayload>(name: string): ZlinkStreamWaitCall<TPayload>;
     expectNone<TPayload = ZlinkStreamEncodedPayload>(name: string): ZlinkStreamExpectNoneCall<TPayload>;

package/dist/browser/Contracts/ZlinkStreamConnectorOptions.d.ts

@@ -12,9 +12,6 @@ export interface ZlinkStreamConnectorOptions {
     readonly reconnect?: ZlinkStreamReconnectOptions;
     readonly maxSendPayloadSize?: number;
     readonly maxReceivePayloadSize?: number;
-    readonly maxReceivedMessages?: number;
-    readonly maxInboundObserverNotifications?: number;
-    readonly maxInboundObserverPayloadPreviewBytes?: number;
     readonly dispatchMode?: ZlinkStreamDispatchMode;
     readonly compression?: ZlinkStreamCompression;
     readonly compressionCodec?: ZlinkStreamCompressionCodec;
@@ -85,9 +82,6 @@ export interface RequiredZlinkStreamConnectorOptions {
     readonly reconnect: Required<ZlinkStreamReconnectOptions>;
     readonly maxSendPayloadSize: number;
     readonly maxReceivePayloadSize: number;
-    readonly maxReceivedMessages: number;
-    readonly maxInboundObserverNotifications: number;
-    readonly maxInboundObserverPayloadPreviewBytes: number;
     readonly dispatchMode: ZlinkStreamDispatchMode;
     readonly compression: ZlinkStreamCompression;
     readonly compressionCodec?: ZlinkStreamCompressionCodec;

package/dist/browser/Contracts/ZlinkStreamEnums.d.ts

@@ -54,9 +54,6 @@ export declare enum ZlinkStreamErrorCode {
     CompressionFailed = "compressionFailed",
     DecompressionFailed = "decompressionFailed",
     UserCallbackFailed = "userCallbackFailed",
-    ObserverFailed = "observer-failed",
-    ObserverDropped = "observer-dropped",
-    ReceivedMessageDropped = "received-message-dropped",
     RemoteError = "remoteError"
 }
 export declare enum ZlinkStreamConnectionState {

package/dist/browser/Contracts/ZlinkStreamModels.d.ts

@@ -42,19 +42,6 @@ export interface ZlinkStreamConnectionStateChanged {
     readonly current: ZlinkStreamConnectionState;
     readonly error?: ZlinkStreamError;
 }
-export interface ZlinkStreamInboundObservation {
-    readonly kind: ZlinkStreamMessageKind;
-    readonly name: string;
-    readonly codec: ZlinkStreamCodec;
-    readonly requestSeq?: bigint;
-    readonly flowId?: string;
-    readonly flowOrigin?: ZlinkFlowOrigin;
-    readonly metadata: ZlinkStreamMetadata;
-    readonly payloadLength: number;
-    readonly isCompressed: boolean;
-    readonly receivedAt: Date;
-    readonly payloadPreview: Uint8Array;
-}
 export interface ZlinkStreamResult {
     readonly isSuccess: boolean;
     readonly error?: ZlinkStreamError;

package/dist/browser/Contracts/index.d.ts

@@ -3,7 +3,7 @@ export type { ZlinkFlowOrigin, ZlinkStreamCloseReason } from './ZlinkStreamEnums
 export * from './ZlinkStreamConnectorOptions';
 export * from './ZlinkStreamInterfaces';
 export * from './ZlinkStreamMetadata';
-export type { ZlinkStreamEncodedPayload, ZlinkStreamFlow, ZlinkStreamMessage, ZlinkStreamError, ZlinkStreamConnectionStateChanged, ZlinkStreamInboundObservation, ZlinkStreamResult, ZlinkStreamResultOf } from './ZlinkStreamModels';
+export type { ZlinkStreamEncodedPayload, ZlinkStreamFlow, ZlinkStreamMessage, ZlinkStreamError, ZlinkStreamConnectionStateChanged, ZlinkStreamResult, ZlinkStreamResultOf } from './ZlinkStreamModels';
 export { ZlinkStreamException } from './ZlinkStreamModels';
 export * from './ZlinkStreamJsonCodec';
 export * from './IZlinkStreamConnector';

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

@@ -1,4 +1,4 @@
-import { Disposable, RequiredZlinkStreamConnectorOptions, ZlinkStreamConnectionState, ZlinkStreamConnectionStateChanged, ZlinkStreamConnector, ZlinkStreamConnectorOptions, ZlinkStreamDiagnosticsLevel, ZlinkStreamEncodedPayload, ZlinkStreamError, ZlinkStreamExpectNoneCall, ZlinkStreamFlow, ZlinkStreamInboundObservation, ZlinkStreamMessage, ZlinkStreamMessageKind, ZlinkStreamMetadata, ZlinkStreamRequestCall, ZlinkStreamSendCall, ZlinkStreamSequenceCall, ZlinkStreamWaitCall } from '../Contracts';
+import { Disposable, RequiredZlinkStreamConnectorOptions, ZlinkStreamConnectionState, ZlinkStreamConnectionStateChanged, ZlinkStreamConnector, ZlinkStreamConnectorOptions, ZlinkStreamDiagnosticsLevel, ZlinkStreamEncodedPayload, ZlinkStreamError, ZlinkStreamExpectNoneCall, ZlinkStreamFlow, ZlinkStreamMessage, ZlinkStreamMessageKind, ZlinkStreamMetadata, ZlinkStreamRequestCall, ZlinkStreamSendCall, ZlinkStreamSequenceCall, ZlinkStreamWaitCall } from '../Contracts';
 export declare class DefaultZlinkStreamConnector implements ZlinkStreamConnector {
     static readonly heartbeatPingName = "$zlink.heartbeat.ping";
     static readonly heartbeatPongName = "$zlink.heartbeat.pong";
@@ -9,7 +9,6 @@ export declare class DefaultZlinkStreamConnector implements ZlinkStreamConnector
     private readonly pendingRequests;
     private readonly frameSender;
     private readonly receiveDispatcher;
-    private readonly inboundObservers;
     private readonly diagnosticsLevelCell;
     readonly options: RequiredZlinkStreamConnectorOptions;
     constructor(options: ZlinkStreamConnectorOptions);
@@ -43,7 +42,6 @@ export declare class DefaultZlinkStreamConnector implements ZlinkStreamConnector
     dispatch(signal?: AbortSignal): Promise<void>;
     send(payload: unknown, messageType?: Function): ZlinkStreamSendCall;
     request(payload: unknown, messageType?: Function): ZlinkStreamRequestCall;
-    observeInbound(observer: (observation: ZlinkStreamInboundObservation, signal?: AbortSignal) => Promise<void> | void): Disposable;
     on<TPayload = ZlinkStreamEncodedPayload>(name: string, handler: (message: ZlinkStreamMessage<TPayload>, signal?: AbortSignal) => Promise<void> | void, messageType?: Function): Disposable;
     waitFor<TPayload = ZlinkStreamEncodedPayload>(name: string): ZlinkStreamWaitCall<TPayload>;
     expectNone<TPayload = ZlinkStreamEncodedPayload>(name: string): ZlinkStreamExpectNoneCall<TPayload>;

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/ZlinkStreamReceiveDispatcher.d.ts

@@ -2,7 +2,6 @@ import type { ZlinkStreamConnection } from '../Contracts';
 import type { ZlinkStreamFrameProtocol } from './Protocol/ZlinkStreamFrameProtocol';
 import type { ZlinkStreamConnectorEvents } from './ZlinkStreamConnectorEvents';
 import type { ZlinkStreamFrameSender } from './ZlinkStreamFrameSender';
-import type { ZlinkStreamInboundObservers } from './ZlinkStreamInboundObservers';
 import type { ZlinkStreamPendingRequests } from './ZlinkStreamPendingRequests';
 import type { ZlinkStreamReceivedMessages } from './ZlinkStreamReceivedMessages';
 import type { ZlinkFlowContext } from './ZlinkFlowContext';
@@ -15,14 +14,13 @@ export interface ZlinkStreamReceiveResult {
 export declare class ZlinkStreamReceiveDispatcher {
     private readonly protocol;
     private readonly pendingRequests;
-    private readonly inboundObservers;
     private readonly receivedMessages;
     private readonly frameSender;
     private readonly events;
     private readonly flowContext;
     private readonly metrics;
     private readonly serverClosing?;
-    constructor(protocol: ZlinkStreamFrameProtocol, pendingRequests: ZlinkStreamPendingRequests, inboundObservers: ZlinkStreamInboundObservers, receivedMessages: ZlinkStreamReceivedMessages, frameSender: ZlinkStreamFrameSender, events: ZlinkStreamConnectorEvents, flowContext: ZlinkFlowContext, metrics: ZlinkStreamRuntimeMetrics, serverClosing?: ((reason: ZlinkStreamCloseReason) => Promise<void>) | undefined);
+    constructor(protocol: ZlinkStreamFrameProtocol, pendingRequests: ZlinkStreamPendingRequests, receivedMessages: ZlinkStreamReceivedMessages, frameSender: ZlinkStreamFrameSender, events: ZlinkStreamConnectorEvents, flowContext: ZlinkFlowContext, metrics: ZlinkStreamRuntimeMetrics, serverClosing?: ((reason: ZlinkStreamCloseReason) => Promise<void>) | undefined);
     readAndDispatch(connection: ZlinkStreamConnection | undefined, signal?: AbortSignal, isCurrent?: () => boolean): Promise<ZlinkStreamReceiveResult>;
     private dispatch;
     private dispatchControl;

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

@@ -1,24 +1,51 @@
 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 capacity;
     private readonly events;
+    private readonly deliverOnArrival;
     private readonly handlers;
+    private readonly observers;
     private readonly queue;
     private queueHead;
     private queuedCount;
     private drainTask;
-    private dropReportPending;
-    constructor(capacity: number, 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;
     private compactQueue;
-    private reportDropped;
 }
 export {};