@dev-crew-berlin/enter-js-utils 0.97.5 → 0.98.10

package/dist/api-client/api-base.d.ts

@@ -23,6 +23,12 @@ export type FetchOptions = {
         revalidate: false | 0 | number;
     };
 };
+export type SubscribeOptions = {
+    signal?: AbortSignal;
+    onReset?: () => void;
+    onConnectionChange?: (state: 'connected' | 'reconnecting') => void;
+    initialLastEventId?: string;
+};
 export default class APIBase {
     private credentials;
     private isLoggedIn;
@@ -36,8 +42,8 @@ export default class APIBase {
         onLogout: (reason?: string) => void;
     });
     private static fetchResult;
-    private buildHeaders;
-    private fetchResponse;
+    protected buildHeaders(extraHeaders?: Record<string, string>): Record<string, string>;
+    protected fetchResponse(endpoint: string, init: RequestInit): Promise<APIResult<Response>>;
     /**
      * @category Auth
      */
@@ -56,7 +62,22 @@ export default class APIBase {
         expires: Date;
     }>>;
     private fetchFromEnter;
-    protected stream<T>(endpoint: string, options?: FetchOptions): AsyncGenerator<T>;
+    /**
+     * Self-healing SSE stream with automatic reconnect, heartbeat watchdog, and
+     * cursor-based replay. Yields domain events as parsed JSON.
+     *
+     * Reconnect behaviour: when the connection drops (network error, server
+     * close, or watchdog timeout) the method sleeps with exponential backoff and
+     * jitter, then opens a new request. The last received SSE `id` is sent as
+     * `Last-Event-ID` so the server can replay missed events. Backoff resets
+     * after a connection that stayed alive long enough to be considered healthy.
+     *
+     * The loop exits without retrying on 401 (session expired — logout is
+     * handled by fetchResponse) or when the consumer breaks / the external
+     * signal fires.
+     */
+    protected stream<T>(endpoint: string, options?: SubscribeOptions): AsyncGenerator<T>;
+    private readSseEvents;
     protected get<Path extends keyof paths>(endpoint: Path, options: FetchOptions): Promise<APIResult<ResponseType<Path, 'get'>>>;
     protected post<Path extends keyof paths>(endpoint: Path, data: RequestBody<Path, 'post'>, options: FetchOptions): Promise<APIResult<ResponseType<Path, 'post'>>>;
     protected put<Path extends keyof paths>(endpoint: Path, data: RequestBody<Path, 'put'>, options: FetchOptions): Promise<APIResult<ResponseType<Path, 'put'>>>;

package/dist/api-client/api-base.js

@@ -1,6 +1,21 @@
 import jws from 'jws';
 import { EventSourceParserStream } from 'eventsource-parser/stream';
 import { failure, success } from '../lib';
