@kyneta/websocket-transport 1.3.1 → 1.5.0

package/dist/client-transport-D3tYQYrS.d.ts

@@ -0,0 +1,134 @@
+import { c as WebSocketConstructor, d as WebsocketClientState, f as WebsocketClientStateTransition, t as DisconnectReason } from "./types-c1S_xIRG.js";
+import { GeneratedChannel, PeerId, Transport, TransportFactory } from "@kyneta/transport";
+import { TransitionListener as TransitionListener$1 } from "@kyneta/machine";
+
+//#region src/client-transport.d.ts
+/**
+ * Default fragment threshold in bytes.
+ * AWS API Gateway has a 128KB limit, so 100KB provides a safe margin.
+ */
+declare const DEFAULT_FRAGMENT_THRESHOLD: number;
+/**
+ * Options for the Websocket client transport (browser connections).
+ */
+interface WebsocketClientOptions {
+  /** Websocket URL to connect to. Can be a string or a function of peerId. */
+  url: string | ((peerId: PeerId) => string);
+  /**
+   * WebSocket constructor — caller must provide explicitly.
+   *
+   * In browsers, pass the global `WebSocket`. In Node.js, pass `ws`'s
+   * `WebSocket`. In Bun, pass `globalThis.WebSocket`. The transport
+   * never probes `globalThis` on its own.
+   */
+  WebSocket: WebSocketConstructor;
+  /**
+   * Headers to send during Websocket upgrade.
+   * Used for authentication in service-to-service communication.
+   *
+   * Note: Headers are a Bun/Node-specific extension. The browser WebSocket
+   * API does not support custom headers per the WHATWG spec.
+   */
+  headers?: Record<string, string>;
+  /** Reconnection options. */
+  reconnect?: {
+    enabled?: boolean;
+    maxAttempts?: number;
+    baseDelay?: number;
+    maxDelay?: number;
+  };
+  /** Keepalive interval in ms (default: 30000). */
+  keepaliveInterval?: number;
+  /**
+   * Fragment threshold in bytes. Messages larger than this are fragmented.
+   * Set to 0 to disable fragmentation (not recommended for cloud deployments).
+   * Default: 100KB
+   */
+  fragmentThreshold?: number;
+  /** Lifecycle event callbacks. */
+  lifecycle?: WebsocketClientLifecycleEvents;
+}
+/**
+ * Lifecycle event callbacks for the Websocket client.
+ */
+interface WebsocketClientLifecycleEvents {
+  /** Called on every state transition (delivered async via microtask). */
+  onStateChange?: (transition: WebsocketClientStateTransition) => void;
+  /** Called when the connection is lost. */
+  onDisconnect?: (reason: DisconnectReason) => void;
+  /** Called when a reconnection attempt is scheduled. */
+  onReconnecting?: (attempt: number, nextAttemptMs: number) => void;
+  /** Called when reconnection succeeds after a previous connection. */
+  onReconnected?: () => void;
+  /** Called when the server sends the "ready" signal. */
+  onReady?: () => void;
+}
+/**
+ * Websocket client network transport for @kyneta/exchange.
+ *
+ * Connects to a Websocket server, sends and receives ChannelMsg via
+ * the kyneta wire format (CBOR codec + framing + fragmentation).
+ *
+ * Internally, the connection lifecycle is a `Program<Msg, Model, Fx>` —
+ * a pure Mealy machine whose transitions are deterministically testable.
+ * This class is the imperative shell that interprets data effects as I/O.
+ *
+ * Prefer the factory functions for construction:
+ * - `createWebsocketClient()` — browser-to-server (from `./browser`)
+ * - `createServiceWebsocketClient()` — service-to-service with headers (from `./server`)
+ */
+declare class WebsocketClientTransport extends Transport<void> {
+  #private;
+  constructor(options: WebsocketClientOptions);
+  /**
+   * Get the current connection state.
+   */
+  getState(): WebsocketClientState;
+  /**
+   * Subscribe to state transitions.
+   */
+  subscribeToTransitions(listener: TransitionListener$1<WebsocketClientState>): () => void;
+  /**
+   * Wait for a specific state.
+   */
+  waitForState(predicate: (state: WebsocketClientState) => boolean, options?: {
+    timeoutMs?: number;
+  }): Promise<WebsocketClientState>;
+  /**
+   * Wait for a specific status.
+   */
+  waitForStatus(status: WebsocketClientState["status"], options?: {
+    timeoutMs?: number;
+  }): Promise<WebsocketClientState>;
+  /**
+   * Whether the client is ready (server ready signal received).
+   */
+  get isReady(): boolean;
+  protected generate(): GeneratedChannel;
+  onStart(): Promise<void>;
+  onStop(): Promise<void>;
+}
+/**
+ * Create a Websocket client transport factory for browser-to-server
+ * connections.
+ *
+ * Returns an `TransportFactory` — a closure that creates a fresh transport
+ * instance when called. Pass directly to `Exchange({ transports: [...] })`.
+ *
+ * @example
+ * ```typescript
+ * import { createWebsocketClient } from "@kyneta/websocket-transport/browser"
+ *
+ * const exchange = new Exchange({
+ *   transports: [createWebsocketClient({
+ *     url: "ws://localhost:3000/ws",
+ *     WebSocket,
+ *     reconnect: { enabled: true },
+ *   })],
+ * })
+ * ```
+ */
+declare function createWebsocketClient(options: WebsocketClientOptions): TransportFactory;
+//#endregion
+export { createWebsocketClient as a, WebsocketClientTransport as i, WebsocketClientLifecycleEvents as n, WebsocketClientOptions as r, DEFAULT_FRAGMENT_THRESHOLD as t };
+//# sourceMappingURL=client-transport-D3tYQYrS.d.ts.map

