fix(sse): apply reconnect budget to browser-level (CONNECTING) retries

Co-authored-by: JavanPoirier <42590458+JavanPoirier@users.noreply.github.com>

Author: Copilot

packages/sse/src/sse.ts

@@ -83,8 +83,10 @@ export type CreateSSEOptions<T> = SSEOptions & {
    * - `true`: reconnect with defaults (Infinity retries, 3000ms delay)
    * - object: custom `{ retries?, delay? }`
    *
-   * Note: `EventSource` already reconnects natively for transient network
-   * drops. This option handles cases where the browser gives up entirely.
+   * The `retries` budget is shared across both browser-level retries
+   * (readyState stays CONNECTING) and app-level reconnects (readyState →
+   * CLOSED). Once the budget is exhausted the connection is fully torn down,
+   * stopping any further browser-driven retry loops.
    */
   reconnect?: boolean | SSEReconnectOptions;
   /**
@@ -227,6 +229,13 @@ export const createSSE = <T = string>(
   // ── Connection management ─────────────────────────────────────────────────
   let currentCleanup: VoidFunction | undefined;
 
+  /** Tears down the current source without scheduling a reconnect. */
+  const teardown = () => {
+    currentCleanup?.();
+    currentCleanup = undefined;
+    setSource(undefined);
+  };
+
   /** Open a fresh connection, resetting the retry counter. */
   const connect = (resolvedUrl: string) => {
     retriesLeft = reconnectConfig.retries ?? 0;
@@ -255,16 +264,26 @@ export const createSSE = <T = string>(
       setError(() => e);
       options.onError?.(e);
 
-      // Only app-level reconnect when the browser has given up (CLOSED).
-      // When readyState is still CONNECTING the browser is handling retries.
+      // When the browser has given up (CLOSED), perform app-level reconnects
+      // against the configured budget.
+      // When the browser is still retrying (CONNECTING) and a reconnect budget
+      // is configured, count those attempts too so the config is always honoured
+      // and the browser can never loop infinitely beyond the configured limit.
       if (es.readyState === SSEReadyState.CLOSED && retriesLeft > 0) {
         retriesLeft--;
         reconnectTimer = setTimeout(() => _open(resolvedUrl), reconnectConfig.delay ?? 3000);
       } else if (es.readyState === SSEReadyState.CLOSED) {
         // Retries exhausted — clean up fully to avoid memory/listener leaks.
-        currentCleanup?.();
-        currentCleanup = undefined;
-        setSource(undefined);
+        teardown();
+      } else if (es.readyState === SSEReadyState.CONNECTING && options.reconnect) {
+        // Browser is retrying. Consume the budget; when it's gone, abort so
+        // we don't loop forever against the user's configured retry limit.
+        if (retriesLeft > 0) {
+          retriesLeft--;
+        } else {
+          teardown();
+          setReadyState(SSEReadyState.CLOSED);
+        }
       }
     };
 
@@ -285,9 +304,7 @@ export const createSSE = <T = string>(
   const disconnect = () => {
     clearReconnectTimer();
     retriesLeft = 0;
-    currentCleanup?.();
-    currentCleanup = undefined;
-    setSource(undefined);
+    teardown();
     setReadyState(SSEReadyState.CLOSED);
   };
 
@@ -314,10 +331,7 @@ export const createSSE = <T = string>(
       const resolvedUrl = url();
       if (resolvedUrl !== prevUrl) {
         prevUrl = resolvedUrl;
-        untrack(() => {
-          currentCleanup?.();
-          currentCleanup = undefined;
-        });
+        untrack(() => teardown());
         connect(resolvedUrl);
       }
     });
@@ -326,8 +340,7 @@ export const createSSE = <T = string>(
   // ── Lifecycle cleanup ─────────────────────────────────────────────────────
   onCleanup(() => {
     clearReconnectTimer();
-    currentCleanup?.();
-    currentCleanup = undefined;
+    teardown();
   });
 
   return { source, data, error, readyState, close: disconnect, reconnect: manualReconnect };

packages/sse/test/index.test.ts

@@ -144,7 +144,7 @@ describe("createSSE", () => {
       dispose();
     }));
 
-  it("does not app-reconnect on transient errors (browser handles those)", () =>
+  it("does not open a new connection on transient errors (browser retries natively)", () =>
     createRoot(dispose => {
       const initialCount = SSEInstances.length;
       const { source } = createSSE("https://example.com/events", {
@@ -153,7 +153,41 @@ describe("createSSE", () => {
       vi.advanceTimersByTime(20);
       (source() as unknown as MockEventSource).simulateTransientError();
       vi.advanceTimersByTime(300);
-      // readyState stayed CONNECTING → no new EventSource was created
+      // readyState stayed CONNECTING → no new EventSource was created, but
+      // the retry budget was decremented by 1 (from 5 to 4).
+      expect(SSEInstances.length).toBe(initialCount + 1);
+      dispose();
+    }));
+
+  it("stops browser retry loop when reconnect budget is exhausted via transient errors", () =>
+    createRoot(dispose => {
+      const { source, readyState } = createSSE("https://example.com/events", {
+        reconnect: { retries: 2, delay: 50 },
+      });
+      vi.advanceTimersByTime(20);
+      const es = source() as unknown as MockEventSource;
+      const closeSpy = vi.spyOn(es, "close");
+      // Two transient errors consume the full budget (2→1→0).
+      es.simulateTransientError(); // retries: 2→1
+      es.simulateTransientError(); // retries: 1→0
+      // A third transient error exhausts the budget → connection must be stopped.
+      es.simulateTransientError();
+      expect(closeSpy).toHaveBeenCalledOnce();
+      expect(source()).toBeUndefined();
+      expect(readyState()).toBe(SSEReadyState.CLOSED);
+      dispose();
+    }));
+
+  it("does not affect transient errors when reconnect is not configured", () =>
+    createRoot(dispose => {
+      const initialCount = SSEInstances.length;
+      const { source } = createSSE("https://example.com/events");
+      vi.advanceTimersByTime(20);
+      const es = source() as unknown as MockEventSource;
+      // Transient errors with no reconnect config should not kill the connection.
+      es.simulateTransientError();
+      es.simulateTransientError();
+      expect(source()).toBe(es);
       expect(SSEInstances.length).toBe(initialCount + 1);
       dispose();
     }));