wscall-client 0.3.0

package/src/client.js

@@ -0,0 +1,874 @@
+/**
+ * WscallClient - High-performance WebSocket RPC client for the WSCALL framework.
+ *
+ * Features:
+ * - Binary frame protocol with optional ChaCha20/AES-256-GCM encryption
+ * - Automatic reconnection with exponential backoff + jitter
+ * - Heartbeat keep-alive (ping/pong)
+ * - Concurrent request/response correlation via pending maps
+ * - Event subscription with concurrent handler dispatch
+ * - Event ACK support
+ * - Connection lifecycle hooks
+ */
+
+import {
+  FrameCodec,
+  EncryptionKind,
+  MessageType,
+  K_API_RESPONSE,
+  K_EVENT_EMIT,
+  K_EVENT_ACK,
+  buildApiRequest,
+  buildEventEmit,
+  buildEventAck,
+  ProtocolError,
+  generateEcdhKeypair,
+  parsePeerPublic,
+  deriveEcdhSessionKey,
+} from './protocol.js';
+
+// ─── Constants ────────────────────────────────────────────────────────────────
+
+const HEARTBEAT_INTERVAL_MS = 15_000;
+const IDLE_TIMEOUT_MS = 45_000;
+const DEFAULT_TIMEOUT_MS = 10_000;
+const RECONNECT_BASE_DELAY_MS = 3_000;
+const RECONNECT_MAX_DELAY_MS = 30_000;
+
+// ─── Errors ───────────────────────────────────────────────────────────────────
+
+export class ClientError extends Error {
+  constructor(message, code = 'CLIENT_ERROR', details = undefined) {
+    super(message);
+    this.name = 'ClientError';
+    this.code = code;
+    this.details = details;
+  }
+
+  static disconnected() {
+    return new ClientError('Client disconnected', 'DISCONNECTED');
+  }
+
+  static timeout() {
+    return new ClientError('Request timed out', 'TIMEOUT');
+  }
+
+  static connectionClosed(reason) {
+    return new ClientError(`Connection closed: ${reason}`, 'CONNECTION_CLOSED');
+  }
+
+  static remote(errorPayload) {
+    return new ClientError(
+      errorPayload?.message || 'Remote error',
+      errorPayload?.code || 'REMOTE_ERROR',
+      errorPayload
+    );
+  }
+}
+
+// ─── Pending Request Tracker ──────────────────────────────────────────────────
+
+/**
+ * Lock-free pending map using native Map for O(1) insert/delete/lookup.
+ * Each entry holds { resolve, reject, timer } for timeout management.
+ */
+class PendingMap {
+  #map = new Map();
+
+  get size() { return this.#map.size; }
+
+  /**
+   * Register a pending request. Returns a Promise that resolves/rejects
+   * when the response arrives or times out.
+   */
+  register(id, timeoutMs) {
+    return new Promise((resolve, reject) => {
+      const timer = setTimeout(() => {
+        this.#map.delete(id);
+        reject(ClientError.timeout());
+      }, timeoutMs);
+      // Unref timer in Node.js so it doesn't keep the process alive
+      if (timer.unref) timer.unref();
+      this.#map.set(id, { resolve, reject, timer });
+    });
+  }
+
+  /** Resolve a pending request with a value. */
+  resolve(id, value) {
+    const entry = this.#map.get(id);
+    if (entry) {
+      clearTimeout(entry.timer);
+      this.#map.delete(id);
+      entry.resolve(value);
+      return true;
+    }
+    return false;
+  }
+
+  /** Reject a pending request with an error. */
+  reject(id, error) {
+    const entry = this.#map.get(id);
+    if (entry) {
+      clearTimeout(entry.timer);
+      this.#map.delete(id);
+      entry.reject(error);
+      return true;
+    }
+    return false;
+  }
+
+  /** Drain all pending requests with an error (used on disconnect). */
+  drainAll(error) {
+    for (const [id, entry] of this.#map) {
+      clearTimeout(entry.timer);
+      entry.reject(error);
+    }
+    this.#map.clear();
+  }
+}
+
+// ─── WscallClientConfig ───────────────────────────────────────────────────────
+
+/**
+ * Configuration for establishing a WscallClient connection.
+ *
+ * Bundles all user-tunable connection parameters into a single value object.
+ * Use the static factory methods for common presets, or construct manually
+ * with the builder-style `with*` methods.
+ *
+ * @example
+ * ```js
+ * // ECDH dynamic key agreement (recommended default)
+ * const config = WscallClientConfig.ecdh();
+ *
+ * // Pre-shared ChaCha20 key
+ * const config = WscallClientConfig.pskChaCha20(key);
+ *
+ * // Plaintext (development only)
+ * const config = WscallClientConfig.plaintext();
+ *
+ * const client = await WscallClient.connect('ws://127.0.0.1:9001/socket', config);
+ * ```
+ */
+export class WscallClientConfig {
+  /** @type {Uint8Array|null} 32-byte ChaCha20-Poly1305 pre-shared key */
+  chacha20Key = null;
+  /** @type {Uint8Array|null} 32-byte AES-256-GCM pre-shared key */
+  aes256Key = null;
+  /** @type {boolean} Use ECDH dynamic key agreement */
+  useEcdh = true;
+  /** @type {boolean} Auto reconnect on unexpected disconnect */
+  autoReconnect = true;
+  /** @type {number} Default request timeout (ms) */
+  timeout = DEFAULT_TIMEOUT_MS;
+  /** @type {object} Default metadata sent with requests */
+  metadata = {};
+  /** @type {string[]} Failover server URLs tried when the primary is unreachable */
+  failoverUrls = [];
+
+  /** Creates a config with the recommended secure defaults (ECDH + ChaCha20 + auto-reconnect). */
+  static default() {
+    return new WscallClientConfig();
+  }
+
+  /** Convenience: ECDH dynamic key agreement (the default). */
+  static ecdh() {
+    return new WscallClientConfig();
+  }
+
+  /** Convenience: plaintext transport with no encryption (development only). */
+  static plaintext() {
+    const c = new WscallClientConfig();
+    c.useEcdh = false;
+    return c;
+  }
+
+  /** Convenience: pre-shared ChaCha20-Poly1305 key (no ECDH handshake). */
+  static pskChaCha20(key) {
+    const c = new WscallClientConfig();
+    c.chacha20Key = key;
+    c.useEcdh = false;
+    return c;
+  }
+
+  /** Convenience: pre-shared AES-256-GCM key (no ECDH handshake). */
+  static pskAes256(key) {
+    const c = new WscallClientConfig();
+    c.aes256Key = key;
+    c.useEcdh = false;
+    return c;
+  }
+
+  /** Builder: enable or disable ECDH. */
+  withUseEcdh(v) { this.useEcdh = v; return this; }
+  /** Builder: enable or disable auto-reconnect. */
+  withAutoReconnect(v) { this.autoReconnect = v; return this; }
+  /** Builder: set default timeout (ms). */
+  withTimeout(ms) { this.timeout = ms; return this; }
+  /** Builder: set default metadata. */
+  withMetadata(meta) { this.metadata = meta; return this; }
+  /** Builder: set a pre-shared ChaCha20 key (disables ECDH). */
+  withChaCha20Key(key) { this.chacha20Key = key; this.useEcdh = false; return this; }
+  /** Builder: set a pre-shared AES-256 key (disables ECDH). */
+  withAes256Key(key) { this.aes256Key = key; this.useEcdh = false; return this; }
+  /** Builder: append a single failover URL (can be called multiple times). */
+  withFailoverUrl(url) { this.failoverUrls.push(url); return this; }
+  /** Builder: set the full failover URL list (replaces any previously added). */
+  withFailoverUrls(urls) { this.failoverUrls = [...urls]; return this; }
+}
+
+// ─── WscallClient ─────────────────────────────────────────────────────────────
+
+export class WscallClient {
+  /** @type {string[]} All candidate server URLs: [primary, ...failover] */
+  #urls;
+  /** @type {number} Index of the last successfully connected URL */
+  #lastUrlIdx = 0;
+  #codec;
+  #defaultEncryption;
+  #autoReconnect;
+  #defaultTimeout;
+  #metadata;
+  #useEcdh = false;
+
+  // Connection state
+  #ws = null;
+  #connected = false;
+  #shutdown = false;
+  #generation = 0;
+  #reconnectAttempt = 0;
+  #reconnectTimer = null;
+  #heartbeatTimer = null;
+  #idleTimer = null;
+
+  // Correlation
+  #pendingApi = new PendingMap();
+  #pendingEvent = new PendingMap();
+  #nextRequestId = 0;
+  #nextEventId = 0;
+
+  // Handlers
+  #eventHandlers = new Map();      // name -> [handler, ...]
+  #connectedHandlers = [];
+  #disconnectedHandlers = [];
+
+  // Write queue for batching sends
+  #sendQueue = [];
+  #flushScheduled = false;
+
+  /**
+   * @param {object} options
+   * @param {string} options.url - Primary WebSocket URL (ws:// or wss://)
+   * @param {string[]} [options.failoverUrls] - Backup URLs for failover
+   * @param {Uint8Array} [options.chacha20Key] - 32-byte ChaCha20-Poly1305 key
+   * @param {Uint8Array} [options.aes256Key] - 32-byte AES-256-GCM key
+   * @param {boolean} [options.useEcdh=false] - Use ECDH dynamic key agreement
+   * @param {boolean} [options.autoReconnect=true] - Auto reconnect on disconnect
+   * @param {number} [options.timeout=10000] - Default request timeout (ms)
+   * @param {object} [options.metadata] - Default metadata sent with requests
+   */
+  constructor(options = {}) {
+    const { url, failoverUrls = [], chacha20Key, aes256Key, useEcdh = false, autoReconnect = true, timeout = DEFAULT_TIMEOUT_MS, metadata = {} } = options;
+
+    if (!url) throw new Error('url is required');
+
+    this.#urls = [url, ...failoverUrls];
+    this.#autoReconnect = autoReconnect;
+    this.#defaultTimeout = timeout;
+    this.#metadata = metadata;
+    this.#useEcdh = useEcdh;
+
+    this.#codec = new FrameCodec();
+    if (useEcdh) {
+      // Codec will be configured with the session key after the handshake.
+      this.#defaultEncryption = EncryptionKind.ChaCha20;
+    } else if (chacha20Key) {
+      this.#codec.withChaCha20Key(chacha20Key);
+      this.#defaultEncryption = EncryptionKind.ChaCha20;
+    } else if (aes256Key) {
+      this.#codec.withAes256Key(aes256Key);
+      this.#defaultEncryption = EncryptionKind.Aes256;
+    } else {
+      this.#defaultEncryption = EncryptionKind.None;
+    }
+  }
+
+  // ─── Static Connectors ──────────────────────────────────────────────────────
+
+  /**
+   * Connect to a WSCALL server with the given configuration.
+   *
+   * This is the unified entry point. Pass a {@link WscallClientConfig} for
+   * full control, or a plain options object for backward compatibility.
+   *
+   * @param {string} url - WebSocket URL (ws:// or wss://)
+   * @param {WscallClientConfig|object} [config] - Connection configuration
+   * @returns {Promise<WscallClient>}
+   */
+  static async connect(url, config = {}) {
+    let options;
+    if (config instanceof WscallClientConfig) {
+      options = {
+        url,
+        failoverUrls: config.failoverUrls,
+        chacha20Key: config.chacha20Key,
+        aes256Key: config.aes256Key,
+        useEcdh: config.useEcdh,
+        autoReconnect: config.autoReconnect,
+        timeout: config.timeout,
+        metadata: config.metadata,
+      };
+    } else {
+      options = { url, ...config };
+    }
+    const client = new WscallClient(options);
+    await client.connect();
+    return client;
+  }
+
+  /**
+   * Connect with ChaCha20-Poly1305 encryption.
+   * @deprecated Use WscallClient.connect(url, WscallClientConfig.pskChaCha20(key))
+   */
+  static async connectWithChaCha20(url, key, options = {}) {
+    return WscallClient.connect(url, WscallClientConfig.pskChaCha20(key).withMetadata(options.metadata || {}));
+  }
+
+  /**
+   * Connect with AES-256-GCM encryption.
+   * @deprecated Use WscallClient.connect(url, WscallClientConfig.pskAes256(key))
+   */
+  static async connectWithAes256(url, key, options = {}) {
+    return WscallClient.connect(url, WscallClientConfig.pskAes256(key).withMetadata(options.metadata || {}));
+  }
+
+  /**
+   * Connect using ECDH dynamic key agreement (no pre-shared key needed).
+   * @deprecated Use WscallClient.connect(url, WscallClientConfig.ecdh())
+   */
+  static async connectWithEcdh(url, options = {}) {
+    return WscallClient.connect(url, WscallClientConfig.ecdh().withMetadata(options.metadata || {}));
+  }
+
+  // ─── Connection Management ──────────────────────────────────────────────────
+
+  /** Establish the WebSocket connection. Resolves when connected. */
+  connect() {
+    if (this.#connected) return Promise.resolve();
+    this.#shutdown = false;
+    return this.#establishConnection();
+  }
+
+  /** Gracefully close the connection. */
+  close() {
+    this.#shutdown = true;
+    this.#clearTimers();
+    if (this.#reconnectTimer) {
+      clearTimeout(this.#reconnectTimer);
+      this.#reconnectTimer = null;
+    }
+    if (this.#ws) {
+      try { this.#ws.close(1000, 'client close'); } catch { /* ignore */ }
+      this.#ws = null;
+    }
+    this.#handleDisconnect('client closed', false);
+  }
+
+  /** Whether the client is currently connected. */
+  get isConnected() { return this.#connected; }
+
+  /** The URL of the last successfully connected server. */
+  get #currentUrl() { return this.#urls[this.#lastUrlIdx]; }
+
+  // ─── Event Registration ─────────────────────────────────────────────────────
+
+  /**
+   * Register an event handler. Multiple handlers per event name are supported.
+   * Handler receives an EventMessage and should return a receipt object.
+   * @param {string} name - Event name
+   * @param {(event: EventMessage) => object|Promise<object>} handler
+   */
+  onEvent(name, handler) {
+    if (!this.#eventHandlers.has(name)) {
+      this.#eventHandlers.set(name, []);
+    }
+    this.#eventHandlers.get(name).push(handler);
+    return this;
+  }
+
+  /** Remove an event handler. */
+  offEvent(name, handler) {
+    const handlers = this.#eventHandlers.get(name);
+    if (handlers) {
+      const idx = handlers.indexOf(handler);
+      if (idx !== -1) handlers.splice(idx, 1);
+      if (handlers.length === 0) this.#eventHandlers.delete(name);
+    }
+    return this;
+  }
+
+  /** Register a connected lifecycle handler. */
+  onConnected(handler) {
+    this.#connectedHandlers.push(handler);
+    // If already connected, fire immediately
+    if (this.#connected) {
+      handler({ url: this.#currentUrl });
+    }
+    return this;
+  }
+
+  /** Register a disconnected lifecycle handler. */
+  onDisconnected(handler) {
+    this.#disconnectedHandlers.push(handler);
+    return this;
+  }
+
+  // ─── RPC Calls ──────────────────────────────────────────────────────────────
+
+  /**
+   * Make an API call (request/response).
+   * @param {string} route - API route name
+   * @param {object} [params={}] - Request parameters
+   * @param {Array} [attachments=[]] - File attachments
+   * @param {object} [options] - Per-call options
+   * @param {number} [options.timeout] - Override default timeout (ms)
+   * @param {object} [options.metadata] - Override default metadata
+   * @returns {Promise<object>} Response data
+   */
+  async call(route, params = {}, attachments = [], options = {}) {
+    if (!this.#connected) throw ClientError.disconnected();
+
+    const requestId = ++this.#nextRequestId;
+    const timeout = options.timeout ?? this.#defaultTimeout;
+    const metadata = options.metadata ?? this.#metadata;
+
+    const body = buildApiRequest(requestId, route, params, attachments, metadata);
+    const promise = this.#pendingApi.register(requestId, timeout);
+
+    try {
+      await this.#sendPacket(body);
+    } catch (err) {
+      this.#pendingApi.reject(requestId, ClientError.disconnected());
+      throw err;
+    }
+
+    return promise;
+  }
+
+  /**
+   * Send an event and wait for ACK.
+   * @param {string} name - Event name
+   * @param {object} [data={}] - Event data
+   * @param {Array} [attachments=[]] - File attachments
+   * @param {object} [options] - Per-call options
+   * @returns {Promise<object>} ACK receipt
+   */
+  async sendEvent(name, data = {}, attachments = [], options = {}) {
+    if (!this.#connected) throw ClientError.disconnected();
+
+    const eventId = ++this.#nextEventId;
+    const timeout = options.timeout ?? this.#defaultTimeout;
+    const metadata = options.metadata ?? this.#metadata;
+
+    const body = buildEventEmit(eventId, name, data, attachments, metadata, true);
+    const promise = this.#pendingEvent.register(eventId, timeout);
+
+    try {
+      await this.#sendPacket(body);
+    } catch (err) {
+      this.#pendingEvent.reject(eventId, ClientError.disconnected());
+      throw err;
+    }
+
+    return promise;
+  }
+
+  // ─── Internal: Connection ───────────────────────────────────────────────────
+
+  async #establishConnection() {
+    const generation = ++this.#generation;
+    const WebSocketImpl = typeof WebSocket !== 'undefined' ? WebSocket : (await import('ws')).default;
+
+    return new Promise((resolve, reject) => {
+      // Failover: iterate through candidate URLs starting from the last
+      // successful index (sticky failover).
+      const start = this.#lastUrlIdx;
+      const count = this.#urls.length;
+      let offset = 0;
+      let lastError = null;
+
+      const tryNext = () => {
+        if (this.#generation !== generation || this.#shutdown) {
+          reject(new ClientError('Connection cancelled', 'CANCELLED'));
+          return;
+        }
+        if (offset >= count) {
+          reject(lastError || new ClientError('All server URLs unreachable', 'ALL_UNREACHABLE'));
+          return;
+        }
+
+        const idx = (start + offset) % count;
+        offset++;
+        const ws = new WebSocketImpl(this.#urls[idx]);
+        ws.binaryType = 'arraybuffer';
+
+        const onFail = (err) => {
+          ws.removeEventListener?.('open', onOpen);
+          ws.removeEventListener?.('error', onFail);
+          ws.onopen = null;
+          ws.onerror = null;
+          lastError = new ClientError(
+            `${this.#urls[idx]}: ${err?.message || 'connection failed'}`,
+            'CONNECTION_FAILED'
+          );
+          tryNext();
+        };
+
+        const onOpen = () => {
+          ws.removeEventListener?.('open', onOpen);
+          ws.removeEventListener?.('error', onFail);
+          ws.onopen = null;
+          ws.onerror = null;
+          this.#lastUrlIdx = idx;
+          this.#setupConnection(ws, generation, resolve, reject);
+        };
+
+        ws.addEventListener ? ws.addEventListener('open', onOpen) : (ws.onopen = onOpen);
+        ws.addEventListener ? ws.addEventListener('error', onFail) : (ws.onerror = onFail);
+      };
+
+      tryNext();
+    });
+  }
+
+  /**
+   * Set up message/close/heartbeat handlers on an already-open WebSocket.
+   * Handles the optional ECDH handshake before marking the connection ready.
+   */
+  #setupConnection(ws, generation, resolve, reject) {
+    this.#ws = ws;
+
+      // ECDH handshake state
+      let handshakePending = this.#useEcdh;
+      let handshakePrivateKey = null;
+      // Messages that arrive while the ECDH derivation is in-flight are
+      // buffered here and replayed once the session key is ready.
+      let handshakeBuffer = [];
+
+      const completeConnection = () => {
+        this.#connected = true;
+        this.#reconnectAttempt = 0;
+        this.#startHeartbeat();
+        this.#resetIdleTimer();
+        this.#emitConnected();
+        resolve();
+        // Replay any messages that arrived during the async derivation.
+        if (handshakeBuffer.length > 0) {
+          const buffered = handshakeBuffer;
+          handshakeBuffer = [];
+          for (const msg of buffered) {
+            this.#resetIdleTimer();
+            this.#handleInbound(msg);
+          }
+        }
+      };
+
+      const onOpenAsync = async () => {
+        if (this.#generation !== generation) return;
+
+        if (this.#useEcdh) {
+          // Generate X25519 keypair and send the client's public key.
+          try {
+            const { privateKey, publicKey } = await generateEcdhKeypair();
+            handshakePrivateKey = privateKey;
+            ws.send(publicKey);
+            // The server's public key will arrive as the first binary message.
+            // handshakePending stays true; onMessage will complete the handshake.
+          } catch (err) {
+            reject(new ClientError(`ECDH keypair generation failed: ${err.message}`, 'ECDH_ERROR'));
+          }
+        } else {
+          completeConnection();
+        }
+      };
+
+      // The socket is already open (failover loop resolved on 'open'),
+      // so kick off the handshake / completion immediately.
+      onOpenAsync();
+
+      const onClose = (event) => {
+        // Clean up all listeners on close
+        ws.removeEventListener?.('close', onClose);
+        ws.removeEventListener?.('message', onMessage);
+        ws.removeEventListener?.('pong', onPong);
+        ws.onclose = null;
+        ws.onmessage = null;
+        if (this.#generation !== generation) return;
+        const wasConnected = this.#connected;
+        this.#handleDisconnect(
+          event?.reason || 'connection closed',
+          true
+        );
+        if (!wasConnected) {
+          reject(ClientError.connectionClosed(event?.reason || 'connection refused'));
+        }
+      };
+
+      const onMessage = (event) => {
+        if (this.#generation !== generation) return;
+        // ws library: event may be the data directly or a MessageEvent-like object
+        const data = event?.data !== undefined ? event.data : event;
+
+        if (handshakePending === true) {
+          // The first 32-byte binary message is the server's X25519 public key.
+          // Start the async session key derivation. Any messages that arrive
+          // while the derivation is in-flight are buffered for replay.
+          const raw = new Uint8Array(data);
+          try {
+            const serverPublic = parsePeerPublic(raw);
+            handshakePending = 'deriving';
+            deriveEcdhSessionKey(handshakePrivateKey, serverPublic)
+              .then((sessionKey) => {
+                this.#codec = new FrameCodec();
+                this.#codec.withChaCha20Key(sessionKey);
+                this.#defaultEncryption = EncryptionKind.ChaCha20;
+                handshakePending = false;
+                completeConnection();
+              })
+              .catch((err) => {
+                reject(new ClientError(
+                  `ECDH session key derivation failed: ${err.message}`,
+                  'ECDH_ERROR'
+                ));
+              });
+          } catch (err) {
+            reject(new ClientError(`ECDH handshake failed: ${err.message}`, 'ECDH_ERROR'));
+          }
+          return;
+        }
+
+        if (handshakePending === 'deriving') {
+          handshakeBuffer.push(data);
+          return;
+        }
+
+        this.#resetIdleTimer();
+        this.#handleInbound(data);
+      };
+
+      const onPong = () => {
+        this.#resetIdleTimer();
+      };
+
+      // Support both addEventListener (browser) and on* (Node ws)
+      if (ws.addEventListener) {
+        ws.addEventListener('close', onClose);
+        ws.addEventListener('message', onMessage);
+        ws.addEventListener('pong', onPong);
+      } else {
+        ws.onclose = onClose;
+        ws.onmessage = onMessage;
+        ws.onpong = onPong;
+      }
+  }
+
+  #handleDisconnect(reason, willReconnect) {
+    if (!this.#connected && !this.#ws) return;
+
+    this.#connected = false;
+    this.#ws = null;
+    this.#clearTimers();
+
+    // Drain pending requests
+    const error = ClientError.connectionClosed(reason);
+    this.#pendingApi.drainAll(error);
+    this.#pendingEvent.drainAll(error);
+
+    // Notify disconnect handlers
+    const shouldReconnect = willReconnect && !this.#shutdown && this.#autoReconnect;
+    const event = {
+      url: this.#currentUrl,
+      reason,
+      willReconnect: shouldReconnect,
+      retryAfter: shouldReconnect ? this.#reconnectDelay(1) : null,
+    };
+    for (const handler of this.#disconnectedHandlers) {
+      try { handler(event); } catch { /* ignore handler errors */ }
+    }
+
+    // Schedule reconnect
+    if (shouldReconnect) {
+      this.#scheduleReconnect();
+    }
+  }
+
+  #scheduleReconnect() {
+    this.#reconnectAttempt++;
+    const delay = this.#reconnectDelay(this.#reconnectAttempt) + this.#reconnectJitter();
+
+    this.#reconnectTimer = setTimeout(async () => {
+      this.#reconnectTimer = null;
+      if (this.#shutdown) return;
+      try {
+        await this.#establishConnection();
+      } catch {
+        // Will be retried via handleDisconnect -> scheduleReconnect
+        if (!this.#shutdown && this.#autoReconnect) {
+          this.#scheduleReconnect();
+        }
+      }
+    }, delay);
+
+    // Unref in Node.js
+    if (this.#reconnectTimer.unref) this.#reconnectTimer.unref();
+  }
+
+  #reconnectDelay(attempt) {
+    const exp = Math.min(Math.max(attempt, 1) - 1, 6);
+    return Math.min(RECONNECT_BASE_DELAY_MS * (1 << exp), RECONNECT_MAX_DELAY_MS);
+  }
+
+  #reconnectJitter() {
+    return Math.random() * (RECONNECT_BASE_DELAY_MS / 2);
+  }
+
+  // ─── Internal: Heartbeat & Idle ─────────────────────────────────────────────
+
+  #startHeartbeat() {
+    this.#clearTimers();
+    this.#heartbeatTimer = setInterval(() => {
+      if (!this.#connected || !this.#ws) return;
+      try {
+        if (this.#ws.ping) {
+          this.#ws.ping(); // Node.js ws
+        } else {
+          // Browser: send a lightweight protocol-level ping isn't possible,
+          // but the server will handle WebSocket protocol pings.
+          // For browser, we rely on the idle timeout mechanism.
+        }
+      } catch { /* connection may have closed */ }
+    }, HEARTBEAT_INTERVAL_MS);
+
+    if (this.#heartbeatTimer.unref) this.#heartbeatTimer.unref();
+  }
+
+  #resetIdleTimer() {
+    if (this.#idleTimer) clearTimeout(this.#idleTimer);
+    this.#idleTimer = setTimeout(() => {
+      if (this.#connected) {
+        this.#handleDisconnect('idle timeout', true);
+        if (this.#ws) {
+          try { this.#ws.close(4000, 'idle timeout'); } catch { /* ignore */ }
+        }
+      }
+    }, IDLE_TIMEOUT_MS);
+
+    if (this.#idleTimer.unref) this.#idleTimer.unref();
+  }
+
+  #clearTimers() {
+    if (this.#heartbeatTimer) { clearInterval(this.#heartbeatTimer); this.#heartbeatTimer = null; }
+    if (this.#idleTimer) { clearTimeout(this.#idleTimer); this.#idleTimer = null; }
+  }
+
+  // ─── Internal: Send ─────────────────────────────────────────────────────────
+
+  async #sendPacket(body) {
+    if (!this.#ws || !this.#connected) throw ClientError.disconnected();
+    const frame = await this.#codec.encode(body);
+    this.#ws.send(frame);
+  }
+
+  // ─── Internal: Inbound Processing ──────────────────────────────────────────
+
+  async #handleInbound(data) {
+    let packet;
+    try {
+      packet = await this.#codec.decode(data);
+    } catch (err) {
+      console.warn('[wscall] Failed to decode inbound frame:', err.message);
+      return;
+    }
+
+    const { body } = packet;
+    const k = body.k;
+
+    switch (k) {
+      case K_API_RESPONSE:
+        this.#handleApiResponse(body);
+        break;
+      case K_EVENT_EMIT:
+        await this.#handleEventEmit(body);
+        break;
+      case K_EVENT_ACK:
+        this.#handleEventAck(body);
+        break;
+      default:
+        // Ignore unknown packet types (e.g., ApiRequest from server)
+        break;
+    }
+  }
+
+  #handleApiResponse(body) {
+    const { i: requestId, o: ok, d: data, er: error } = body;
+    if (ok) {
+      this.#pendingApi.resolve(requestId, data);
+    } else {
+      this.#pendingApi.reject(requestId, ClientError.remote(error));
+    }
+  }
+
+  #handleEventAck(body) {
+    const { i: eventId, o: ok, rc: receipt, er: error } = body;
+    if (ok) {
+      this.#pendingEvent.resolve(eventId, receipt);
+    } else {
+      this.#pendingEvent.reject(eventId, ClientError.remote(error));
+    }
+  }
+
+  async #handleEventEmit(body) {
+    const { i: eventId, n: name, d: data, a: attachments, m: metadata, e: expectAck } = body;
+
+    const event = {
+      eventId,
+      name,
+      data,
+      attachments: attachments || [],
+      metadata: metadata || {},
+    };
+
+    // Dispatch to all handlers concurrently
+    const handlers = this.#eventHandlers.get(name) || [];
+    let receipt = { handled: false };
+
+    if (handlers.length > 0) {
+      const results = await Promise.allSettled(
+        handlers.map(h => h(event))
+      );
+      // Last successful non-default receipt wins (matches Rust semantics)
+      for (const result of results) {
+        if (result.status === 'fulfilled' && result.value != null) {
+          receipt = result.value;
+        }
+      }
+    }
+
+    // Send ACK if expected
+    if (expectAck) {
+      const ackBody = buildEventAck(eventId, true, receipt);
+      try {
+        await this.#sendPacket(ackBody);
+      } catch { /* best-effort ACK */ }
+    }
+  }
+
+  // ─── Internal: Lifecycle Events ─────────────────────────────────────────────
+
+  #emitConnected() {
+    const event = { url: this.#currentUrl };
+    for (const handler of this.#connectedHandlers) {
+      try { handler(event); } catch { /* ignore handler errors */ }
+    }
+  }
+}