@zlink-systems/stream-connector 0.10.0

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

@@ -0,0 +1,44 @@
+import { ZlinkStreamConnection, ZlinkStreamTransportFactory } from '../../Contracts';
+import type { RequiredZlinkStreamConnectorOptions } from '../../Contracts';
+interface BrowserWebSocketEventMap {
+    open: unknown;
+    close: unknown;
+    error: unknown;
+    message: {
+        readonly data: unknown;
+    };
+}
+interface BrowserWebSocket {
+    binaryType: string;
+    readonly readyState: number;
+    send(data: Uint8Array): void;
+    close(): void;
+    addEventListener<TKey extends keyof BrowserWebSocketEventMap>(type: TKey, listener: (event: BrowserWebSocketEventMap[TKey]) => void, options?: {
+        readonly once?: boolean;
+    }): void;
+    removeEventListener<TKey extends keyof BrowserWebSocketEventMap>(type: TKey, listener: (event: BrowserWebSocketEventMap[TKey]) => void): void;
+}
+export declare class BrowserStreamTransportFactory implements ZlinkStreamTransportFactory {
+    connect(options: RequiredZlinkStreamConnectorOptions, signal?: AbortSignal): Promise<ZlinkStreamConnection>;
+}
+export declare class BrowserWebSocketConnection implements ZlinkStreamConnection {
+    private readonly socket;
+    private readonly messages;
+    private messageHead;
+    private closed;
+    private error;
+    private readWaiter;
+    constructor(socket: BrowserWebSocket);
+    write(frame: Uint8Array, signal?: AbortSignal): Promise<void>;
+    read(signal?: AbortSignal): Promise<Uint8Array | undefined>;
+    close(signal?: AbortSignal): Promise<void>;
+    private readonly onMessage;
+    private readonly onClose;
+    private readonly onError;
+    private waitForMessage;
+    private wakeReader;
+    private removeListeners;
+    private hasQueuedMessage;
+    private takeMessage;
+}
+export {};

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

@@ -0,0 +1,3 @@
+import { ZlinkStreamTransport } from '../../Contracts';
+export declare function inferTransport(endpoint: string): ZlinkStreamTransport;
+export declare function parseEndpoint(endpoint: string): URL;

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

@@ -0,0 +1,15 @@
+import type { ZlinkFlowOrigin } from '../Contracts';
+export interface ZlinkFlowContextValue {
+    readonly flowId: string;
+    readonly flowOrigin: ZlinkFlowOrigin;
+}
+export interface ZlinkFlowContext {
+    currentOrCreate(explicit?: ZlinkFlowContextValue): ZlinkFlowContextValue;
+    createInbound(flowId?: string, flowOrigin?: ZlinkFlowOrigin): ZlinkFlowContextValue;
+}
+export declare class BrowserZlinkFlowContext implements ZlinkFlowContext {
+    currentOrCreate(explicit?: ZlinkFlowContextValue): ZlinkFlowContextValue;
+    createInbound(flowId?: string, flowOrigin?: ZlinkFlowOrigin): ZlinkFlowContextValue;
+    private createUuidV7;
+}
+export declare function formatUuidV7(bytes: Uint8Array): string;

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

@@ -0,0 +1,7 @@
+import { type ZlinkStreamError } from '../Contracts';
+export interface ZlinkStreamAssertions {
+    ensure(condition: boolean, message: string): asserts condition;
+    expectFailure(action: (signal?: AbortSignal) => Promise<void>, errorKind?: string): Promise<ZlinkStreamError>;
+    expectTimeout(action: (signal?: AbortSignal) => Promise<void>): Promise<void>;
+}
+export declare const zlinkStreamAssert: ZlinkStreamAssertions;

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