+const BACKOFF_INITIAL_MS = 1_000;
+const BACKOFF_MAX_MS = 30_000;
+const BACKOFF_RESET_AFTER_MS = 10_000;
+const WATCHDOG_TIMEOUT_MS = 45_000;
+function sleep(ms, signal) {
+  return new Promise(resolve => {
+    const timer = setTimeout(resolve, ms);
+    signal.addEventListener('abort', () => {
+      clearTimeout(timer);
+      resolve();
+    }, {
+      once: true
+    });
+  });
+}
 export default class APIBase {
   constructor(args) {
     this.credentials = args.credentials;
@@ -135,21 +150,121 @@ export default class APIBase {
     const json = await res.data.json();
     return success(json);
   }
+
+  /**
+   * Self-healing SSE stream with automatic reconnect, heartbeat watchdog, and
+   * cursor-based replay. Yields domain events as parsed JSON.
+   *
+   * Reconnect behaviour: when the connection drops (network error, server
+   * close, or watchdog timeout) the method sleeps with exponential backoff and
+   * jitter, then opens a new request. The last received SSE `id` is sent as
+   * `Last-Event-ID` so the server can replay missed events. Backoff resets
+   * after a connection that stayed alive long enough to be considered healthy.
+   *
+   * The loop exits without retrying on 401 (session expired — logout is
+   * handled by fetchResponse) or when the consumer breaks / the external
+   * signal fires.
+   */
   async *stream(endpoint, options = {}) {
-    const res = await this.fetchResponse(endpoint, {
-      method: 'GET',
-      headers: this.buildHeaders({
-        Accept: 'text/event-stream'
-      }),
-      ...options
-    });
-    if (!res.success) {
-      throw new Error(res.error[0]?.message ?? 'Unknown error');
-    }
-    if (!res.data.body) {
-      throw new Error('Response body is null');
+    const {
+      signal: externalSignal,
+      onReset,
+      onConnectionChange
+    } = options;
+
+    // outerAbort is the single switch that stops the whole reconnect loop.
+    // It is wired to the external signal and also fired in the finally block
+    // so that the sleep() in the backoff path is always interrupted on exit.
+    const outerAbort = new AbortController();
+    if (externalSignal?.aborted) return;
+    const onExternalAbort = () => outerAbort.abort();
+    externalSignal?.addEventListener('abort', onExternalAbort);
+    let lastEventId = options.initialLastEventId ?? null;
+    let backoffMs = BACKOFF_INITIAL_MS;
+    let isFirstConnect = true;
+    try {
+      while (!outerAbort.signal.aborted) {
+        // Fresh abort controller per attempt so the watchdog or a read error
+        // on one attempt cannot bleed into the next.
+        const attemptAbort = new AbortController();
+        const propagateAbort = () => attemptAbort.abort();
+        outerAbort.signal.addEventListener('abort', propagateAbort);
+        const hadCursor = lastEventId !== null;
+        const headers = {
+          Accept: 'text/event-stream'
+        };
+        // Sending Last-Event-ID lets the server replay events we missed while
+        // disconnected. If the cursor is unknown or too old, the server replies
+        // with event:reset instead of replaying.
+        if (hadCursor) headers['Last-Event-ID'] = lastEventId;
+
+        // connectedAt stays 0 when the attempt never reached a live stream,
+        // which prevents a spurious backoff reset on pure network failures.
+        let connectedAt = 0;
+        try {
+          const res = await this.fetchResponse(endpoint, {
+            method: 'GET',
+            headers: this.buildHeaders(headers),
+            signal: attemptAbort.signal
+          });
+          if (!res.success) {
+            const err = res.error[0];
+            // 401 means the session is gone — fetchResponse already called
+            // logout(), so stop retrying rather than hammering the server.
+            if (err?.type === 'http-error' && err.statusCode === 401) return;
+            // Any other failure (network error, 5xx, …) falls through to backoff.
+          } else if (res.data.body) {
+            connectedAt = Date.now();
+            onConnectionChange?.('connected');
+            // On a reconnect with no cursor we cannot know what events were
+            // missed, so tell the consumer to refetch their full state.
+            if (!isFirstConnect && !hadCursor) onReset?.();
+            isFirstConnect = false;
+            for await (const {
+              data,
+              id
+            } of this.readSseEvents(res.data.body, attemptAbort, onReset)) {
+              if (id) lastEventId = id;
+              yield data;
+            }
+          }
+        } catch {
+          // Covers fetch throwing (network error) and the stream aborting
+          // mid-read — both fall through to the backoff sleep below.
+        } finally {
+          outerAbort.signal.removeEventListener('abort', propagateAbort);
+          attemptAbort.abort();
+        }
+        if (outerAbort.signal.aborted) break;
+
+        // Reset backoff when the previous connection was healthy long enough;
+        // otherwise double it (with jitter) up to the cap.
+        const lived = connectedAt > 0 ? Date.now() - connectedAt : 0;
+        if (lived >= BACKOFF_RESET_AFTER_MS) backoffMs = BACKOFF_INITIAL_MS;
+        onConnectionChange?.('reconnecting');
+        await sleep(backoffMs, outerAbort.signal);
+        backoffMs = Math.min(backoffMs * 2, BACKOFF_MAX_MS) * (0.5 + Math.random());
+      }
+    } finally {
+      // Aborting here also unblocks any in-progress sleep() call.
+      outerAbort.abort();
+      externalSignal?.removeEventListener('abort', onExternalAbort);
     }
-    const reader = res.data.body.pipeThrough(new TextDecoderStream()).pipeThrough(new EventSourceParserStream()).getReader();
+  }
+
+  // Reads parsed SSE events from a single response body until the stream
+  // closes or the attemptAbort signal fires. Manages the heartbeat watchdog:
+  // if no message arrives within WATCHDOG_TIMEOUT_MS the connection is
+  // considered half-open (common on mobile networks) and is aborted so the
+  // outer loop can reconnect.
+  async *readSseEvents(body, attemptAbort, onReset) {
+    const reader = body.pipeThrough(new TextDecoderStream()).pipeThrough(new EventSourceParserStream()).getReader();
+    let watchdogTimer = null;
+    const resetWatchdog = () => {
+      if (watchdogTimer) clearTimeout(watchdogTimer);
+      watchdogTimer = setTimeout(() => attemptAbort.abort(), WATCHDOG_TIMEOUT_MS);
+    };
+    resetWatchdog();
     try {
       while (true) {
         const {
@@ -157,15 +272,31 @@ export default class APIBase {
           value: event
         } = await reader.read();
         if (done) break;
-        if (event.data === '[DONE]') return;
+
+        // Any message — including heartbeats — proves the connection is alive.
+        resetWatchdog();
+
+        // Heartbeats are only keepalives; never yield them to the consumer.
+        if (event.event === 'heartbeat') continue;
+        // The server sends reset when the requested cursor is unknown or too
+        // old. The consumer should refetch full state; we do not yield it.
+        if (event.event === 'reset') {
+          onReset?.();
+          continue;
+        }
         try {
-          yield JSON.parse(event.data);
+          yield {
+            data: JSON.parse(event.data),
+            id: event.id
+          };
         } catch {
           console.warn('[SSE] Failed to parse event data:', event.data);
         }
       }
     } finally {
+      if (watchdogTimer) clearTimeout(watchdogTimer);
       reader.releaseLock();
+      attemptAbort.abort();
     }
   }
   async get(endpoint, options) {