package/dist/client-transport-D3tYQYrS.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client-transport-D3tYQYrS.d.ts","names":[],"sources":["../src/client-transport.ts"],"mappings":";;;;;;;;;cAkEa,0BAAA;;;;UAKI,sBAAA;EAoBL;EAlBV,GAAA,aAAgB,MAAA,EAAQ,MAAA;EAuCkB;;;;;;;EA9B1C,SAAA,EAAW,oBAAA;EASD;;;;;;;EAAV,OAAA,GAAU,MAAA;EAqBV;EAlBA,SAAA;IACE,OAAA;IACA,WAAA;IACA,SAAA;IACA,QAAA;EAAA;EAyBsC;EArBxC,iBAAA;EAkB6B;;;;;EAX7B,iBAAA;EAiBkB;EAdlB,SAAA,GAAY,8BAAA;AAAA;;;;UAMG,8BAAA;EAmCqB;EAjCpC,aAAA,IAAiB,UAAA,EAAY,8BAAA;EAsDR;EAnDrB,YAAA,IAAgB,MAAA,EAAQ,gBAAA;EA0YO;EAvY/B,cAAA,IAAkB,OAAA,UAAiB,aAAA;EAgZd;EA7YrB,aAAA;EA+YG;EA5YH,OAAA;AAAA;;;;;;;;;;;;;;;cAqBW,wBAAA,SAAiC,SAAA;EAAA;cAqBhC,OAAA,EAAS,sBAAA;EAuVnB;;;EARF,QAAA,CAAA,GAAY,oBAAA;EAiBV;;;EAVF,sBAAA,CACE,QAAA,EAAU,oBAAA,CAAmB,oBAAA;EAWpB;;;EAHX,YAAA,CACE,SAAA,GAAY,KAAA,EAAO,oBAAA,cACnB,OAAA;IAAY,SAAA;EAAA,IACX,OAAA,CAAQ,oBAAA;EAUR;;;EAHH,aAAA,CACE,MAAA,EAAQ,oBAAA,YACR,OAAA;IAAY,SAAA;EAAA,IACX,OAAA,CAAQ,oBAAA;EA6CM;;;EAAA,IAtCb,OAAA,CAAA;EAAA,UAQM,QAAA,CAAA,GAAY,gBAAA;EA8BhB,OAAA,CAAA,GAAW,OAAA;EAUX,MAAA,CAAA,GAAU,OAAA;AAAA;;;;;;;;;;;;;;;;;;;;;iBA8BF,qBAAA,CACd,OAAA,EAAS,sBAAA,GACR,gBAAA"}

package/dist/server.d.ts

@@ -1,9 +1,8 @@
-import { PeerId, Channel, ChannelMsg, Transport, GeneratedChannel, TransportFactory } from '@kyneta/transport';
-import { S as Socket, g as WebsocketConnectionOptions, h as WebsocketConnectionResult } from './types-D0lbeevu.js';
-export { D as DisconnectReason, N as NodeWebsocketLike, R as READY_STATE, a as SocketReadyState, b as WebSocketCloseEvent, c as WebSocketConstructor, d as WebSocketLike, e as WebSocketMessageEvent, i as WebsocketConnectionHandle, w as wrapNodeWebsocket, j as wrapStandardWebsocket } from './types-D0lbeevu.js';
-import { a as WebsocketClientOptions } from './client-transport-DUAFjVbh.js';
-import '@kyneta/machine';
+import { _ as wrapStandardWebsocket, a as SocketReadyState, c as WebSocketConstructor, g as wrapNodeWebsocket, h as WebsocketConnectionResult, i as Socket, l as WebSocketLike, m as WebsocketConnectionOptions, n as NodeWebsocketLike, p as WebsocketConnectionHandle, r as READY_STATE, s as WebSocketCloseEvent, t as DisconnectReason, u as WebSocketMessageEvent } from "./types-c1S_xIRG.js";
+import { r as WebsocketClientOptions } from "./client-transport-D3tYQYrS.js";
+import { Channel, ChannelMsg, GeneratedChannel, PeerId, Transport, TransportFactory } from "@kyneta/transport";
 