@@ -0,0 +1,63 @@
+import { Disposable, RequiredZlinkStreamConnectorOptions, ZlinkStreamConnectionState, ZlinkStreamConnectionStateChanged, ZlinkStreamConnector, ZlinkStreamConnectorOptions, ZlinkStreamDiagnosticsLevel, ZlinkStreamEncodedPayload, ZlinkStreamError, ZlinkStreamExpectNoneCall, ZlinkStreamFlow, ZlinkStreamInboundObservation, 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";
+    private readonly receivedMessages;
+    private readonly lifecycle;
+    private readonly events;
+    private correlationCounter;
+    private readonly pendingRequests;
+    private readonly frameSender;
+    private readonly receiveDispatcher;
+    private readonly inboundObservers;
+    private readonly diagnosticsLevelCell;
+    readonly options: RequiredZlinkStreamConnectorOptions;
+    constructor(options: ZlinkStreamConnectorOptions);
+    get isConnected(): boolean;
+    get closeReason(): import("..").ZlinkStreamCloseReason | undefined;
+    get state(): ZlinkStreamConnectionState;
+    get pendingDispatchCount(): number;
+    /**
+     * Current diagnostics level (spec 26 §4.1, spec stream-connector 32 §13).
+     * Reflects the level set by the most recent {@link setDiagnosticsLevel}
+     * call, or the construction-time option (default
+     * {@link ZlinkStreamDiagnosticsLevel.Errors}) if it was never changed.
+     */
+    get diagnosticsLevel(): ZlinkStreamDiagnosticsLevel;
+    /**
+     * Changes the diagnostics level in place without recreating the connector
+     * (spec 26 §4.1, spec stream-connector 32 §13). The change is an atomic
+     * state update: it applies to processing points that read the level after
+     * this call returns and is never applied retroactively to frames already
+     * built. Rejects unknown values with {@link ZlinkStreamErrorCode.ConfigurationError}.
+     * Do not call this synchronous bridge from a framework execution context such
+     * as a handler or callback; use setDiagnosticsLevelAsync there.
+     */
+    setDiagnosticsLevel(level: ZlinkStreamDiagnosticsLevel): void;
+    setDiagnosticsLevelAsync(level: ZlinkStreamDiagnosticsLevel): Promise<void>;
+    onErrorReceived(handler: (error: ZlinkStreamError, signal?: AbortSignal) => Promise<void> | void): Disposable;
+    onDisconnected(handler: (signal?: AbortSignal) => Promise<void> | void): Disposable;
+    onConnectionStateChanged(handler: (change: ZlinkStreamConnectionStateChanged, signal?: AbortSignal) => Promise<void> | void): Disposable;
+    connect(signal?: AbortSignal): Promise<void>;
+    close(signal?: AbortSignal): Promise<void>;
+    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>;
+    waitForSequence<TPayload = ZlinkStreamEncodedPayload>(name: string): ZlinkStreamSequenceCall<TPayload>;
+    waitForMessage<TPayload>(name: string, timeoutMs: number, predicate: (message: ZlinkStreamMessage<TPayload>) => boolean, signal?: AbortSignal): Promise<ZlinkStreamMessage<TPayload>>;
+    private encodePayload;
+    private decodePayload;
+    private decodeWaitPayload;
+    sendEncoded(kind: ZlinkStreamMessageKind, name: string, payload: ZlinkStreamEncodedPayload, metadata: ZlinkStreamMetadata, compress: boolean, requestSeq: bigint | undefined, signal?: AbortSignal, flow?: ZlinkStreamFlow, correlationId?: string): Promise<void>;
+    /**
+     * Per-connector monotonic correlation id (hex). The client generates it on each request
+     * and the server echoes it back on the reply, so flows can be joined across the wire.
+     */
+    private nextCorrelationId;
+    requestEncoded(name: string, payload: ZlinkStreamEncodedPayload, metadata: ZlinkStreamMetadata, compress: boolean, timeoutMs: number, signal?: AbortSignal, flow?: ZlinkStreamFlow): Promise<ZlinkStreamEncodedPayload>;
+    private resolveNameOrDefault;
+}

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

