@parall/sdk 1.12.0

package/src/ws.ts

@@ -0,0 +1,404 @@
+import { WS_EVENTS } from './constants.js';
+import type { WsFrame, WsEventMap, WsTicketResponse } from './types.js';
+
+export type WsEventType = keyof WsEventMap;
+export type WsEventHandler<T extends WsEventType> = (data: WsEventMap[T], seq?: number) => void;
+
+export type WsClientEventMap = {
+  'ping': { ts: number };
+  'typing': { chat_id: string; thread_root_id: string | null; action: 'start' | 'stop' };
+  'watch': { chat_ids: string[] };
+  'agent.heartbeat': { session_id: string; telemetry?: Record<string, unknown> };
+};
+
+export type WsConnectionState = 'connecting' | 'connected' | 'disconnected' | 'reconnecting';
+
+export interface ParallWsOptions {
+  /** Async function that fetches a one-time WS ticket from the API. */
+  getTicket: () => Promise<WsTicketResponse>;
+  /** Fallback WS URL if getTicket response doesn't include ws_url. */
+  wsUrl?: string;
+  lastSeq?: number;
+  reconnect?: boolean;
+  reconnectInterval?: number;
+  maxReconnectInterval?: number;
+}
+
+export class ParallWs {
+  private ws: WebSocket | null = null;
+  private options: ParallWsOptions & { reconnect: boolean; reconnectInterval: number; maxReconnectInterval: number };
+  private listeners = new Map<string, Set<WsEventHandler<WsEventType>>>();
+  private stateListeners = new Set<(state: WsConnectionState) => void>();
+  private heartbeatTimer: ReturnType<typeof setInterval> | null = null;
+  private reconnectTimer: ReturnType<typeof setTimeout> | null = null;
+  private reconnectAttempts = 0;
+  private lastSeq = 0;
+  private _state: WsConnectionState = 'disconnected';
+  private intentionalClose = false;
+  private lastReceivedAt = 0;
+  private heartbeatIntervalMs = 0;
+  private probeTimer: ReturnType<typeof setTimeout> | null = null;
+  private browserListenersActive = false;
+
+  constructor(options: ParallWsOptions) {
+    this.options = {
+      reconnect: true,
+      reconnectInterval: 1000,
+      maxReconnectInterval: 30000,
+      ...options,
+    };
+    this.lastSeq = options.lastSeq ?? 0;
+  }
+
+  get state(): WsConnectionState {
+    return this._state;
+  }
+
+  async connect() {
+    this.intentionalClose = false;
+    this.setupBrowserListeners();
+    this.setState('connecting');
+
+    let ticket: WsTicketResponse;
+    try {
+      ticket = await this.options.getTicket();
+    } catch (err) {
+      console.error('Failed to get WS ticket:', err);
+      if (this.options.reconnect) {
+        this.scheduleReconnect();
+      } else {
+        this.setState('disconnected');
+      }
+      return;
+    }
+
+    const wsUrl = ticket.ws_url || this.options.wsUrl;
+    if (!wsUrl) {
+      console.error('No WS URL available');
+      this.setState('disconnected');
+      return;
+    }
+
+    // wsUrl may already contain query params (e.g. ?swimlane=pr-42 for
+    // swimlane routing). Use URL API to merge params correctly.
+    const url = new URL(wsUrl);
+    url.searchParams.set('ticket', ticket.ticket);
+    if (this.lastSeq > 0) {
+      url.searchParams.set('last_seq', String(this.lastSeq));
+    }
+
+    this.ws = new WebSocket(url.toString());
+
+    // Force-reconnect if not connected within 15s.
+    // Handles edge case where Node 22 WebSocket transitions to CLOSED without
+    // firing onclose (e.g. TCP reset during Cloudflare rolling update).
+    const ws = this.ws;
+    const connectTimeout = setTimeout(() => {
+      if (this._state === 'connected' || this.intentionalClose) return;
+      ws.onclose = null;
+      ws.onopen = null;
+      ws.onerror = null;
+      try { ws.close(); } catch { /* ignore */ }
+      // Only reconnect if this socket is still the active one.
+      // If connect() was called again, a newer socket owns the lifecycle.
+      if (ws !== this.ws) return;
+      if (this.options.reconnect) {
+        this.scheduleReconnect();
+      } else {
+        this.setState('disconnected');
+      }
+    }, 15_000);
+
+    this.ws.onopen = () => {
+      clearTimeout(connectTimeout);
+      this.reconnectAttempts = 0;
+      this.lastReceivedAt = Date.now();
+      this.setState('connected');
+    };
+
+    this.ws.onmessage = (event) => {
+      try {
+        const frame: WsFrame = JSON.parse(event.data as string);
+        this.handleFrame(frame);
+      } catch {
+        // ignore malformed frames
+      }
+    };
+
+    this.ws.onclose = () => {
+      clearTimeout(connectTimeout);
+      this.stopHeartbeat();
+      this.clearProbe();
+      if (this.intentionalClose) {
+        this.setState('disconnected');
+        return;
+      }
+      if (this.options.reconnect) {
+        this.scheduleReconnect();
+      } else {
+        this.setState('disconnected');
+      }
+    };
+
+    this.ws.onerror = () => {
+      // onclose will fire after this
+    };
+  }
+
+  disconnect() {
+    this.intentionalClose = true;
+    this.stopHeartbeat();
+    this.clearReconnect();
+    this.clearProbe();
+    this.teardownBrowserListeners();
+    if (this.ws) {
+      this.ws.close();
+      this.ws = null;
+    }
+    this.setState('disconnected');
+  }
+
+  // ---- Client -> Server messages ----
+
+  /** Tell the server which chats the user is currently viewing (no auth implications). */
+  watch(chatIds: string[]) {
+    this.send({ type: WS_EVENTS.WATCH, data: { chat_ids: chatIds } });
+  }
+
+  sendTyping(chatId: string, action: 'start' | 'stop', threadRootId?: string) {
+    this.send({
+      type: WS_EVENTS.TYPING,
+      data: { chat_id: chatId, thread_root_id: threadRootId ?? null, action },
+    });
+  }
+
+  /** Send an agent heartbeat with telemetry data. */
+  sendAgentHeartbeat(sessionId: string, telemetry?: Record<string, unknown>) {
+    this.send({
+      type: WS_EVENTS.AGENT_HEARTBEAT,
+      data: { session_id: sessionId, telemetry },
+    });
+  }
+
+  sendEvent(type: string, data: unknown) {
+    this.send({ type, data });
+  }
+
+  // ---- Event listeners ----
+
+  on<T extends WsEventType>(event: T, handler: WsEventHandler<T>) {
+    let set = this.listeners.get(event);
+    if (!set) {
+      set = new Set();
+      this.listeners.set(event, set);
+    }
+    set.add(handler as WsEventHandler<WsEventType>);
+    return () => {
+      set!.delete(handler as WsEventHandler<WsEventType>);
+    };
+  }
+
+  off<T extends WsEventType>(event: T, handler: WsEventHandler<T>) {
+    this.listeners.get(event)?.delete(handler as WsEventHandler<WsEventType>);
+  }
+
+  onStateChange(handler: (state: WsConnectionState) => void) {
+    this.stateListeners.add(handler);
+    return () => {
+      this.stateListeners.delete(handler);
+    };
+  }
+
+  // ---- Internal ----
+
+  private send(frame: { type: string; data: unknown }) {
+    if (this.ws?.readyState === WebSocket.OPEN) {
+      this.ws.send(JSON.stringify(frame));
+    }
+  }
+
+  private handleFrame(frame: WsFrame) {
+    this.lastReceivedAt = Date.now();
+    this.clearProbe();
+
+    // Track seq for reconnection
+    if (frame.seq !== undefined) {
+      this.lastSeq = frame.seq;
+    }
+
+    // Handle hello — start heartbeat
+    if (frame.type === WS_EVENTS.HELLO) {
+      const interval = (frame.data as { heartbeat_interval: number }).heartbeat_interval;
+      this.startHeartbeat(interval);
+    }
+
+    // Dispatch to listeners
+    const handlers = this.listeners.get(frame.type);
+    if (handlers) {
+      for (const handler of handlers) {
+        handler(frame.data as WsEventMap[WsEventType], frame.seq);
+      }
+    }
+  }
+
+  private startHeartbeat(intervalSec: number) {
+    this.stopHeartbeat();
+    if (!Number.isFinite(intervalSec) || intervalSec <= 0) {
+      console.error('Invalid heartbeat interval from server:', intervalSec);
+      return;
+    }
+    this.heartbeatIntervalMs = intervalSec * 1000;
+    this.heartbeatTimer = setInterval(() => {
+      // If no data received for >1.5× heartbeat interval, the connection may
+      // be stale — or the timer may have been delayed by browser throttling /
+      // event-loop stalls. Probe with a 5s timeout rather than force-
+      // reconnecting, so healthy connections that were merely timer-starved
+      // survive while genuinely dead sockets are caught quickly.
+      if (this.lastReceivedAt > 0 && Date.now() - this.lastReceivedAt > this.heartbeatIntervalMs * 1.5) {
+        this.probeConnection();
+        return;
+      }
+      this.send({ type: WS_EVENTS.PING, data: { ts: Date.now() } });
+    }, intervalSec * 1000);
+  }
+
+  private stopHeartbeat() {
+    if (this.heartbeatTimer) {
+      clearInterval(this.heartbeatTimer);
+      this.heartbeatTimer = null;
+    }
+  }
+
+  private scheduleReconnect() {
+    this.setState('reconnecting');
+    this.clearReconnect();
+
+    const base = Math.min(
+      this.options.reconnectInterval * Math.pow(2, this.reconnectAttempts),
+      this.options.maxReconnectInterval,
+    );
+    // Jitter: 50-100% of base delay to prevent thundering herd
+    const delay = base * (0.5 + Math.random() * 0.5);
+    this.reconnectAttempts++;
+
+    this.reconnectTimer = setTimeout(() => {
+      this.connect();
+    }, delay);
+  }
+
+  private clearReconnect() {
+    if (this.reconnectTimer) {
+      clearTimeout(this.reconnectTimer);
+      this.reconnectTimer = null;
+    }
+  }
+
+  /** Force-close a dead/stale connection and trigger reconnect. */
+  private forceReconnect() {
+    this.stopHeartbeat();
+    this.clearReconnect();
+    this.clearProbe();
+    if (this.ws) {
+      this.ws.onclose = null;
+      this.ws.onopen = null;
+      this.ws.onerror = null;
+      this.ws.onmessage = null;
+      try { this.ws.close(); } catch { /* ignore */ }
+      this.ws = null;
+    }
+    if (this.options.reconnect && !this.intentionalClose) {
+      this.scheduleReconnect();
+    } else {
+      this.setState('disconnected');
+    }
+  }
+
+  // ---- Browser event listeners for proactive reconnection ----
+
+  private setupBrowserListeners() {
+    if (this.browserListenersActive) return;
+    this.browserListenersActive = true;
+    if (typeof document !== 'undefined') {
+      document.addEventListener('visibilitychange', this.handleVisibilityChange);
+    }
+    if (typeof window !== 'undefined') {
+      window.addEventListener('online', this.handleOnline);
+    }
+  }
+
+  private teardownBrowserListeners() {
+    if (!this.browserListenersActive) return;
+    this.browserListenersActive = false;
+    if (typeof document !== 'undefined') {
+      document.removeEventListener('visibilitychange', this.handleVisibilityChange);
+    }
+    if (typeof window !== 'undefined') {
+      window.removeEventListener('online', this.handleOnline);
+    }
+  }
+
+  /**
+   * Send a ping and arm a short timeout. If no frame arrives within 5s the
+   * connection is assumed dead and force-reconnected. Any received frame
+   * (including the pong) cancels the timer via clearProbe() in handleFrame.
+   */
+  private probeConnection() {
+    if (this.probeTimer) return; // don't re-arm an active probe
+    this.send({ type: WS_EVENTS.PING, data: { ts: Date.now() } });
+    this.probeTimer = setTimeout(() => {
+      this.forceReconnect();
+    }, 5_000);
+  }
+
+  private clearProbe() {
+    if (this.probeTimer) {
+      clearTimeout(this.probeTimer);
+      this.probeTimer = null;
+    }
+  }
+
+  /** Tab returned to foreground — verify connection or accelerate reconnect. */
+  private handleVisibilityChange = () => {
+    if (typeof document !== 'undefined' && document.hidden) return;
+
+    if (this._state === 'connected') {
+      if (!this.ws || this.ws.readyState !== WebSocket.OPEN) {
+        this.forceReconnect();
+      } else {
+        // Probe liveness — do NOT reset lastReceivedAt here; a zombie socket
+        // may still report OPEN. The 5s probe timeout will catch it quickly
+        // instead of deferring to the next heartbeat cycle (~60s).
+        this.probeConnection();
+      }
+    } else if (this._state === 'reconnecting') {
+      // Skip remaining backoff — try immediately
+      this.clearReconnect();
+      this.reconnectAttempts = 0;
+      this.connect();
+    }
+  };
+
+  /** Network restored — accelerate reconnection. */
+  private handleOnline = () => {
+    if (this.intentionalClose) return;
+
+    if (this._state === 'connected') {
+      if (!this.ws || this.ws.readyState !== WebSocket.OPEN) {
+        this.forceReconnect();
+      } else {
+        this.probeConnection();
+      }
+    } else if (this._state === 'reconnecting') {
+      this.clearReconnect();
+      this.reconnectAttempts = 0;
+      this.connect();
+    }
+  };
+
+  private setState(state: WsConnectionState) {
+    this._state = state;
+    for (const listener of this.stateListeners) {
+      listener(state);
+    }
+  }
+}