+//#region src/connection.d.ts
 /**
  * Default fragment threshold in bytes.
  * Messages larger than this are fragmented for cloud infrastructure compatibility.
@@ -14,12 +13,12 @@ declare const DEFAULT_FRAGMENT_THRESHOLD: number;
  * Configuration for creating a WebsocketConnection.
  */
 interface WebsocketConnectionConfig {
-    /**
-     * Fragment threshold in bytes. Messages larger than this are fragmented.
-     * Set to 0 to disable fragmentation (not recommended for cloud deployments).
-     * Default: 100KB (safe for AWS API Gateway's 128KB limit)
-     */
-    fragmentThreshold?: number;
+  /**
+   * Fragment threshold in bytes. Messages larger than this are fragmented.
+   * Set to 0 to disable fragmentation (not recommended for cloud deployments).
+   * Default: 100KB (safe for AWS API Gateway's 128KB limit)
+   */
+  fragmentThreshold?: number;
 }
 /**
  * Represents a single Websocket connection to a peer (server-side).
@@ -31,53 +30,55 @@ interface WebsocketConnectionConfig {
  * the natural choice for Websocket's binary frame support.
  */
 declare class WebsocketConnection {
-    #private;
-    readonly peerId: PeerId;
-    readonly channelId: number;
-    constructor(peerId: PeerId, channelId: number, socket: Socket, config?: WebsocketConnectionConfig);
-    /**
-     * Set the channel reference.
-     * Called by the adapter when the channel is created.
-     * @internal
-     */
-    _setChannel(channel: Channel): void;
-    /**
-     * Start processing messages on this connection.
-     *
-     * Sets up the message handler on the socket. Must be called after
-     * the connection is fully set up (channel assigned, stored in adapter).
-     */
-    start(): void;
-    /**
-     * Send a ChannelMsg through the Websocket.
-     *
-     * Encodes via CBOR codec → frame → fragment if needed → socket.send().
-     */
-    send(msg: ChannelMsg): void;
-    /**
-     * Send a "ready" signal to the client.
-     *
-     * This is a transport-level text message that tells the client the
-     * server is ready to receive protocol messages. The client creates
-     * its channel and sends establish-request after receiving this.
-     */
-    sendReady(): void;
-    /**
-     * Close the connection and clean up resources.
-     */
-    close(code?: number, reason?: string): void;
+  #private;
+  readonly peerId: PeerId;
+  readonly channelId: number;
+  constructor(peerId: PeerId, channelId: number, socket: Socket, config?: WebsocketConnectionConfig);
+  /**
+   * Set the channel reference.
+   * Called by the adapter when the channel is created.
+   * @internal
+   */
+  _setChannel(channel: Channel): void;
+  /**
+   * Start processing messages on this connection.
+   *
+   * Sets up the message handler on the socket. Must be called after
+   * the connection is fully set up (channel assigned, stored in adapter).
+   */
+  start(): void;
+  /**
+   * Send a ChannelMsg through the Websocket.
+   *
+   * Pipeline: alias transformer → wire encode → frame → fragment if needed
+   * → socket.send().
+   */
+  send(msg: ChannelMsg): void;
+  /**
+   * Send a "ready" signal to the client.
+   *
+   * This is a transport-level text message that tells the client the
+   * server is ready to receive protocol messages. The client creates
+   * its channel and sends establish after receiving this.
+   */
+  sendReady(): void;
+  /**
+   * Close the connection and clean up resources.
+   */
+  close(code?: number, reason?: string): void;
 }