@@ -0,0 +1,13 @@
+import type { Disposable, ZlinkStreamConnectionStateChanged, ZlinkStreamError } from '../Contracts';
+export declare class ZlinkStreamConnectorEvents {
+    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>;
+    private publish;
+}

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

@@ -0,0 +1,55 @@
+import type { RequiredZlinkStreamConnectorOptions, ZlinkStreamConnection } from '../Contracts';
+import { ZlinkStreamConnectionState } from '../Contracts';
+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 { ZlinkStreamRuntimeMetrics } from './ZlinkStreamRuntimeMetrics';
+export declare class ZlinkStreamConnectorLifecycle {
+    private readonly options;
+    private readonly pendingRequests;
+    private readonly frameSender;
+    private readonly receiveDispatcher;
+    private readonly events;
+    private readonly metrics;
+    private receiveLoopAbort;
+    private currentConnection;
+    private connectionGeneration;
+    private currentState;
+    private heartbeatTimer;
+    private lastInboundAt;
+    private closeTask;
+    private connectTask;
+    private disconnectTask;
+    private closeRequested;
+    private disconnectedPublished;
+    private closeReasonValue?;
+    private lateConnectCleanupError;
+    constructor(options: RequiredZlinkStreamConnectorOptions, pendingRequests: ZlinkStreamPendingRequests, frameSender: ZlinkStreamFrameSender, receiveDispatcher: ZlinkStreamReceiveDispatcher, events: ZlinkStreamConnectorEvents, metrics: ZlinkStreamRuntimeMetrics);
+    get isConnected(): boolean;
+    get state(): ZlinkStreamConnectionState;
+    get closeReason(): ZlinkStreamCloseReason | undefined;
+    connect(signal?: AbortSignal): Promise<void>;
+    private connectOnce;
+    close(signal?: AbortSignal): Promise<void>;
+    serverClosing(reason: ZlinkStreamCloseReason): Promise<void>;
+    private closeOnce;
+    dispatch(signal?: AbortSignal): Promise<void>;
+    connectionForSend(): ZlinkStreamConnection;
+    private dispatchAvailable;
+    private connectWithReconnect;
+    private startHeartbeat;
+    private stopHeartbeat;
+    private startReceiveLoop;
+    private stopReceiveLoop;
+    private runReceiveLoop;
+    private shouldContinueReceiveLoop;
+    private runHeartbeatTick;
+    private disconnectForTransportFailure;
+    private isCurrentConnection;
+    private disconnectOnce;
+    private shouldReconnect;
+    private publishDisconnectedOnce;
+    private setState;
+}

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

@@ -0,0 +1,3 @@
+import { RequiredZlinkStreamConnectorOptions, ZlinkStreamConnectorOptions, ZlinkStreamDiagnosticsLevel } from '../Contracts';
+export declare function normalizeOptions(options: ZlinkStreamConnectorOptions, defaultTransportFactory: RequiredZlinkStreamConnectorOptions['transportFactory']): RequiredZlinkStreamConnectorOptions;
+export declare function validateDiagnosticsLevel(level: ZlinkStreamDiagnosticsLevel | undefined): void;

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

@@ -0,0 +1,16 @@
+import { ZlinkStreamDiagnosticsLevel } from '../Contracts';
+/**
+ * Mutable holder for the connector's current diagnostics level (spec 26 §4.1,
+ * spec stream-connector 32 §13). The application can read and change the
+ * level at runtime without recreating the connector. Each processing point
+ * reads {@link level} exactly once and uses that value for the whole
+ * operation; the change takes effect for processing points that read the
+ * cell after the change and is never applied retroactively to frames already
+ * built.
+ */
+export declare class ZlinkStreamDiagnosticsLevelCell {
+    private current;
+    constructor(initial: ZlinkStreamDiagnosticsLevel);
+    get level(): ZlinkStreamDiagnosticsLevel;
+    set(level: ZlinkStreamDiagnosticsLevel): void;
+}

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

