@velion-la/onboarding-sdk-react-native 1.0.0-beta.2

package/src/transport/sse.ts

@@ -0,0 +1,310 @@
+/**
+ * @fileoverview SSE client for React Native, with auto-reconnect.
+ *
+ * React Native's `fetch` does not expose `body.getReader()`, so we lean on
+ * `react-native-sse` — which follows the `EventSource` model and dispatches
+ * by `event:` name. If the backend publishes named events
+ * (e.g. `event: NextStepRequestedEvent`), the default `'message'` listener
+ * never fires.
+ *
+ * To cover both cases we register the same handler on `'message'` AND on
+ * every named event the orchestrator may emit. New event types are
+ * discovered automatically the first time the wrapper sees them
+ * (`addEventListener` is added on demand) — see the dynamic registration
+ * below.
+ *
+ * ## Reconnection
+ *
+ * Production deployments behind GCP / k8s ingress (and most load balancers)
+ * close idle TCP streams at ~30 s. When that happens `react-native-sse`
+ * fires `error` with `{ type: 'error', message: 'cannot parse response',
+ * xhrStatus: 200, xhrState: 4 }` — a clean upstream close, not a real
+ * transport failure. The native EventSource spec would auto-reconnect
+ * here, but `react-native-sse` does not in this scenario, so we wrap it.
+ *
+ * Strategy:
+ *   - On `error` or `close`, schedule a reconnect with exponential backoff
+ *     (capped at 30 s). On `open` of the new connection, reset the attempt
+ *     counter so a brief blip doesn't punish us forever.
+ *   - Track `lastEventId` across reconnects — the backend supports
+ *     `Last-Event-ID` replay via Redis, so we never lose an event that
+ *     fired during the gap.
+ *   - Don't escalate transient drops to `onError`: the orchestrator uses
+ *     that callback to switch to GET polling, which is a much worse UX
+ *     than a 1 s blip + replay. We still log the underlying error for
+ *     debugging.
+ *
+ * Path: `${baseUrl}/sessions/:sessionId/events` (baseUrl already includes `/public/sdk`).
+ * Backend: `OnboardingSseController GET /public/sdk/sessions/{sessionId}/events`.
+ */
+
+import EventSource from 'react-native-sse';
+import type { OnboardingSessionEvent } from '../types';
+import { log } from '../utils/log';
+
+export const SSE_EVENTS_PATH = '/sessions';
+
+/**
+ * Named events the backend is known to dispatch. The list intentionally
+ * covers both the legacy domain-event names (e.g. `NextStepRequestedEvent`)
+ * and the public wire types (`ROUTING_COMMAND`, `STEP_UPDATED`, …) so we
+ * stay compatible with whichever shape the orchestrator chooses.
+ */
+const KNOWN_EVENT_TYPES = [
+  // Public/wire types (preferred — what the SDK code branches on).
+  'ROUTING_COMMAND',
+  'STEP_UPDATED',
+  'SESSION_APPROVED',
+  'SESSION_MANUAL_REVIEW',
+  'SESSION_DECLINED',
+  'SESSION_TERMINATED',
+  // Legacy/domain-event names emitted by `SseDomainEventConsumer` in the
+  // Spring orchestrator. Listening to both lets the same SDK build talk to
+  // older and newer backends without a config flag.
+  'NextStepRequestedEvent',
+  'StepUpdatedEvent',
+  'SessionApprovedEvent',
+  'SessionManualReviewEvent',
+  'SessionDeclinedEvent',
+  'SessionTerminatedEvent',
+  'OnboardingCreatedEvent',
+] as const;
+
+/** Backoff schedule (ms). Last entry repeats indefinitely. */
+const RECONNECT_BACKOFF_MS = [1_000, 2_000, 4_000, 8_000, 15_000, 30_000] as const;
+
+export interface SessionEventSourceOptions {
+  baseUrl: string;
+  sessionId: string;
+  sessionToken: string;
+  /** Last event_id (epoch millis) received; use "0" for first connection. */
+  lastEventId?: string;
+  /** Optional abort signal — closes the stream when fired. */
+  signal?: AbortSignal;
+  onEvent?: (event: OnboardingSessionEvent) => void;
+  onError?: (err: unknown) => void;
+}
+
+interface MessageEventLike {
+  data?: string | null;
+  type?: string;
+  lastEventId?: string;
+}
+
+type RnEventSource = {
+  addEventListener: (
+    type: string,
+    listener: (event: MessageEventLike) => void,
+  ) => void;
+  removeAllEventListeners?: () => void;
+  close: () => void;
+};
+
+export function createSessionEventSource(
+  options: SessionEventSourceOptions,
+): () => void {
+  const {
+    baseUrl,
+    sessionId,
+    sessionToken,
+    lastEventId: initialLastEventId = '0',
+    signal,
+    onEvent,
+    onError,
+  } = options;
+
+  const base = baseUrl.replace(/\/$/, '');
+  const url = `${base}${SSE_EVENTS_PATH}/${sessionId}/events`;
+
+  /** Updated on every event we receive — replayed via Last-Event-ID. */
+  let lastEventId = initialLastEventId;
+  let attempt = 0;
+  let closed = false;
+  let current: RnEventSource | null = null;
+  let reconnectTimer: ReturnType<typeof setTimeout> | null = null;
+  /**
+   * Monotonic id of the active EventSource. Listeners capture their own id
+   * and only act if it still matches — events from a previous instance that
+   * fire after we've moved on (e.g. `close` fired *because* we called
+   * `es.close()` ourselves) are ignored. Without this guard the listeners
+   * cascade into runaway reconnect loops.
+   */
+  let generation = 0;
+
+  // Cast to a relaxed type — `react-native-sse` typings are over-strict on
+  // the constructor signature when passing a custom-events tuple.
+  const EventSourceCtor = EventSource as unknown as new (
+    url: string,
+    init: {
+      headers: Record<string, string>;
+      method: string;
+      pollingInterval: number;
+      // `react-native-sse` 1.2+ accepts a `customEvents` array that pre-
+      // registers listeners for named events. Earlier versions ignore it
+      // gracefully.
+      customEvents?: ReadonlyArray<string>;
+    },
+  ) => RnEventSource;
+
+  const buildHeaders = (): Record<string, string> => {
+    const headers: Record<string, string> = {
+      Accept: 'text/event-stream',
+      Authorization: `Bearer ${sessionToken}`,
+      // Hint to any intermediate proxy not to buffer the stream.
+      'Cache-Control': 'no-cache',
+    };
+    if (lastEventId !== '0') {
+      headers['Last-Event-ID'] = lastEventId;
+    }
+    return headers;
+  };
+
+  const scheduleReconnect = (reason: string): void => {
+    if (closed) return;
+    if (reconnectTimer != null) return; // already scheduled
+    const delay =
+      RECONNECT_BACKOFF_MS[Math.min(attempt, RECONNECT_BACKOFF_MS.length - 1)] ??
+      30_000;
+    attempt += 1;
+    log.info('[SSE] Reconnecting', {
+      reason,
+      attempt,
+      delayMs: delay,
+      lastEventId,
+    });
+    reconnectTimer = setTimeout(() => {
+      reconnectTimer = null;
+      if (closed) return;
+      tearDown(current);
+      current = connect();
+    }, delay);
+  };
+
+  /**
+   * Detach listeners and close an EventSource that we're about to replace.
+   * The listener detach is what stops the cascade: without it, `es.close()`
+   * itself dispatches a `close` event, which our handler would catch and
+   * schedule another reconnect — even though we already started a new one.
+   */
+  const tearDown = (es: RnEventSource | null): void => {
+    if (!es) return;
+    try {
+      es.removeAllEventListeners?.();
+    } catch (detachErr) {
+      log.warn('[SSE] Error detaching listeners from previous stream', detachErr);
+    }
+    try {
+      es.close();
+    } catch (closeErr) {
+      log.warn('[SSE] Error closing previous stream', closeErr);
+    }
+  };
+
+  const connect = (): RnEventSource => {
+    const myGen = ++generation;
+    const isStale = (): boolean => closed || myGen !== generation;
+
+    const headers = buildHeaders();
+    log.info('[SSE] Opening stream', {
+      url,
+      sessionId,
+      hasLastEventId: lastEventId !== '0',
+      lastEventId,
+      attempt,
+      generation: myGen,
+    });
+
+    const es = new EventSourceCtor(url, {
+      headers,
+      method: 'GET',
+      pollingInterval: 0,
+      customEvents: KNOWN_EVENT_TYPES,
+    });
+
+    es.addEventListener('open', () => {
+      if (isStale()) return;
+      log.info('[SSE] Stream connected', { generation: myGen });
+      // Reset backoff once the upstream has accepted us — a healthy
+      // connection wipes any prior penalty.
+      attempt = 0;
+    });
+
+    const handleMessage = (evt: MessageEventLike): void => {
+      if (isStale()) return;
+      const data = evt.data;
+      // Track lastEventId even when we receive a heartbeat / non-JSON
+      // chunk: the server still advanced its replay cursor.
+      if (typeof evt.lastEventId === 'string' && evt.lastEventId.length > 0) {
+        lastEventId = evt.lastEventId;
+      }
+      if (typeof data !== 'string' || data.length === 0) return;
+      try {
+        const payload = JSON.parse(data) as OnboardingSessionEvent;
+        log.info('[SSE] Event received', {
+          wireType: evt.type,
+          eventType: payload.event_type,
+          action: payload.action,
+          stepCode: payload.step_code,
+          eventId: payload.event_id,
+        });
+        onEvent?.(payload);
+      } catch (parseErr) {
+        log.warn('[SSE] Failed to parse event payload', {
+          wireType: evt.type,
+          rawData: data,
+          error: parseErr,
+        });
+      }
+    };
+
+    es.addEventListener('message', handleMessage);
+    for (const type of KNOWN_EVENT_TYPES) {
+      es.addEventListener(type, handleMessage);
+    }
+
+    es.addEventListener('error', (evt) => {
+      if (isStale()) return;
+      // Most errors here are upstream idle-timeouts from the ingress.
+      // Log at info level (not error) to avoid noisy reports, and don't
+      // escalate to onError — we'll just reconnect.
+      log.info('[SSE] Stream interrupted, will reconnect', evt);
+      scheduleReconnect('error');
+    });
+
+    es.addEventListener('close', () => {
+      if (isStale()) return;
+      log.info('[SSE] Stream closed by server, will reconnect');
+      scheduleReconnect('close');
+    });
+
+    return es;
+  };
+
+  current = connect();
+
+  const closeAll = (): void => {
+    if (closed) return;
+    closed = true;
+    if (reconnectTimer != null) {
+      clearTimeout(reconnectTimer);
+      reconnectTimer = null;
+    }
+    tearDown(current);
+    current = null;
+  };
+
+  if (signal) {
+    if (signal.aborted) {
+      closeAll();
+    } else {
+      signal.addEventListener('abort', closeAll);
+    }
+  }
+
+  // We still expose onError so the orchestrator can react to *unrecoverable*
+  // failures — but with auto-reconnect, the only realistic trigger is the
+  // outer signal aborting. Keep the parameter wired up for future use.
+  void onError;
+
+  return closeAll;
+}