-
+//#endregion
+//#region src/server-transport.d.ts
 /**
  * Options for the Websocket server adapter.
  */
 interface WebsocketServerTransportOptions {
-    /**
-     * Fragment threshold in bytes. Messages larger than this are fragmented.
-     * Set to 0 to disable fragmentation (not recommended for cloud deployments).
-     * Default: 100KB (safe for AWS API Gateway's 128KB limit)
-     */
-    fragmentThreshold?: number;
+  /**
+   * Fragment threshold in bytes. Messages larger than this are fragmented.
+   * Set to 0 to disable fragmentation (not recommended for cloud deployments).
+   * Default: 100KB (safe for AWS API Gateway's 128KB limit)
+   */
+  fragmentThreshold?: number;
 }
 /**
  * Websocket server network adapter.
@@ -92,74 +93,75 @@ interface WebsocketServerTransportOptions {
  *
  * The connection handshake follows a two-phase protocol:
  * 1. Server sends text `"ready"` signal (transport-level)
- * 2. Client sends `establish-request` (protocol-level)
- * 3. Server responds with `establish-response` (handled by Synchronizer)
+ * 2. Client sends `establish` (protocol-level)
+ * 3. Server upgrades channel and sends present (handled by Synchronizer)
  *
  * The server does NOT call `establishChannel()` — it waits for the
- * client's establish-request to avoid a race condition where the binary
- * establish-request could arrive before the client has processed "ready".
+ * client's establish to avoid a race condition where the binary
+ * establish could arrive before the client has processed "ready".
  */
 declare class WebsocketServerTransport extends Transport<PeerId> {
-    #private;
-    constructor(options?: WebsocketServerTransportOptions);
-    protected generate(peerId: PeerId): GeneratedChannel;
-    onStart(): Promise<void>;
-    onStop(): Promise<void>;
-    /**
-     * Handle a new Websocket connection.
-     *
-     * Call this from your framework's Websocket upgrade handler.
-     * Returns a connection handle and a `start()` function that begins
-     * message processing and sends the "ready" signal.
-     *
-     * @param options - Connection options including the Socket and optional peer ID
-     * @returns A connection handle and start function
-     *
-     * @example Bun
-     * ```typescript
-     * const { start } = serverAdapter.handleConnection({
-     *   socket: wrapBunWebsocket(ws),
-     * })
-     * start()
-     * ```
-     *
-     * @example Node.js ws
-     * ```typescript
-     * wss.on("connection", (ws) => {
-     *   const { start } = serverAdapter.handleConnection({
-     *     socket: wrapNodeWebsocket(ws),
-     *   })
-     *   start()
-     * })
-     * ```
-     */
-    handleConnection(options: WebsocketConnectionOptions): WebsocketConnectionResult;
-    /**
-     * Get an active connection by peer ID.
-     */
-    getConnection(peerId: PeerId): WebsocketConnection | undefined;
-    /**
-     * Get all active connections.
-     */
-    getAllConnections(): WebsocketConnection[];
-    /**
-     * Check if a peer is connected.
-     */
-    isConnected(peerId: PeerId): boolean;
-    /**
-     * Unregister a connection, removing its channel and cleaning up state.
-     */
-    unregisterConnection(peerId: PeerId): void;
-    /**
-     * Broadcast a message to all connected peers.
-     */
-    broadcast(msg: ChannelMsg): void;
-    /**
-     * Get the number of connected peers.
-     */
-    get connectionCount(): number;
+  #private;
+  constructor(options?: WebsocketServerTransportOptions);
+  protected generate(peerId: PeerId): GeneratedChannel;
+  onStart(): Promise<void>;
+  onStop(): Promise<void>;
+  /**
+   * Handle a new Websocket connection.
+   *
+   * Call this from your framework's Websocket upgrade handler.
+   * Returns a connection handle and a `start()` function that begins
+   * message processing and sends the "ready" signal.
+   *
+   * @param options - Connection options including the Socket and optional peer ID
+   * @returns A connection handle and start function
+   *
+   * @example Bun
+   * ```typescript
+   * const { start } = serverAdapter.handleConnection({
+   *   socket: wrapBunWebsocket(ws),
+   * })
+   * start()
+   * ```
+   *
+   * @example Node.js ws
+   * ```typescript
+   * wss.on("connection", (ws) => {
+   *   const { start } = serverAdapter.handleConnection({
+   *     socket: wrapNodeWebsocket(ws),
+   *   })
+   *   start()
+   * })
+   * ```
+   */
+  handleConnection(options: WebsocketConnectionOptions): WebsocketConnectionResult;
+  /**
+   * Get an active connection by peer ID.
+   */
+  getConnection(peerId: PeerId): WebsocketConnection | undefined;
+  /**
+   * Get all active connections.
+   */
+  getAllConnections(): WebsocketConnection[];
+  /**
+   * Check if a peer is connected.
+   */
+  isConnected(peerId: PeerId): boolean;
+  /**
+   * Unregister a connection, removing its channel and cleaning up state.
+   */
+  unregisterConnection(peerId: PeerId): void;
+  /**
+   * Broadcast a message to all connected peers.
+   */
+  broadcast(msg: ChannelMsg): void;
+  /**
+   * Get the number of connected peers.
+   */
+  get connectionCount(): number;
 }