@@ -0,0 +1,15 @@
+import type { ZlinkStreamConnection, ZlinkStreamEncodedPayload, ZlinkStreamFlow, ZlinkStreamMetadata, ZlinkStreamMessageKind } from '../Contracts';
+import type { ZlinkStreamFrameProtocol } from './Protocol/ZlinkStreamFrameProtocol';
+import type { ZlinkFlowContext } from './ZlinkFlowContext';
+import type { ZlinkStreamRuntimeMetrics } from './ZlinkStreamRuntimeMetrics';
+export declare class ZlinkStreamFrameSender {
+    private readonly protocol;
+    private readonly flowContext;
+    private readonly metrics;
+    private readonly pendingWrites;
+    constructor(protocol: ZlinkStreamFrameProtocol, flowContext: ZlinkFlowContext, metrics: ZlinkStreamRuntimeMetrics);
+    send(connection: ZlinkStreamConnection, kind: ZlinkStreamMessageKind, name: string, payload: ZlinkStreamEncodedPayload, metadata: ZlinkStreamMetadata, compress: boolean, requestSeq: bigint | undefined, signal?: AbortSignal, correlationId?: string, explicitFlow?: ZlinkStreamFlow): Promise<void>;
+    sendControl(connection: ZlinkStreamConnection, name: string, signal?: AbortSignal): Promise<void>;
+    drain(signal?: AbortSignal): Promise<void>;
+    private write;
+}

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

@@ -0,0 +1,25 @@
+import { Disposable, ZlinkStreamInboundObservation } from '../Contracts';
+import type { ZlinkStreamHeader } from '../Contracts/ZlinkStreamModels';
+import type { ZlinkStreamConnectorEvents } from './ZlinkStreamConnectorEvents';
+type InboundObserver = (observation: ZlinkStreamInboundObservation, signal?: AbortSignal) => Promise<void> | void;
+export declare class ZlinkStreamInboundObservers {
+    private readonly maxNotifications;
+    private readonly maxPayloadPreviewBytes;
+    private readonly events;
+    private readonly observers;
+    private readonly queue;
+    private queueHead;
+    private queuedCount;
+    private draining;
+    private dropReportPending;
+    constructor(maxNotifications: number, maxPayloadPreviewBytes: number, events: ZlinkStreamConnectorEvents);
+    add(observer: InboundObserver): Disposable;
+    enqueue(header: ZlinkStreamHeader, payload: Uint8Array, signal?: AbortSignal): void;
+    private createObservation;
+    private scheduleDrain;
+    private drain;
+    private reportDropped;
+    private reportObserverFailed;
+    private takeObservation;
+}
+export {};

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

@@ -0,0 +1,15 @@
+import { ZlinkStreamEncodedPayload, ZlinkStreamError } from '../Contracts';
+export interface PendingZlinkStreamRequest {
+    readonly requestSeq: bigint;
+    readonly promise: Promise<ZlinkStreamEncodedPayload>;
+}
+export declare class ZlinkStreamPendingRequests {
+    private nextRequestSeq;
+    private readonly active;
+    get count(): number;
+    create(packetName: string, timeoutMs: number): PendingZlinkStreamRequest;
+    resolve(requestSeq: bigint, value: ZlinkStreamEncodedPayload): boolean;
+    reject(requestSeq: bigint, error: ZlinkStreamError): boolean;
+    cancel(requestSeq: bigint): void;
+    failAll(error: ZlinkStreamError): void;
+}

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

@@ -0,0 +1,29 @@
+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';
+import type { ZlinkStreamCloseReason } from '../Contracts';
+import type { ZlinkStreamRuntimeMetrics } from './ZlinkStreamRuntimeMetrics';
+export interface ZlinkStreamReceiveResult {
+    readonly available: boolean;
+    readonly inbound: boolean;
+}
+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);
+    readAndDispatch(connection: ZlinkStreamConnection | undefined, signal?: AbortSignal, isCurrent?: () => boolean): Promise<ZlinkStreamReceiveResult>;
+    private dispatch;
+    private dispatchControl;
+}

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

