@kyneta/websocket-transport 1.1.0 → 1.3.0

package/dist/client.js

@@ -1,69 +1,190 @@
 import {
   wrapStandardWebsocket
-} from "./chunk-5FHT54WT.js";
+} from "./chunk-PSG3LLT5.js";
 
-// src/client-transport.ts
-import { Transport } from "@kyneta/exchange";
-import {
-  cborCodec,
-  decodeBinaryFrame,
-  encodeComplete,
-  FragmentReassembler,
-  fragmentPayload,
-  wrapCompleteMessage
-} from "@kyneta/wire";
-
-// src/client-state-machine.ts
-import { ClientStateMachine } from "@kyneta/exchange";
-var WS_VALID_TRANSITIONS = {
-  disconnected: ["connecting"],
-  connecting: ["connected", "disconnected", "reconnecting"],
-  connected: ["ready", "disconnected", "reconnecting"],
-  ready: ["disconnected", "reconnecting"],
-  reconnecting: ["connecting", "disconnected"]
-};
-var WebsocketClientStateMachine = class extends ClientStateMachine {
-  constructor() {
-    super({
-      initialState: { status: "disconnected" },
-      validTransitions: WS_VALID_TRANSITIONS
-    });
-  }
-  /**
-   * Check if the client is in a "connected" state (either connected or ready).
-   */
-  isConnectedOrReady() {
-    const s = this.getStatus();
-    return s === "connected" || s === "ready";
-  }
-  /**
-   * Check if the client is ready (server ready signal received).
-   */
-  isReady() {
-    return this.getStatus() === "ready";
+// src/client-program.ts
+import { computeBackoffDelay, DEFAULT_RECONNECT } from "@kyneta/transport";
+function createWsClientProgram(options = {}) {
+  const { jitterFn = () => Math.random() * 1e3 } = options;
+  const reconnect = {
+    ...DEFAULT_RECONNECT,
+    ...options.reconnect
+  };
+  function tryReconnect(currentAttempt, reason, ...extraEffects) {
+    if (!reconnect.enabled) {
+      return [{ status: "disconnected", reason }, ...extraEffects];
+    }
+    if (currentAttempt >= reconnect.maxAttempts) {
+      return [
+        {
+          status: "disconnected",
+          reason: { type: "max-retries-exceeded", attempts: currentAttempt }
+        },
+        ...extraEffects
+      ];
+    }
+    const delay = computeBackoffDelay(
+      currentAttempt + 1,
+      reconnect.baseDelay,
+      reconnect.maxDelay,
+      jitterFn()
+    );
+    return [
+      {
+        status: "reconnecting",
+        attempt: currentAttempt + 1,
+        nextAttemptMs: delay
+      },
+      ...extraEffects,
+      { type: "start-reconnect-timer", delayMs: delay }
+    ];
   }
-};
+  return {
+    init: [{ status: "disconnected" }],
+    update(msg, model) {
+      switch (msg.type) {
+        // -----------------------------------------------------------------
+        // start
+        // -----------------------------------------------------------------
+        case "start": {
+          if (model.status !== "disconnected") return [model];
+          return [
+            { status: "connecting", attempt: 1 },
+            { type: "create-websocket", attempt: 1 }
+          ];
+        }
+        // -----------------------------------------------------------------
+        // socket-opened
+        // -----------------------------------------------------------------
+        case "socket-opened": {
+          if (model.status !== "connecting") return [model];
+          return [{ status: "connected" }, { type: "start-keepalive" }];
+        }
+        // -----------------------------------------------------------------
+        // server-ready
+        // -----------------------------------------------------------------
+        case "server-ready": {
+          if (model.status === "ready") return [model];
+          if (model.status === "connected") {
+            return [{ status: "ready" }, { type: "add-channel-and-establish" }];
+          }
+          if (model.status === "connecting") {
+            return [
+              { status: "ready" },
+              { type: "start-keepalive" },
+              { type: "add-channel-and-establish" }
+            ];
+          }
+          return [model];
+        }
+        // -----------------------------------------------------------------
+        // socket-closed
+        // -----------------------------------------------------------------
+        case "socket-closed": {
+          const reason = {
+            type: "closed",
+            code: msg.code,
+            reason: msg.reason
+          };
+          if (model.status === "connected") {
+            return tryReconnect(0, reason, { type: "stop-keepalive" });
+          }
+          if (model.status === "ready") {
+            return tryReconnect(
+              0,
+              reason,
+              { type: "stop-keepalive" },
+              { type: "remove-channel" }
+            );
+          }
+          return [model];
+        }
+        // -----------------------------------------------------------------
+        // socket-error
+        // -----------------------------------------------------------------
+        case "socket-error": {
+          const reason = {
+            type: "error",
+            error: msg.error
+          };
+          if (model.status === "connecting") {
+            return tryReconnect(model.attempt, reason);
+          }
+          if (model.status === "connected") {
+            return tryReconnect(0, reason, { type: "stop-keepalive" });
+          }
+          if (model.status === "ready") {
+            return tryReconnect(
+              0,
+              reason,
+              { type: "stop-keepalive" },
+              { type: "remove-channel" }
+            );
+          }
+          return [model];
+        }
+        // -----------------------------------------------------------------
+        // reconnect-timer-fired
+        // -----------------------------------------------------------------
+        case "reconnect-timer-fired": {
+          if (model.status !== "reconnecting") return [model];
+          return [
+            { status: "connecting", attempt: model.attempt },
+            { type: "create-websocket", attempt: model.attempt }
+          ];
+        }
+        // -----------------------------------------------------------------
+        // stop
+        // -----------------------------------------------------------------
+        case "stop": {
+          if (model.status === "disconnected") return [model];
+          const effects = [{ type: "cancel-reconnect-timer" }];
+          if (model.status === "connecting") {
+            effects.push({ type: "close-websocket" });
+          }
+          if (model.status === "connected") {
+            effects.push(
+              { type: "close-websocket" },
+              { type: "stop-keepalive" }
+            );
+          }
+          if (model.status === "ready") {
+            effects.push(
+              { type: "close-websocket" },
+              { type: "stop-keepalive" },
+              { type: "remove-channel" }
+            );
+          }
+          return [
+            { status: "disconnected", reason: { type: "intentional" } },
+            ...effects
+          ];
+        }
+      }
+    }
+  };
+}
 
 // src/client-transport.ts
+import { createObservableProgram } from "@kyneta/machine";
+import { Transport } from "@kyneta/transport";
+import {
+  decodeBinaryMessages,
+  encodeBinaryAndSend,
+  FragmentReassembler
+} from "@kyneta/wire";
 var DEFAULT_FRAGMENT_THRESHOLD = 100 * 1024;
-var DEFAULT_RECONNECT = {
-  enabled: true,
-  maxAttempts: 10,
-  baseDelay: 1e3,
-  maxDelay: 3e4
-};
 var WebsocketClientTransport = class extends Transport {
   #peerId;
+  #options;
+  #WebSocketImpl;
+  // Observable program handle — created in constructor, drives all state
+  #handle;
+  // Executor-local I/O state — not in the program model
   #socket;
   #serverChannel;
   #keepaliveTimer;
   #reconnectTimer;
-  #options;
-  #WebSocketImpl;
-  #shouldReconnect = true;
-  #wasConnectedBefore = false;
-  // State machine
-  #stateMachine = new WebsocketClientStateMachine();
   // Fragmentation
   #fragmentThreshold;
   #reassembler;
@@ -75,120 +196,90 @@ var WebsocketClientTransport = class extends Transport {
     this.#reassembler = new FragmentReassembler({
       timeoutMs: 1e4
     });
+    const program = createWsClientProgram({
+      reconnect: options.reconnect
+    });
+    this.#handle = createObservableProgram(program, (effect, dispatch) => {
+      this.#executeEffect(effect, dispatch);
+    });
     this.#setupLifecycleEvents();
   }
   // ==========================================================================
