@zlink-systems/stream-connector 0.24.0 → 0.26.0

package/dist/browser/Runtime/Calls/ZlinkStreamCallBuilders.d.ts

@@ -19,8 +19,9 @@ export declare class ZlinkStreamSendBuilder implements ZlinkStreamSendCall {
 export declare class ZlinkStreamRequestBuilder implements ZlinkStreamRequestCall {
     private readonly connector;
     private readonly payload;
+    private readonly enqueueCallback;
     private readonly state;
-    constructor(connector: ZlinkStreamConnectorSubmitter, name: string | undefined, payload: ZlinkStreamEncodedPayload, actorSlot?: number, validateActor?: () => void);
+    constructor(connector: ZlinkStreamConnectorSubmitter, name: string | undefined, payload: ZlinkStreamEncodedPayload, enqueueCallback: (callback: () => void) => void, actorSlot?: number, validateActor?: () => void);
     packetName(name: string): this;
     metadata(key: string, value: string): this;
     metadata(metadata: ZlinkStreamMetadata): this;

package/dist/browser/Runtime/Transport/BrowserWebSocketConnection.d.ts

@@ -31,6 +31,11 @@ export declare class BrowserWebSocketConnection implements ZlinkStreamConnection
     constructor(socket: BrowserWebSocket);
     write(frame: Uint8Array, signal?: AbortSignal): Promise<void>;
     read(signal?: AbortSignal): Promise<Uint8Array | undefined>;
+    /**
+     * Spec stream-connector 32 §7: closing does not wait for the peer to read or
+     * answer. `WebSocket.close` sends the close frame after the data already
+     * handed to `send`, so a frame whose write completed is not torn.
+     */
     close(signal?: AbortSignal): Promise<void>;
     private readonly onMessage;
     private readonly onClose;

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

@@ -40,6 +40,5 @@ export declare class ZlinkStreamActors {
     private bind;
     private unbind;
     private queue;
-    private invoke;
 }
 export {};

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

@@ -71,7 +71,7 @@ export declare class DefaultZlinkStreamConnector implements ZlinkStreamConnector
     private encodePayload;
     private decodePayload;
     private decodeWaitPayload;
-    sendEncoded(kind: ZlinkStreamMessageKind, name: string, payload: ZlinkStreamEncodedPayload, metadata: ZlinkStreamMetadata, compress: boolean, requestSeq: bigint | undefined, signal?: AbortSignal, correlationId?: string, actorSlot?: number): Promise<void>;
+    sendEncoded(kind: ZlinkStreamMessageKind, name: string, payload: ZlinkStreamEncodedPayload, metadata: ZlinkStreamMetadata, compress: boolean, requestSeq: bigint | undefined, signal?: AbortSignal, correlationId?: string, actorSlot?: number, expiry?: Promise<unknown>, onAccepted?: () => void): Promise<void>;
     /**
      * Per-connector monotonic correlation id (hex). The client generates it on each request
      * and the server echoes it back on the reply.

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

@@ -1,13 +1,28 @@
 import type { Disposable, ZlinkStreamConnectionStateChanged, ZlinkStreamError } from '../Contracts';
 export declare class ZlinkStreamConnectorEvents {
+    private readonly enqueueCallback;
+    /**
+     * @param enqueueCallback Queues a callback that calls the number of handlers
+     *   `callbacks` reports for the handlers registered at that moment.
+     */
+    constructor(enqueueCallback: (callback: () => void, callbacks: () => number) => void);
     private readonly errorHandlers;
     private readonly disconnectedHandlers;
     private readonly stateHandlers;
     onError(handler: (error: ZlinkStreamError, signal?: AbortSignal) => Promise<void> | void): Disposable;
     onDisconnected(handler: (signal?: AbortSignal) => Promise<void> | void): Disposable;
     onStateChanged(handler: (change: ZlinkStreamConnectionStateChanged, signal?: AbortSignal) => Promise<void> | void): Disposable;
-    publishError(error: ZlinkStreamError, signal?: AbortSignal): Promise<void>;
-    publishDisconnected(signal?: AbortSignal): Promise<void>;
-    publishStateChanged(change: ZlinkStreamConnectionStateChanged, signal?: AbortSignal): Promise<void>;
+    publishError(error: ZlinkStreamError, signal?: AbortSignal): void;
+    publishDisconnected(signal?: AbortSignal): void;
+    publishStateChanged(change: ZlinkStreamConnectionStateChanged, signal?: AbortSignal): void;
+    /**
+     * Spec stream-connector 32 §7: the connector runs a registered callback and
+     * does not wait for it to finish. A thrown or rejected failure reaches the
+     * error handlers as `UserCallbackFailed`.
+     */
+    runUserCallback(run: () => Promise<void> | void, failureMessage: string, signal?: AbortSignal): void;
     private publish;
+    private reportFailure;
+    private reportToRemaining;
+    private invoke;
 }

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

@@ -4,7 +4,7 @@ import type { ZlinkStreamCloseReason } from '../Contracts';
 import type { ZlinkStreamConnectorEvents } from './ZlinkStreamConnectorEvents';
 import type { ZlinkStreamFrameSender } from './ZlinkStreamFrameSender';
 import type { ZlinkStreamPendingRequests } from './ZlinkStreamPendingRequests';
-import type { ZlinkStreamReceiveDispatcher } from './ZlinkStreamReceiveDispatcher';
+import { type ZlinkStreamReceiveDispatcher } from './ZlinkStreamReceiveDispatcher';
 import type { ZlinkStreamReceivedMessages } from './ZlinkStreamReceivedMessages';
 import type { ZlinkStreamActors } from './ZlinkStreamActors';
 export declare class ZlinkStreamConnectorLifecycle {
@@ -27,6 +27,7 @@ export declare class ZlinkStreamConnectorLifecycle {
     private lastInboundAt;
     private closeTask;
     private connectTask;
+    private connectAbort;
     private disconnectTask;
     private closeRequested;
     private disconnectedPublished;
@@ -37,7 +38,20 @@ export declare class ZlinkStreamConnectorLifecycle {
     get state(): ZlinkStreamConnectionState;
     get closeReason(): ZlinkStreamCloseReason | undefined;
     connect(signal?: AbortSignal): Promise<void>;
+    /**
+     * Spec stream-connector 32 §7: close does not wait for a connect attempt or a
+     * reconnect delay to run its course. The attempts listen to one controller
+     * the lifecycle owns; close aborts it, and the caller's signal is forwarded
+     * to it.
+     */
     private connectOnce;
+    /**
+     * Spec stream-connector 32 §7: a `close` called outside the registered
+     * handlers and callbacks returns once the close work has ended. One called
+     * from inside them returns right after starting it; the result goes to the
+     * outside caller, so a callback never waits for the close of the path that
+     * is running it.
+     */
     close(signal?: AbortSignal): Promise<void>;
     serverClosing(reason: ZlinkStreamCloseReason): Promise<void>;
     private closeOnce;
@@ -64,9 +78,21 @@ export declare class ZlinkStreamConnectorLifecycle {
     private releaseReceiveLoopSettled;
     private shouldContinueReceiveLoop;
     private runHeartbeatTick;
+    /**
+     * @param reason Given only where the reason is not read from `error`: a
+     *   server `session-closing` and the heartbeat timeout. Every other ending
+     *   takes it from {@link closeReasonFor}.
+     */
     private disconnectForTransportFailure;
     private isCurrentConnection;
-    /** Transport teardown only — no application callback runs from here. */
+    /**
+     * Ends the current connection, for close and for transport loss alike. No
+     * application callback runs from here. Spec stream-connector 32 §7 and §9:
+     * every operation the ending connection fails (the frames it has not
+     * written, the one it is writing and the pending requests) fails with
+     * `Disconnected`, whatever ended it; the cause stays in the close reason.
+     * The transport is closed without waiting for the frames.
+     */
     private tearDownConnection;
     /**
      * Runs once the teardown promise has settled, so a handler reached from here
@@ -78,35 +104,13 @@ export declare class ZlinkStreamConnectorLifecycle {
      */
     private announceDisconnect;
     private shouldReconnect;
-    private claimDisconnectedPublish;
-    private publishDisconnectedOnce;
     /**
-     * Spec stream-connector 32 §7: the connector runs the registered handler, it
-     * does not wait for it to finish. `close` returns once its own work is done —
-     * the drain, the transport close, the pending requests — having run the
-     * disconnect handler but without looking at whether that handler has ended.
-     *
-     * Starting the publish without awaiting it still runs every handler right
-     * here: an `async` function body runs synchronously up to its first `await`,
-     * and `publishDisconnected` reaches each handler before that point. So the
-     * handler has run by the time `close` returns, which is what the spec asks
-     * for, while a handler that calls `close` no longer waits for the very
-     * `closeTask` it is running inside. Java and C++ hand the handler to a queue
-     * and return the same way.
-     *
-     * `claimDisconnectedPublish` is taken by the same call and before any await,
-     * so deferring the completion never turns the one notification into two.
-     *
-     * Nothing awaits the promise, so a rejection would reach the process as an
-     * unhandled rejection and kill it. Handler failures are already contained
-     * where they were before this call stopped waiting — the `Promise.allSettled`
-     * in `publishDisconnected` — and this `catch` covers what is left rather than
-     * reporting the same failure a second time on the error surface.
+     * Spec stream-connector 32 §6 and §7: one disconnect notification per
+     * lifecycle event, handed to the dispatch queue. The connector does not wait
+     * for the handler; `Manual` runs it when the application pumps dispatch.
+     * The flag is tested and set synchronously, so concurrent callers for the
+     * same event claim it once.
      */
-    private publishDisconnectedWithoutWaiting;
-    private queueDisconnected;
-    private queueState;
+    private publishDisconnected;
     private setState;
-    private transitionState;
-    private publishStateChange;
 }

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

@@ -1,11 +1,27 @@
-import type { ZlinkStreamConnection, ZlinkStreamEncodedPayload, ZlinkStreamMetadata, ZlinkStreamMessageKind } from '../Contracts';
+import type { ZlinkStreamConnection, ZlinkStreamEncodedPayload, ZlinkStreamError, ZlinkStreamMetadata, ZlinkStreamMessageKind } from '../Contracts';
 import type { ZlinkStreamFrameProtocol } from './Protocol/ZlinkStreamFrameProtocol';
 export declare class ZlinkStreamFrameSender {
     private readonly protocol;
-    private readonly pendingWrites;
+    private readonly queues;
     constructor(protocol: ZlinkStreamFrameProtocol);
-    send(connection: ZlinkStreamConnection, kind: ZlinkStreamMessageKind, name: string, payload: ZlinkStreamEncodedPayload, metadata: ZlinkStreamMetadata, compress: boolean, requestSeq: bigint | undefined, signal?: AbortSignal, correlationId?: string, actorSlot?: number): Promise<void>;
-    sendControl(connection: ZlinkStreamConnection, name: string, signal?: AbortSignal): Promise<void>;
-    drain(signal?: AbortSignal): Promise<void>;
+    send(connection: ZlinkStreamConnection, kind: ZlinkStreamMessageKind, name: string, payload: ZlinkStreamEncodedPayload, metadata: ZlinkStreamMetadata, compress: boolean, requestSeq: bigint | undefined, signal?: AbortSignal, correlationId?: string, actorSlot?: number, expiry?: Promise<unknown>, onAccepted?: () => void): Promise<void>;
+    /**
+     * Writes a control frame (heartbeat ping or pong). A control frame belongs to
+     * no operation: its write failure ends the connection through the write
+     * queue like any other write (spec stream-connector 32 §9), and a connection
+     * that has already ended does not write it. The promise settles when the
+     * write has ended either way.
+     */
+    sendControl(connection: ZlinkStreamConnection, name: string): Promise<void>;
+    /**
+     * Gives a connection that has just been established its own write queue.
+     * `writeFailed` ends that connection when one of its transport writes fails.
+     */
+    open(connection: ZlinkStreamConnection, writeFailed: (error: ZlinkStreamError) => void): void;
+    /**
+     * Ends the write queue of a connection that has ended, by close and by
+     * transport loss alike. Every operation still in it fails with `error`.
+     */
+    failUnwritten(connection: ZlinkStreamConnection, error: unknown): void;
     private write;
 }

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

@@ -2,13 +2,13 @@ import { ZlinkStreamEncodedPayload, ZlinkStreamError, ZlinkStreamMessage, ZlinkS
 export interface PendingZlinkStreamRequest {
     readonly requestSeq: bigint;
     readonly promise: Promise<ZlinkStreamMessage<ZlinkStreamEncodedPayload>>;
+    startTimeout(): void;
 }
 export declare class ZlinkStreamPendingRequests {
     private nextRequestSeq;
     private readonly active;
-    get count(): number;
     create(packetName: string, timeoutMs: number): PendingZlinkStreamRequest;
-    resolve(requestSeq: bigint, value: ZlinkStreamEncodedPayload, metadata: ZlinkStreamMetadata): boolean;
+    resolve(requestSeq: bigint, value: () => ZlinkStreamEncodedPayload, metadata: ZlinkStreamMetadata): boolean;
     reject(requestSeq: bigint, error: ZlinkStreamError): boolean;
     cancel(requestSeq: bigint): void;
     failAll(error: ZlinkStreamError): void;

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

@@ -1,4 +1,4 @@
-import type { ZlinkStreamConnection } from '../Contracts';
+import type { ZlinkStreamConnection, ZlinkStreamError } from '../Contracts';
 import type { ZlinkStreamFrameProtocol } from './Protocol/ZlinkStreamFrameProtocol';
 import type { ZlinkStreamConnectorEvents } from './ZlinkStreamConnectorEvents';
 import type { ZlinkStreamFrameSender } from './ZlinkStreamFrameSender';
@@ -6,6 +6,18 @@ import type { ZlinkStreamPendingRequests } from './ZlinkStreamPendingRequests';
 import type { ZlinkStreamReceivedMessages } from './ZlinkStreamReceivedMessages';
 import type { ZlinkStreamCloseReason } from '../Contracts';
 import { type ZlinkStreamActors } from './ZlinkStreamActors';
+/**
+ * Spec stream-connector 32 §9: the one mapping from the error that ended a
+ * connection to its close reason. A frame or header the connector cannot
+ * decode and a payload over the receive limit are protocol violations; every
+ * other failure — a transport read or write — is a transport error.
+ */
+export declare function closeReasonFor(error: ZlinkStreamError): ZlinkStreamCloseReason;
+/** A receive failure that ends the connection; {@link closeReasonFor} names its reason. */
+export declare class ZlinkStreamConnectionEnd extends Error {
+    readonly error: ZlinkStreamError;
+    constructor(error: ZlinkStreamError);
+}
 export interface ZlinkStreamReceiveResult {
     readonly available: boolean;
     readonly inbound: boolean;
@@ -28,11 +40,15 @@ export declare class ZlinkStreamReceiveDispatcher {
      *   the recheck the rest of a dead connection's batch lands on the new
      *   connection's state, and the §10 arrival counts, which start at 0 when a
      *   connection is established, take the stale frames on top.
-     * @param connectionForSend Resolves the connection a reply belongs on at the
-     *   moment it is written. The captured `connection` is the one the batch was
-     *   read from, which a reconnect may already have replaced.
      */
-    readAndDispatch(connection: ZlinkStreamConnection | undefined, signal?: AbortSignal, isCurrent?: () => boolean, connectionForSend?: () => ZlinkStreamConnection): Promise<ZlinkStreamReceiveResult>;
+    readAndDispatch(connection: ZlinkStreamConnection | undefined, signal?: AbortSignal, isCurrent?: () => boolean): Promise<ZlinkStreamReceiveResult>;
+    /**
+     * Spec stream-connector 32 §4.7 and §9: a decompressed payload over the
+     * receive limit is `FrameTooLarge` and ends the connection as a protocol
+     * error, like a wire payload over the limit. A payload that does not
+     * decompress fails only its packet.
+     */
+    private decodePayload;
     private dispatch;
     private dispatchControl;
 }

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

@@ -13,9 +13,9 @@ export declare class ZlinkStreamReceivedMessages {
     private readonly handlers;
     private readonly observers;
     private readonly queue;
+    private readonly deliverable;
     private queueHead;
     private queuedCount;
-    private drainTask;
     private draining;
     private readonly receivedCounts;
     /**
@@ -25,7 +25,11 @@ export declare class ZlinkStreamReceivedMessages {
      *   queue in both modes, so they never depend on this flag.
      */
     constructor(events: ZlinkStreamConnectorEvents, deliverOnArrival: boolean);
-    on(name: string, handler: EncodedMessageHandler): Disposable;
+    /**
+     * @param actor The Actor handle that registers the handler, if any. Its
+     *   handler receives only that Actor's packets.
+     */
+    on(name: string, handler: EncodedMessageHandler, actor?: object): Disposable;
     /**
      * Registers a wait surface over the receive queue. Spec stream-connector 32
      * §7: these are not registered callbacks — they observe and consume the
@@ -74,25 +78,42 @@ export declare class ZlinkStreamReceivedMessages {
      */
     connectionEnded(): void;
     enqueue(message: ZlinkStreamMessage<ZlinkStreamEncodedPayload>, signal?: AbortSignal): void;
-    enqueueCallback(callback: () => Promise<void> | void): void;
+    /**
+     * @param callbacks The number of handler calls `callback` makes when it runs
+     *   with the handlers registered at that moment; a callback that runs a set
+     *   of handlers reads the set's size. One callback by default.
+     */
+    enqueueCallback(callback: () => Promise<void> | void, callbacks?: () => number): void;
     /**
      * Runs the registered handlers the receive path left queued. `Manual` calls
-     * this from `dispatch`; `Immediate` has already drained on arrival.
+     * this from `dispatch`; `Immediate` drains on arrival.
      *
-     * A handler that calls `dispatch` arrives back here from inside the drain it
-     * was started by. `scheduleDrain` would find `drainTask` already set and
-     * return, and the await below would then be the drain waiting on itself —
-     * a deadlock with neither timeout nor error. The drain loop already takes
-     * every message a handler exists for, so there is nothing a second drain
-     * would deliver and returning is the whole of the correct behaviour.
+     * The drain is synchronous: the connector does not wait for a handler
+     * (spec stream-connector 32 §7), so nothing inside it awaits. A handler that
+     * calls `dispatch` arrives back here from inside the drain it was started by;
+     * the running loop already takes every deliverable entry, so returning is the
+     * whole of the correct behaviour.
      */
-    pump(): Promise<void>;
+    pump(): void;
+    /**
+     * True while a registered callback runs from {@link pump}: the execution
+     * context spec stream-connector 32 §7 calls "inside a handler".
+     */
+    get dispatching(): boolean;
+    get pendingCallbacks(): number;
     private offerQueued;
-    private scheduleDrain;
-    private drain;
     private removeAt;
     private findDeliverableIndex;
-    private hasQueuedMessage;
+    private indexDeliverable;
+    private isDeliverable;
+    /**
+     * Spec stream-connector 32 §7 and §10: the handlers that receive `message`
+     * are the connector handlers for its name and the handle handlers of the
+     * Actor it carries. A packet no handler receives stays in the queue for the
+     * wait surfaces. This is the one place that decides it.
+     */
+    private receiversOf;
+    private removeDeliverable;
     private advanceHead;
     private compactQueue;
 }