@parlr/react-native 0.1.0

package/src/core/websocket.ts

@@ -0,0 +1,270 @@
+// ---------------------------------------------------------------------------
+// Parlr React Native SDK - WebSocket Real-Time Client
+// ---------------------------------------------------------------------------
+//
+// Manages the persistent WebSocket connection to the Parlr gateway.
+// Features: auto-reconnect with exponential backoff, keep-alive pings,
+// typed event emitter, and clean teardown.
+// ---------------------------------------------------------------------------
+
+import type {
+  ResolvedConfig,
+  WsEventMap,
+  WsIncomingPayload,
+  WsIncomingType,
+  WsOutgoingPayload,
+} from './types';
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+type Listener<T extends WsIncomingType> = (payload: WsEventMap[T]) => void;
+
+export interface ParlrWebSocket {
+  /** Open the connection (idempotent). */
+  connect(sessionToken: string): void;
+  /** Gracefully close the connection. Will NOT auto-reconnect. */
+  disconnect(): void;
+  /** Send a typed frame. */
+  send(frame: WsOutgoingPayload): void;
+  /** Subscribe to a specific incoming event type. Returns unsubscribe fn. */
+  on<T extends WsIncomingType>(type: T, listener: Listener<T>): () => void;
+  /** Whether the socket is currently open. */
+  readonly connected: boolean;
+}
+
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+
+const PING_INTERVAL_MS = 25_000;
+const INITIAL_RECONNECT_MS = 1_000;
+const MAX_RECONNECT_MS = 30_000;
+
+// ---------------------------------------------------------------------------
+// Factory
+// ---------------------------------------------------------------------------
+
+/**
+ * Create a no-op WebSocket stub when wsUrl is not configured.
+ * All methods are safe to call but do nothing.
+ */
+function createNoopWebSocket(): ParlrWebSocket {
+  return {
+    get connected() { return false; },
+    connect() {},
+    disconnect() {},
+    send() {},
+    on() { return () => {}; },
+  };
+}
+
+export function createWebSocket(config: ResolvedConfig): ParlrWebSocket {
+  if (!config.wsUrl) {
+    return createNoopWebSocket();
+  }
+  let ws: WebSocket | null = null;
+  let sessionToken: string | null = null;
+  let intentionalClose = false;
+  let reconnectDelay = INITIAL_RECONNECT_MS;
+  let reconnectTimer: ReturnType<typeof setTimeout> | null = null;
+  let pingTimer: ReturnType<typeof setInterval> | null = null;
+  let lastPongAt: number = 0;
+  let pongCheckTimer: ReturnType<typeof setInterval> | null = null;
+
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  const listeners = new Map<WsIncomingType, Set<(payload: any) => void>>();
+
+  // --- Helpers ---------------------------------------------------------------
+
+  function log(...args: unknown[]) {
+    if (config.debug) {
+      console.log('[@parlr/react-native][ws]', ...args);
+    }
+  }
+
+  function emit(type: WsIncomingType, /* istanbul ignore next */ payload: Record<string, unknown> = {}) {
+    const set = listeners.get(type);
+    if (set) {
+      for (const fn of set) {
+        try {
+          fn(payload);
+        } catch (err) {
+          console.error('[@parlr/react-native][ws] listener error:', err);
+        }
+      }
+    }
+  }
+
+  function clearTimers() {
+    if (pingTimer) {
+      clearInterval(pingTimer);
+      pingTimer = null;
+    }
+    if (reconnectTimer) {
+      clearTimeout(reconnectTimer);
+      reconnectTimer = null;
+    }
+    if (pongCheckTimer) {
+      clearInterval(pongCheckTimer);
+      pongCheckTimer = null;
+    }
+  }
+
+  function startPing() {
+    lastPongAt = Date.now();
+
+    pingTimer = setInterval(() => {
+      if (ws?.readyState === WebSocket.OPEN) {
+        ws.send(JSON.stringify({ type: 'ping' }));
+      }
+    }, PING_INTERVAL_MS);
+
+    // Check for pong timeout: if no pong received in 2x PING_INTERVAL, force reconnect.
+    pongCheckTimer = setInterval(() => {
+      if (Date.now() - lastPongAt > PING_INTERVAL_MS * 2) {
+        log('Pong timeout — forcing reconnect');
+        clearTimers();
+        if (ws) {
+          try { ws.close(); } catch { /* ignore */ }
+        }
+        scheduleReconnect();
+      }
+    }, PING_INTERVAL_MS);
+  }
+
+  function scheduleReconnect() {
+    if (intentionalClose) return;
+
+    const jitter = Math.random() * 500;
+    const wait = Math.min(reconnectDelay + jitter, MAX_RECONNECT_MS);
+    log(`Reconnecting in ${Math.round(wait)}ms`);
+
+    reconnectTimer = setTimeout(() => {
+      reconnectDelay = Math.min(reconnectDelay * 2, MAX_RECONNECT_MS);
+      if (sessionToken) {
+        doConnect(sessionToken);
+      }
+    }, wait);
+  }
+
+  // --- Core connection -------------------------------------------------------
+
+  function doConnect(token: string) {
+    clearTimers();
+
+    if (ws) {
+      try {
+        ws.close();
+      } catch {
+        // ignore
+      }
+    }
+
+    const url = config.wsUrl;
+    log('Connecting to', url);
+
+    ws = new WebSocket(url);
+
+    ws.onopen = () => {
+      log('Connected');
+      reconnectDelay = INITIAL_RECONNECT_MS;
+
+      // Authenticate immediately after opening.
+      ws!.send(
+        JSON.stringify({
+          type: 'auth',
+          payload: { token, workspaceId: config.workspaceId },
+        }),
+      );
+
+      startPing();
+    };
+
+    ws.onmessage = (event) => {
+      try {
+        const raw = String(event.data);
+        const frame = JSON.parse(raw) as WsIncomingPayload;
+
+        if (!frame || typeof frame.type !== 'string') {
+          log('Received invalid frame (missing type):', raw);
+          return;
+        }
+
+        // Track pong responses for keep-alive validation.
+        if (frame.type === 'pong') {
+          lastPongAt = Date.now();
+        }
+
+        log('<-', frame.type, frame.payload);
+        emit(frame.type, frame.payload ?? {});
+      } catch (err) {
+        log('Failed to parse frame:', err);
+      }
+    };
+
+    ws.onerror = (event) => {
+      log('Error:', event);
+    };
+
+    ws.onclose = (event) => {
+      log('Closed:', event.code, event.reason);
+      clearTimers();
+
+      // Only emit auth_error for authentication-related close codes.
+      if (event.code === 4001 || event.code === 4003) {
+        emit('auth_error', { code: event.code, reason: event.reason });
+      } else if (!intentionalClose) {
+        emit('disconnected', { code: event.code, reason: event.reason });
+      }
+
+      scheduleReconnect();
+    };
+  }
+
+  // --- Public API ------------------------------------------------------------
+
+  return {
+    get connected(): boolean {
+      return ws?.readyState === WebSocket.OPEN;
+    },
+
+    connect(token: string) {
+      sessionToken = token;
+      intentionalClose = false;
+      reconnectDelay = INITIAL_RECONNECT_MS;
+      doConnect(token);
+    },
+
+    disconnect() {
+      intentionalClose = true;
+      clearTimers();
+      sessionToken = null;
+      if (ws) {
+        ws.close(1000, 'Client disconnect');
+        ws = null;
+      }
+    },
+
+    send(frame: WsOutgoingPayload) {
+      if (ws?.readyState === WebSocket.OPEN) {
+        log('->', frame.type, frame.payload);
+        ws.send(JSON.stringify(frame));
+      } else {
+        log('Cannot send, socket not open. Frame:', frame.type);
+      }
+    },
+
+    on<T extends WsIncomingType>(type: T, listener: Listener<T>): () => void {
+      if (!listeners.has(type)) {
+        listeners.set(type, new Set());
+      }
+      listeners.get(type)!.add(listener);
+
+      return () => {
+        listeners.get(type)?.delete(listener);
+      };
+    },
+  };
+}