-  // Lifecycle event forwarding
+  // Effect executor — interprets data effects as I/O
   // ==========================================================================
-  #setupLifecycleEvents() {
-    this.#stateMachine.subscribeToTransitions((transition) => {
-      this.#options.lifecycle?.onStateChange?.(transition);
-      const { from, to } = transition;
-      if (to.status === "disconnected" && to.reason) {
-        this.#options.lifecycle?.onDisconnect?.(to.reason);
+  #executeEffect(effect, dispatch) {
+    switch (effect.type) {
+      case "create-websocket": {
+        this.#doCreateWebsocket(dispatch);
+        break;
       }
-      if (to.status === "reconnecting") {
-        this.#options.lifecycle?.onReconnecting?.(to.attempt, to.nextAttemptMs);
-      }
-      if (this.#wasConnectedBefore && (from.status === "reconnecting" || from.status === "connecting") && (to.status === "connected" || to.status === "ready")) {
-        this.#options.lifecycle?.onReconnected?.();
+      case "close-websocket": {
+        if (this.#socket) {
+          this.#socket.close(1e3, "Client disconnecting");
+          this.#socket = void 0;
+        }
+        break;
       }
-      if (to.status === "ready") {
-        this.#options.lifecycle?.onReady?.();
+      case "add-channel-and-establish": {
+        if (this.#serverChannel) {
+          this.removeChannel(this.#serverChannel.channelId);
+          this.#serverChannel = void 0;
+        }
+        this.#serverChannel = this.addChannel();
+        this.establishChannel(this.#serverChannel.channelId);
+        break;
       }
-    });
-  }
-  // ==========================================================================
-  // State observation API
-  // ==========================================================================
-  /**
-   * Get the current state of the connection.
-   */
-  getState() {
-    return this.#stateMachine.getState();
-  }
-  /**
-   * Subscribe to state transitions.
-   * @returns Unsubscribe function
-   */
-  subscribeToTransitions(listener) {
-    return this.#stateMachine.subscribeToTransitions(listener);
-  }
-  /**
-   * Wait for a specific state.
-   */
-  waitForState(predicate, options) {
-    return this.#stateMachine.waitForState(predicate, options);
-  }
-  /**
-   * Wait for a specific status.
-   */
-  waitForStatus(status, options) {
-    return this.#stateMachine.waitForStatus(status, options);
-  }
-  /**
-   * Check if the client is ready (server ready signal received).
-   */
-  get isReady() {
-    return this.#stateMachine.isReady();
-  }
-  // ==========================================================================
-  // Adapter abstract method implementations
-  // ==========================================================================
-  generate() {
-    return {
-      transportType: this.transportType,
-      send: (msg) => {
-        if (!this.#socket || this.#socket.readyState !== WebSocket.OPEN) {
-          return;
+      case "remove-channel": {
+        if (this.#serverChannel) {
+          this.removeChannel(this.#serverChannel.channelId);
+          this.#serverChannel = void 0;
         }
-        const frame = encodeComplete(cborCodec, msg);
-        if (this.#fragmentThreshold > 0 && frame.length > this.#fragmentThreshold) {
-          const fragments = fragmentPayload(frame, this.#fragmentThreshold);
-          for (const fragment of fragments) {
-            this.#socket.send(fragment);
-          }
-        } else {
-          this.#socket.send(wrapCompleteMessage(frame));
+        break;
+      }
+      case "start-reconnect-timer": {
+        this.#reconnectTimer = setTimeout(() => {
+          this.#reconnectTimer = void 0;
+          dispatch({ type: "reconnect-timer-fired" });
+        }, effect.delayMs);
+        break;
+      }
+      case "cancel-reconnect-timer": {
+        if (this.#reconnectTimer !== void 0) {
+          clearTimeout(this.#reconnectTimer);
+          this.#reconnectTimer = void 0;
         }
-      },
-      stop: () => {
+        break;
+      }
+      case "start-keepalive": {
+        this.#startKeepalive();
+        break;
+      }
+      case "stop-keepalive": {
+        this.#stopKeepalive();
+        break;
       }
-    };
-  }
-  async onStart() {
-    if (!this.identity) {
-      throw new Error(
-        "Adapter not properly initialized \u2014 identity not available"
-      );
     }
-    this.#peerId = this.identity.peerId;
-    this.#shouldReconnect = true;
-    this.#wasConnectedBefore = false;
-    await this.#connect();
-  }
-  async onStop() {
-    this.#shouldReconnect = false;
-    this.#reassembler.dispose();
-    this.#disconnect({ type: "intentional" });
   }
   // ==========================================================================
-  // Connection management
+  // WebSocket creation — the core I/O operation
   // ==========================================================================
   /**
-   * Connect to the Websocket server.
+   * Create a WebSocket and wire up event handlers to dispatch messages.
+   *
+   * The message handler is set up IMMEDIATELY after creation (before
+   * the open event) to handle the race condition where the server sends
+   * "ready" before the client's open promise resolves.
    */
-  async #connect() {
-    const currentState = this.#stateMachine.getState();
-    if (currentState.status === "connecting") {
+  #doCreateWebsocket(dispatch) {
+    const peerId = this.#peerId;
+    if (!peerId) {
+      dispatch({
+        type: "socket-error",
+        error: new Error("Cannot connect: peerId not set")
+      });
       return;
     }
-    if (!this.#peerId) {
-      throw new Error("Cannot connect: peerId not set");
-    }
-    const attempt = currentState.status === "reconnecting" ? currentState.attempt : 1;
-    this.#stateMachine.transition({ status: "connecting", attempt });
-    const url = typeof this.#options.url === "function" ? this.#options.url(this.#peerId) : this.#options.url;
+    const url = typeof this.#options.url === "function" ? this.#options.url(peerId) : this.#options.url;
     try {
       if (this.#options.headers && Object.keys(this.#options.headers).length > 0) {
         const BunWebSocket = this.#WebSocketImpl;
@@ -199,122 +290,89 @@ var WebsocketClientTransport = class extends Transport {
         this.#socket = new this.#WebSocketImpl(url);
       }
       this.#socket.binaryType = "arraybuffer";
-      this.#socket.addEventListener("message", (event) => {
-        this.#handleMessage(event);
+      const socket = this.#socket;
+      socket.addEventListener("message", (event) => {
+        this.#handleMessage(event, dispatch);
       });
-      await new Promise((resolve, reject) => {
-        if (!this.#socket) {
-          reject(new Error("Socket not created"));
-          return;
-        }
-        const onOpen = () => {
-          cleanup();
-          resolve();
-        };
-        const onError = (event) => {
-          cleanup();
-          reject(new Error(`WebSocket connection failed: ${event}`));
-        };
-        const onClose = () => {
-          cleanup();
-          reject(new Error("WebSocket closed during connection"));
-        };
-        const cleanup = () => {
-          this.#socket?.removeEventListener("open", onOpen);
-          this.#socket?.removeEventListener("error", onError);
-          this.#socket?.removeEventListener("close", onClose);
-        };
-        this.#socket.addEventListener("open", onOpen);
-        this.#socket.addEventListener("error", onError);
-        this.#socket.addEventListener("close", onClose);
-      });
-      this.#stateMachine.transition({ status: "connected" });
-      this.#socket.addEventListener("close", (event) => {
-        this.#handleClose(event.code, event.reason);
-      });
-      this.#startKeepalive();
+      let settled = false;
+      const onOpen = () => {
+        cleanup();
+        settled = true;
+        dispatch({ type: "socket-opened" });
+        socket.addEventListener("close", (event) => {
+          dispatch({
+            type: "socket-closed",
+            code: event.code,
+            reason: event.reason
+          });
+        });
+      };
+      const onError = () => {
+        if (settled) return;
+        cleanup();
+        settled = true;
+        dispatch({
+          type: "socket-error",
+          error: new Error("WebSocket connection failed")
+        });
+      };
+      const onClose = () => {
+        if (settled) return;
+        cleanup();
+        settled = true;
+        dispatch({
+          type: "socket-error",
+          error: new Error("WebSocket closed during connection")
+        });
+      };
+      const cleanup = () => {
+        socket.removeEventListener("open", onOpen);
+        socket.removeEventListener("error", onError);
+        socket.removeEventListener("close", onClose);
+      };
+      socket.addEventListener("open", onOpen);
+      socket.addEventListener("error", onError);
+      socket.addEventListener("close", onClose);
     } catch (error) {
-      this.#scheduleReconnect({
-        type: "error",
+      dispatch({
+        type: "socket-error",
         error: error instanceof Error ? error : new Error(String(error))
       });
     }
   }
-  /**
-   * Disconnect from the Websocket server.
-   */
-  #disconnect(reason) {
-    this.#stopKeepalive();
-    this.#clearReconnectTimer();
-    if (this.#socket) {
-      this.#socket.close(1e3, "Client disconnecting");
-      this.#socket = void 0;
-    }
-    if (this.#serverChannel) {
-      this.removeChannel(this.#serverChannel.channelId);
-      this.#serverChannel = void 0;
-    }
-    const currentState = this.#stateMachine.getState();
-    if (currentState.status !== "disconnected") {
-      this.#stateMachine.transition({ status: "disconnected", reason });
-    }
-  }
   // ==========================================================================
-  // Message handling
+  // Message handling — I/O parsing logic
   // ==========================================================================
   /**
    * Handle incoming Websocket messages.
+   *
+   * Text frames carry the "ready" handshake and keepalive pong.
+   * Binary frames carry CBOR-encoded ChannelMsg.
    */
-  #handleMessage(event) {
+  #handleMessage(event, dispatch) {
     const data = event.data;
     if (typeof data === "string") {
       if (data === "ready") {
-        this.#handleServerReady();
+        dispatch({ type: "server-ready" });
       }
       return;
     }
     if (data instanceof ArrayBuffer) {
-      const result = this.#reassembler.receiveRaw(new Uint8Array(data));
-      if (result.status === "complete") {
-        try {
-          const frame = decodeBinaryFrame(result.data);
-          const messages = cborCodec.decode(frame.content.payload);
+      try {
+        const messages = decodeBinaryMessages(
+          new Uint8Array(data),
+          this.#reassembler
+        );
+        if (messages) {
           for (const msg of messages) {
             this.#handleChannelMessage(msg);
           }
-        } catch (error) {
-          console.error("Failed to decode message:", error);
         }
-      } else if (result.status === "error") {
-        console.error("Fragment reassembly error:", result.error);
+      } catch (error) {
+        console.error("Failed to decode message:", error);
       }
     }
   }
-  /**
-   * Handle the "ready" signal from the server.
-   *
-   * Creates the channel and starts the establishment handshake.
-   * The "ready" signal is a transport-level indicator that the server's
-   * Websocket handler is ready. After receiving it, we create our channel
-   * and send a real establish-request.
-   */
-  #handleServerReady() {
-    const currentState = this.#stateMachine.getState();
-    if (currentState.status === "ready") {
-      return;
-    }
-    if (currentState.status === "connecting") {
-      this.#stateMachine.transition({ status: "connected" });
-    }
-    this.#stateMachine.transition({ status: "ready" });
-    this.#wasConnectedBefore = true;
-    if (this.#serverChannel) {
-      this.removeChannel(this.#serverChannel.channelId);
-      this.#serverChannel = void 0;
-    }
-    this.#serverChannel = this.addChannel();
-    this.establishChannel(this.#serverChannel.channelId);
-  }
   /**
    * Handle a decoded channel message.
    */
@@ -324,17 +382,6 @@ var WebsocketClientTransport = class extends Transport {
     }
     this.#serverChannel.onReceive(msg);
   }
-  /**
-   * Handle Websocket close.
-   */
-  #handleClose(code, reason) {
-    this.#stopKeepalive();
-    if (this.#serverChannel) {
-      this.removeChannel(this.#serverChannel.channelId);
-      this.#serverChannel = void 0;
-    }
-    this.#scheduleReconnect({ type: "closed", code, reason });
-  }
   // ==========================================================================
   // Keepalive
   // ==========================================================================
@@ -354,51 +401,94 @@ var WebsocketClientTransport = class extends Transport {
     }
   }
   // ==========================================================================
-  // Reconnection
+  // Lifecycle event forwarding
+  // ==========================================================================
+  #setupLifecycleEvents() {
+    let wasConnectedBefore = false;
+    this.#handle.subscribeToTransitions((transition) => {
+      this.#options.lifecycle?.onStateChange?.(transition);
+      const { from, to } = transition;
+      if (to.status === "disconnected" && to.reason) {
+        this.#options.lifecycle?.onDisconnect?.(to.reason);
+      }
+      if (to.status === "reconnecting") {
+        this.#options.lifecycle?.onReconnecting?.(to.attempt, to.nextAttemptMs);
+      }
+      if (wasConnectedBefore && (from.status === "reconnecting" || from.status === "connecting") && (to.status === "connected" || to.status === "ready")) {
+        this.#options.lifecycle?.onReconnected?.();
+      }
+      if (to.status === "ready") {
+        this.#options.lifecycle?.onReady?.();
+        wasConnectedBefore = true;
+      }
+    });
+  }
+  // ==========================================================================
+  // State observation — delegated to the observable handle
   // ==========================================================================
   /**
-   * Schedule a reconnection attempt or transition to disconnected.
+   * Get the current connection state.
    */
-  #scheduleReconnect(reason) {
-    const currentState = this.#stateMachine.getState();
-    if (currentState.status === "disconnected") {
-      return;
-    }
-    const reconnectOpts = {
-      ...DEFAULT_RECONNECT,
-      ...this.#options.reconnect
+  getState() {
+    return this.#handle.getState();
+  }
+  /**
+   * Subscribe to state transitions.
+   */
+  subscribeToTransitions(listener) {
+    return this.#handle.subscribeToTransitions(listener);
+  }
+  /**
+   * Wait for a specific state.
+   */
+  waitForState(predicate, options) {
+    return this.#handle.waitForState(predicate, options);
+  }
+  /**
+   * Wait for a specific status.
+   */
+  waitForStatus(status, options) {
+    return this.#handle.waitForStatus(status, options);
+  }
+  /**
+   * Whether the client is ready (server ready signal received).
+   */
+  get isReady() {
+    return this.#handle.getState().status === "ready";
+  }
+  // ==========================================================================
+  // Transport abstract method implementations
+  // ==========================================================================
+  generate() {
+    return {
+      transportType: this.transportType,
+      send: (msg) => {
+        const socket = this.#socket;
+        if (!socket || socket.readyState !== WebSocket.OPEN) {
+          return;
+        }
+        encodeBinaryAndSend(
+          msg,
+          this.#fragmentThreshold,
+          (data) => socket.send(new Uint8Array(data).buffer)
+        );
+      },
+      stop: () => {
+      }
     };
-    if (!this.#shouldReconnect || !reconnectOpts.enabled) {
-      this.#stateMachine.transition({ status: "disconnected", reason });
-      return;
-    }
-    const currentAttempt = currentState.status === "reconnecting" ? currentState.attempt : currentState.status === "connecting" ? currentState.attempt : 0;
-    if (currentAttempt >= reconnectOpts.maxAttempts) {
-      this.#stateMachine.transition({
-        status: "disconnected",
-        reason: { type: "max-retries-exceeded", attempts: currentAttempt }
-      });
-      return;
-    }
-    const nextAttempt = currentAttempt + 1;
-    const delay = Math.min(
-      reconnectOpts.baseDelay * 2 ** (nextAttempt - 1) + Math.random() * 1e3,
-      reconnectOpts.maxDelay
-    );
-    this.#stateMachine.transition({
-      status: "reconnecting",
-      attempt: nextAttempt,
-      nextAttemptMs: delay
-    });
-    this.#reconnectTimer = setTimeout(() => {
-      this.#connect();
-    }, delay);
   }
-  #clearReconnectTimer() {
-    if (this.#reconnectTimer) {
-      clearTimeout(this.#reconnectTimer);
-      this.#reconnectTimer = void 0;
+  async onStart() {
+    if (!this.identity) {
+      throw new Error(
+        "Transport not properly initialized \u2014 identity not available"
+      );
     }
+    this.#peerId = this.identity.peerId;
+    this.#handle.dispatch({ type: "start" });
+  }
+  async onStop() {
+    this.#reassembler.dispose();
+    this.#handle.dispatch({ type: "stop" });
   }
 };
 function createWebsocketClient(options) {
@@ -409,10 +499,10 @@ function createServiceWebsocketClient(options) {
 }
 export {
   DEFAULT_FRAGMENT_THRESHOLD,
-  WebsocketClientStateMachine,
   WebsocketClientTransport,
   createServiceWebsocketClient,
   createWebsocketClient,
+  createWsClientProgram,
   wrapStandardWebsocket
 };
 //# sourceMappingURL=client.js.map