@@ -0,0 +1,24 @@
+import { Disposable, ZlinkStreamEncodedPayload, ZlinkStreamMessage } from '../Contracts';
+import type { ZlinkStreamConnectorEvents } from './ZlinkStreamConnectorEvents';
+type EncodedMessageHandler = (message: ZlinkStreamMessage<ZlinkStreamEncodedPayload>, signal?: AbortSignal) => Promise<void> | void;
+export declare class ZlinkStreamReceivedMessages {
+    private readonly capacity;
+    private readonly events;
+    private readonly handlers;
+    private readonly queue;
+    private queueHead;
+    private queuedCount;
+    private drainTask;
+    private dropReportPending;
+    constructor(capacity: number, events: ZlinkStreamConnectorEvents);
+    on(name: string, handler: EncodedMessageHandler): Disposable;
+    enqueue(message: ZlinkStreamMessage<ZlinkStreamEncodedPayload>, signal?: AbortSignal): void;
+    private scheduleDrain;
+    private drain;
+    private findDeliverableIndex;
+    private hasQueuedMessage;
+    private advanceHead;
+    private compactQueue;
+    private reportDropped;
+}
+export {};

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

@@ -0,0 +1,17 @@
+import type { RequiredZlinkStreamConnectorOptions } from '../Contracts';
+export declare class ZlinkStreamRuntimeMetrics {
+    private readonly options;
+    private readonly reconnects;
+    private readonly handshakeDuration;
+    private readonly handshakeFailures;
+    private readonly inboundBytes;
+    private readonly outboundBytes;
+    constructor(options: RequiredZlinkStreamConnectorOptions);
+    reconnect(): void;
+    handshakeCompleted(startedAt: number): void;
+    handshakeFailed(error: unknown): void;
+    inbound(byteCount: number): void;
+    outbound(byteCount: number): void;
+    private transportLabel;
+    private safe;
+}

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

@@ -0,0 +1,16 @@
+import { Disposable, ZlinkStreamError, ZlinkStreamErrorCode, ZlinkStreamException } from '../Contracts';
+export declare function connectorError(code: ZlinkStreamErrorCode, message: string, cause?: unknown): ZlinkStreamException;
+export declare function toStreamError(cause: unknown, code: ZlinkStreamErrorCode, message: string): ZlinkStreamError;
+export declare function unwrapStreamError(error: unknown): ZlinkStreamError;
+export declare function subscription(dispose: () => void): Disposable;
+export declare function throwIfAborted(signal: AbortSignal | undefined): void;
+export declare function delay(delayMs: number, signal: AbortSignal | undefined): Promise<void>;
+export declare function readLength(source: Uint8Array, offset: number, bytes: 1 | 2, label: string): number;
+export declare function writeUInt16BE(destination: Uint8Array, offset: number, value: number): void;
+export declare function writeUInt32BE(destination: Uint8Array, offset: number, value: number): void;
+export declare function readUInt16BE(source: Uint8Array, offset: number): number;
+export declare function readUInt32BE(source: Uint8Array, offset: number): number;
+export declare function writeBigUInt64BE(destination: Uint8Array, offset: number, value: bigint): void;
+export declare function readBigUInt64BE(source: Uint8Array, offset: number): bigint;
+export declare function utf8Encode(value: string): Uint8Array;
+export declare function utf8Decode(value: Uint8Array): string;

package/dist/browser/index.d.ts

@@ -0,0 +1,8 @@
+export * from './Contracts';
+export { DefaultZlinkStreamConnector, } from './Runtime/ZlinkStreamConnector';
+export { zlinkStreamAssert } from './Runtime/ZlinkStreamAssertions';
+import { DefaultZlinkStreamConnector } from './Runtime/ZlinkStreamConnector';
+import type { ZlinkStreamConnectorOptions } from './Contracts';
+export declare const zlinkStreamConnectorFactory: {
+    create(options: ZlinkStreamConnectorOptions): DefaultZlinkStreamConnector;
+};