-
+//#endregion
+//#region src/service-client.d.ts
 /**
  * Options for service-to-service Websocket connections.
  *
@@ -194,5 +196,6 @@ type ServiceWebsocketClientOptions = WebsocketClientOptions;
  * ```
  */
 declare function createServiceWebsocketClient(options: ServiceWebsocketClientOptions): TransportFactory;
-
-export { DEFAULT_FRAGMENT_THRESHOLD, type ServiceWebsocketClientOptions, Socket, WebsocketConnection, type WebsocketConnectionConfig, WebsocketConnectionOptions, WebsocketConnectionResult, WebsocketServerTransport, type WebsocketServerTransportOptions, createServiceWebsocketClient };
+//#endregion
+export { DEFAULT_FRAGMENT_THRESHOLD, type DisconnectReason, type NodeWebsocketLike, READY_STATE, type ServiceWebsocketClientOptions, type Socket, type SocketReadyState, type WebSocketCloseEvent, type WebSocketConstructor, type WebSocketLike, type WebSocketMessageEvent, WebsocketConnection, type WebsocketConnectionConfig, type WebsocketConnectionHandle, type WebsocketConnectionOptions, type WebsocketConnectionResult, WebsocketServerTransport, type WebsocketServerTransportOptions, createServiceWebsocketClient, wrapNodeWebsocket, wrapStandardWebsocket };
+//# sourceMappingURL=server.d.ts.map

package/dist/server.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"server.d.ts","names":[],"sources":["../src/connection.ts","../src/server-transport.ts","../src/service-client.ts"],"mappings":";;;;;;;;AA8BA;;cAAa,0BAAA;;;AAKb;UAAiB,yBAAA;;;;AAkBjB;;EAZE,iBAAA;AAAA;;;;;;;;;;cAYW,mBAAA;EAAA;WACF,MAAA,EAAQ,MAAA;EAAA,SACR,SAAA;cAgBP,MAAA,EAAQ,MAAA,EACR,SAAA,UACA,MAAA,EAAQ,MAAA,EACR,MAAA,GAAS,yBAAA;EAFT;;;;;EA4BF,WAAA,CAAY,OAAA,EAAS,OAAA;EAAA;;;;;;EAcrB,KAAA,CAAA;EAkDA;;;;;;EAjCA,IAAA,CAAK,GAAA,EAAK,UAAA;;AClFZ;;;;;AAiCA;EDwEE,SAAA,CAAA;;;;EAUA,KAAA,CAAM,IAAA,WAAe,MAAA;AAAA;;;;AAtIvB;;UCmBiB,+BAAA;EDnBmC;;AAKpD;;;ECoBE,iBAAA;AAAA;ADFF;;;;;;;;;;;;;;;;;;;;AAAA,cC6Ba,wBAAA,SAAiC,SAAA,CAAU,MAAA;EAAA;cAI1C,OAAA,GAAU,+BAAA;EAAA,UAUZ,QAAA,CAAS,MAAA,EAAQ,MAAA,GAAS,gBAAA;EAe9B,OAAA,CAAA,GAAW,OAAA;EAIX,MAAA,CAAA,GAAU,OAAA;EDDhB;;;;;;;;;;;;;ACjEF;;;;;AAiCA;;;;;;;;;;EAyEE,gBAAA,CACE,OAAA,EAAS,0BAAA,GACR,yBAAA;EA+DmB;;;EAAtB,aAAA,CAAc,MAAA,EAAQ,MAAA,GAAS,mBAAA;EAqBF;;;EAd7B,iBAAA,CAAA,GAAqB,mBAAA;EAjJgC;;;EAwJrD,WAAA,CAAY,MAAA,EAAQ,MAAA;;;;EAOpB,oBAAA,CAAqB,MAAA,EAAQ,MAAA;EAjJF;;;EA4J3B,SAAA,CAAU,GAAA,EAAK,UAAA;EA7IE;;;EAAA,IAsJb,eAAA,CAAA;AAAA;;;;;;ADvON;;;;;KETY,6BAAA,GAAgC,sBAAA;;;;;AFgC5C;;;;;;;;;;;;;;;;;;;;iBENgB,4BAAA,CACd,OAAA,EAAS,6BAAA,GACR,gBAAA"}