@cleocode/core 2026.3.76 → 2026.4.2

package/src/conduit/__tests__/sse-transport.test.js

@@ -0,0 +1,291 @@
+/**
+ * SseTransport test scenarios.
+ *
+ * Tests for the Server-Sent Events transport implementation.
+ * SseTransport extends HTTP polling with real-time push via SSE,
+ * falling back to HTTP polling when SSE is unavailable.
+ *
+ * @see packages/contracts/src/transport.ts — Transport interface
+ * @see packages/contracts/src/conduit.ts — ConduitState types
+ * @task T216
+ */
+import { describe, expect, it, vi } from 'vitest';
+import { SseTransport } from '../sse-transport.js';
+// ============================================================================
+// Test helpers
+// ============================================================================
+/** Mock SSE event source that simulates server-sent events. */
+function createMockEventSource() {
+    const handlers = {};
+    return {
+        addEventListener: vi.fn((type, handler) => {
+            handlers[type] = handlers[type] || [];
+            handlers[type].push(handler);
+        }),
+        removeEventListener: vi.fn(),
+        close: vi.fn(),
+        readyState: 0, // CONNECTING
+        /** Simulate receiving an SSE event. */
+        _emit(type, data) {
+            for (const h of handlers[type] || []) {
+                h(new MessageEvent(type, { data }));
+            }
+        },
+        /** Simulate connection open. */
+        _open() {
+            this.readyState = 1; // OPEN
+            for (const h of handlers['open'] || []) {
+                h(new MessageEvent('open', { data: '' }));
+            }
+        },
+        /** Simulate connection error. */
+        _error() {
+            this.readyState = 2; // CLOSED
+            for (const h of handlers['error'] || []) {
+                h(new MessageEvent('error', { data: '' }));
+            }
+        },
+    };
+}
+/** Standard test config for SseTransport. */
+const TEST_CONFIG = {
+    agentId: 'test-agent',
+    apiKey: 'sk_live_test123',
+    apiBaseUrl: 'https://api.signaldock.io',
+    sseEndpoint: 'https://api.signaldock.io/sse',
+};
+// ============================================================================
+// Connection lifecycle
+// ============================================================================
+describe('SseTransport', () => {
+    describe('connect', () => {
+        it.todo('should establish SSE connection to sseEndpoint');
+        // Expected behavior:
+        // - Creates EventSource to config.sseEndpoint with auth headers
+        // - Sets transport name to 'sse'
+        // - Transitions state: disconnected → connecting → connected
+        // - Resolves when EventSource 'open' event fires
+        it.todo('should fall back to HTTP polling when SSE endpoint is unreachable');
+        // Expected behavior:
+        // - Attempts SSE connection
+        // - On connection error, transitions to HTTP polling mode
+        // - State: disconnected → connecting → connected (via HTTP fallback)
+        // - Logs warning: "SSE unavailable, falling back to HTTP polling"
+        // - poll() still works via HTTP
+        it.todo('should include auth headers in SSE connection');
+        // Expected behavior:
+        // - EventSource URL includes ?token=<apiKey> (SSE doesn't support custom headers)
+        // - Or uses a pre-flight auth endpoint to get a session token
+        // - X-Agent-Id is conveyed via query param or pre-flight
+        it.todo('should reject connect when no sseEndpoint or apiBaseUrl is configured');
+        // Expected behavior:
+        // - Throws Error with message indicating missing config
+        // - State remains 'disconnected'
+        it('rejects connect when no sseEndpoint or apiBaseUrl provided', async () => {
+            const transport = new SseTransport();
+            await expect(transport.connect({ agentId: 'test', apiKey: 'key', apiBaseUrl: '' })).rejects.toThrow('requires');
+        });
+        it.todo('should reject connect when already connected');
+        // Expected behavior:
+        // - Second connect() call throws or is no-op
+        // - Does not create duplicate EventSource instances
+        it('has name "sse"', () => {
+            const transport = new SseTransport();
+            expect(transport.name).toBe('sse');
+        });
+    });
+    // ============================================================================
+    // Disconnect
+    // ============================================================================
+    describe('disconnect', () => {
+        it.todo('should close SSE connection and clear state');
+        // Expected behavior:
+        // - Calls EventSource.close()
+        // - Clears internal state
+        // - State: connected → disconnected
+        // - Subsequent push/poll calls throw "not connected"
+        it.todo('should be idempotent when already disconnected');
+        // Expected behavior:
+        // - No error when calling disconnect() on already disconnected transport
+        // - State remains 'disconnected'
+        it('is safe to call disconnect when not connected', async () => {
+            const transport = new SseTransport();
+            await transport.disconnect(); // Should not throw
+            await transport.disconnect(); // Still should not throw
+        });
+        it.todo('should cancel any pending poll timers');
+        // Expected behavior:
+        // - If HTTP fallback polling is active, clears interval
+        // - No orphaned timers after disconnect
+    });
+    // ============================================================================
+    // Reconnect
+    // ============================================================================
+    describe('reconnect', () => {
+        it.todo('should automatically reconnect on SSE connection drop');
+        // Expected behavior:
+        // - When EventSource fires 'error' and readyState becomes CLOSED
+        // - State: connected → reconnecting
+        // - Exponential backoff: 1s, 2s, 4s, 8s, max 30s
+        // - On successful reconnect: state → connected
+        // - Messages received during reconnect are not lost (server-side cursor)
+        it.todo('should fall back to HTTP polling after N failed SSE reconnects');
+        // Expected behavior:
+        // - After 3 failed SSE reconnect attempts
+        // - Permanently switches to HTTP polling mode for this session
+        // - State: reconnecting → connected (via HTTP)
+        // - Logs: "SSE reconnect failed 3 times, switching to HTTP polling"
+        it.todo('should preserve message cursor across reconnect');
+        // Expected behavior:
+        // - Tracks last received message ID or timestamp
+        // - Reconnect URL includes ?lastEventId=<cursor>
+        // - Server replays missed messages from cursor
+        // - No duplicate messages delivered to consumer
+        it.todo('should emit state change events during reconnect cycle');
+        // Expected behavior:
+        // - onStateChange fires: connected → reconnecting → connected
+        // - Or: connected → reconnecting → error (if max retries exceeded)
+    });
+    // ============================================================================
+    // Message receive (SSE mode)
+    // ============================================================================
+    describe('message receive via SSE', () => {
+        it.todo('should deliver incoming SSE messages via poll() return');
+        // Expected behavior:
+        // - SSE 'message' events are buffered internally
+        // - poll() returns buffered messages and clears buffer
+        // - Messages conform to ConduitMessage interface
+        it.todo('should parse SSE data field as JSON ConduitMessage');
+        // Expected behavior:
+        // - SSE data: {"id":"msg-1","from":"agent-a","content":"hello","timestamp":"..."}
+        // - Parsed into ConduitMessage with all fields populated
+        it.todo('should handle malformed SSE data gracefully');
+        // Expected behavior:
+        // - Invalid JSON in SSE data field does not crash transport
+        // - Malformed messages are logged and skipped
+        // - poll() returns only valid messages
+        it.todo('should filter self-sent messages');
+        // Expected behavior:
+        // - Messages where from === config.agentId are excluded from poll()
+        // - Prevents echo of own messages
+        it.todo('should support SSE event types for different message categories');
+        // Expected behavior:
+        // - 'message' event: standard agent messages
+        // - 'heartbeat' event: keep-alive (ignored in poll output)
+        // - 'system' event: system notifications (e.g., agent online/offline)
+    });
+    // ============================================================================
+    // Send with SSE down (fallback to HTTP)
+    // ============================================================================
+    describe('send (push)', () => {
+        it.todo('should send messages via HTTP POST regardless of SSE state');
+        // Expected behavior:
+        // - push() always uses HTTP POST (SSE is receive-only)
+        // - POST /conversations/{conversationId}/messages or /agents/{to}/messages
+        // - Returns { messageId } from response
+        // - Works whether SSE is connected, reconnecting, or fallen back to HTTP
+        it.todo('should send messages when SSE is connected');
+        // Expected behavior:
+        // - SSE connection is active for receiving
+        // - push() uses HTTP POST for sending (SSE is unidirectional)
+        // - Both channels work simultaneously
+        it.todo('should send messages when SSE is down and in HTTP fallback mode');
+        // Expected behavior:
+        // - SSE connection has failed, transport is in HTTP polling mode
+        // - push() still works via HTTP POST
+        // - No difference in send behavior between SSE and HTTP modes
+        it.todo('should retry failed sends with exponential backoff');
+        // Expected behavior:
+        // - On HTTP 5xx or network error, retry up to 3 times
+        // - Backoff: 500ms, 1s, 2s
+        // - On 4xx (client error), fail immediately (no retry)
+        // - Returns error after max retries
+        it.todo('should throw when not connected');
+        // Expected behavior:
+        // - push() before connect() throws "Transport not connected"
+        // - push() after disconnect() throws "Transport not connected"
+        it('throws when push is called before connect', async () => {
+            const transport = new SseTransport();
+            await expect(transport.push('to', 'msg')).rejects.toThrow('not connected');
+        });
+        it('throws when poll is called before connect', async () => {
+            const transport = new SseTransport();
+            await expect(transport.poll()).rejects.toThrow('not connected');
+        });
+        it('throws when ack is called before connect', async () => {
+            const transport = new SseTransport();
+            await expect(transport.ack(['id'])).rejects.toThrow('not connected');
+        });
+    });
+    // ============================================================================
+    // Poll (hybrid mode)
+    // ============================================================================
+    describe('poll', () => {
+        it.todo('should return SSE-buffered messages when SSE is active');
+        // Expected behavior:
+        // - In SSE mode, poll() drains the internal message buffer
+        // - Does NOT make an HTTP request (messages arrive via SSE push)
+        // - Returns empty array if no new messages since last poll
+        it.todo('should fall back to HTTP polling when SSE is down');
+        // Expected behavior:
+        // - In HTTP fallback mode, poll() makes GET /messages/peek
+        // - Behaves identically to HttpTransport.poll()
+        // - Respects limit and since options
+        it.todo('should respect since parameter for cursor-based retrieval');
+        // Expected behavior:
+        // - poll({ since: '2026-03-30T20:00:00Z' }) returns only newer messages
+        // - In SSE mode: filters buffer by timestamp
+        // - In HTTP mode: passes as query param
+    });
+    // ============================================================================
+    // Acknowledge
+    // ============================================================================
+    describe('ack', () => {
+        it.todo('should acknowledge messages via HTTP POST');
+        // Expected behavior:
+        // - ack(['msg-1', 'msg-2']) sends POST /messages/ack
+        // - Works in both SSE and HTTP modes (always HTTP for ack)
+        // - Acknowledged messages are not returned by subsequent poll()
+    });
+    // ============================================================================
+    // Heartbeat
+    // ============================================================================
+    describe('heartbeat', () => {
+        it.todo('should send heartbeat via HTTP POST');
+        // Expected behavior:
+        // - POST /agents/{agentId}/heartbeat
+        // - Works in both SSE and HTTP modes
+        // - Does not depend on SSE connection state
+        it.todo('should detect SSE connection health from heartbeat response');
+        // Expected behavior:
+        // - Heartbeat response may include SSE connection status
+        // - If server reports SSE session expired, trigger reconnect
+    });
+    // ============================================================================
+    // Edge cases
+    // ============================================================================
+    describe('edge cases', () => {
+        it.todo('should handle rapid connect/disconnect cycles');
+        // Expected behavior:
+        // - connect() → disconnect() → connect() in quick succession
+        // - No resource leaks (EventSource properly closed)
+        // - Final state is consistent
+        it.todo('should handle server-initiated SSE close');
+        // Expected behavior:
+        // - Server sends SSE close/shutdown event
+        // - Transport transitions to reconnecting or HTTP fallback
+        // - No unhandled errors
+        it.todo('should handle network going offline then online');
+        // Expected behavior:
+        // - SSE connection drops (network offline)
+        // - Reconnect attempts fail (network offline)
+        // - When network returns, reconnect succeeds
+        // - Messages buffered server-side are delivered
+        it.todo('should not leak EventSource instances on repeated reconnects');
+        // Expected behavior:
+        // - Each reconnect properly closes the previous EventSource
+        // - No accumulation of open connections
+        // - Memory usage stays constant
+    });
+});
+//# sourceMappingURL=sse-transport.test.js.map

package/src/conduit/__tests__/sse-transport.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sse-transport.test.js","sourceRoot":"","sources":["sse-transport.test.ts"],"names":[],"mappings":"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"}

package/src/conduit/__tests__/sse-transport.test.ts

@@ -0,0 +1,344 @@
+/**
+ * SseTransport test scenarios.
+ *
+ * Tests for the Server-Sent Events transport implementation.
+ * SseTransport extends HTTP polling with real-time push via SSE,
+ * falling back to HTTP polling when SSE is unavailable.
+ *
+ * @see packages/contracts/src/transport.ts — Transport interface
+ * @see packages/contracts/src/conduit.ts — ConduitState types
+ * @task T216
+ */
+
+import { describe, expect, it, vi } from 'vitest';
+
+import { SseTransport } from '../sse-transport.js';
+
+// ============================================================================
+// Test helpers
+// ============================================================================
+
+/** Mock SSE event source that simulates server-sent events. */
+function createMockEventSource() {
+  const handlers: Record<string, ((event: MessageEvent) => void)[]> = {};
+  return {
+    addEventListener: vi.fn((type: string, handler: (event: MessageEvent) => void) => {
+      handlers[type] = handlers[type] || [];
+      handlers[type].push(handler);
+    }),
+    removeEventListener: vi.fn(),
+    close: vi.fn(),
+    readyState: 0, // CONNECTING
+    /** Simulate receiving an SSE event. */
+    _emit(type: string, data: string) {
+      for (const h of handlers[type] || []) {
+        h(new MessageEvent(type, { data }));
+      }
+    },
+    /** Simulate connection open. */
+    _open() {
+      this.readyState = 1; // OPEN
+      for (const h of handlers['open'] || []) {
+        h(new MessageEvent('open', { data: '' }));
+      }
+    },
+    /** Simulate connection error. */
+    _error() {
+      this.readyState = 2; // CLOSED
+      for (const h of handlers['error'] || []) {
+        h(new MessageEvent('error', { data: '' }));
+      }
+    },
+  };
+}
+
+/** Standard test config for SseTransport. */
+const TEST_CONFIG = {
+  agentId: 'test-agent',
+  apiKey: 'sk_live_test123',
+  apiBaseUrl: 'https://api.signaldock.io',
+  sseEndpoint: 'https://api.signaldock.io/sse',
+};
+
+// ============================================================================
+// Connection lifecycle
+// ============================================================================
+
+describe('SseTransport', () => {
+  describe('connect', () => {
+    it.todo('should establish SSE connection to sseEndpoint');
+    // Expected behavior:
+    // - Creates EventSource to config.sseEndpoint with auth headers
+    // - Sets transport name to 'sse'
+    // - Transitions state: disconnected → connecting → connected
+    // - Resolves when EventSource 'open' event fires
+
+    it.todo('should fall back to HTTP polling when SSE endpoint is unreachable');
+    // Expected behavior:
+    // - Attempts SSE connection
+    // - On connection error, transitions to HTTP polling mode
+    // - State: disconnected → connecting → connected (via HTTP fallback)
+    // - Logs warning: "SSE unavailable, falling back to HTTP polling"
+    // - poll() still works via HTTP
+
+    it.todo('should include auth headers in SSE connection');
+    // Expected behavior:
+    // - EventSource URL includes ?token=<apiKey> (SSE doesn't support custom headers)
+    // - Or uses a pre-flight auth endpoint to get a session token
+    // - X-Agent-Id is conveyed via query param or pre-flight
+
+    it.todo('should reject connect when no sseEndpoint or apiBaseUrl is configured');
+    // Expected behavior:
+    // - Throws Error with message indicating missing config
+    // - State remains 'disconnected'
+
+    it('rejects connect when no sseEndpoint or apiBaseUrl provided', async () => {
+      const transport = new SseTransport();
+      await expect(
+        transport.connect({ agentId: 'test', apiKey: 'key', apiBaseUrl: '' }),
+      ).rejects.toThrow('requires');
+    });
+
+    it.todo('should reject connect when already connected');
+    // Expected behavior:
+    // - Second connect() call throws or is no-op
+    // - Does not create duplicate EventSource instances
+
+    it('has name "sse"', () => {
+      const transport = new SseTransport();
+      expect(transport.name).toBe('sse');
+    });
+  });
+
+  // ============================================================================
+  // Disconnect
+  // ============================================================================
+
+  describe('disconnect', () => {
+    it.todo('should close SSE connection and clear state');
+    // Expected behavior:
+    // - Calls EventSource.close()
+    // - Clears internal state
+    // - State: connected → disconnected
+    // - Subsequent push/poll calls throw "not connected"
+
+    it.todo('should be idempotent when already disconnected');
+    // Expected behavior:
+    // - No error when calling disconnect() on already disconnected transport
+    // - State remains 'disconnected'
+
+    it('is safe to call disconnect when not connected', async () => {
+      const transport = new SseTransport();
+      await transport.disconnect(); // Should not throw
+      await transport.disconnect(); // Still should not throw
+    });
+
+    it.todo('should cancel any pending poll timers');
+    // Expected behavior:
+    // - If HTTP fallback polling is active, clears interval
+    // - No orphaned timers after disconnect
+  });
+
+  // ============================================================================
+  // Reconnect
+  // ============================================================================
+
+  describe('reconnect', () => {
+    it.todo('should automatically reconnect on SSE connection drop');
+    // Expected behavior:
+    // - When EventSource fires 'error' and readyState becomes CLOSED
+    // - State: connected → reconnecting
+    // - Exponential backoff: 1s, 2s, 4s, 8s, max 30s
+    // - On successful reconnect: state → connected
+    // - Messages received during reconnect are not lost (server-side cursor)
+
+    it.todo('should fall back to HTTP polling after N failed SSE reconnects');
+    // Expected behavior:
+    // - After 3 failed SSE reconnect attempts
+    // - Permanently switches to HTTP polling mode for this session
+    // - State: reconnecting → connected (via HTTP)
+    // - Logs: "SSE reconnect failed 3 times, switching to HTTP polling"
+
+    it.todo('should preserve message cursor across reconnect');
+    // Expected behavior:
+    // - Tracks last received message ID or timestamp
+    // - Reconnect URL includes ?lastEventId=<cursor>
+    // - Server replays missed messages from cursor
+    // - No duplicate messages delivered to consumer
+
+    it.todo('should emit state change events during reconnect cycle');
+    // Expected behavior:
+    // - onStateChange fires: connected → reconnecting → connected
+    // - Or: connected → reconnecting → error (if max retries exceeded)
+  });
+
+  // ============================================================================
+  // Message receive (SSE mode)
+  // ============================================================================
+
+  describe('message receive via SSE', () => {
+    it.todo('should deliver incoming SSE messages via poll() return');
+    // Expected behavior:
+    // - SSE 'message' events are buffered internally
+    // - poll() returns buffered messages and clears buffer
+    // - Messages conform to ConduitMessage interface
+
+    it.todo('should parse SSE data field as JSON ConduitMessage');
+    // Expected behavior:
+    // - SSE data: {"id":"msg-1","from":"agent-a","content":"hello","timestamp":"..."}
+    // - Parsed into ConduitMessage with all fields populated
+
+    it.todo('should handle malformed SSE data gracefully');
+    // Expected behavior:
+    // - Invalid JSON in SSE data field does not crash transport
+    // - Malformed messages are logged and skipped
+    // - poll() returns only valid messages
+
+    it.todo('should filter self-sent messages');
+    // Expected behavior:
+    // - Messages where from === config.agentId are excluded from poll()
+    // - Prevents echo of own messages
+
+    it.todo('should support SSE event types for different message categories');
+    // Expected behavior:
+    // - 'message' event: standard agent messages
+    // - 'heartbeat' event: keep-alive (ignored in poll output)
+    // - 'system' event: system notifications (e.g., agent online/offline)
+  });
+
+  // ============================================================================
+  // Send with SSE down (fallback to HTTP)
+  // ============================================================================
+
+  describe('send (push)', () => {
+    it.todo('should send messages via HTTP POST regardless of SSE state');
+    // Expected behavior:
+    // - push() always uses HTTP POST (SSE is receive-only)
+    // - POST /conversations/{conversationId}/messages or /agents/{to}/messages
+    // - Returns { messageId } from response
+    // - Works whether SSE is connected, reconnecting, or fallen back to HTTP
+
+    it.todo('should send messages when SSE is connected');
+    // Expected behavior:
+    // - SSE connection is active for receiving
+    // - push() uses HTTP POST for sending (SSE is unidirectional)
+    // - Both channels work simultaneously
+
+    it.todo('should send messages when SSE is down and in HTTP fallback mode');
+    // Expected behavior:
+    // - SSE connection has failed, transport is in HTTP polling mode
+    // - push() still works via HTTP POST
+    // - No difference in send behavior between SSE and HTTP modes
+
+    it.todo('should retry failed sends with exponential backoff');
+    // Expected behavior:
+    // - On HTTP 5xx or network error, retry up to 3 times
+    // - Backoff: 500ms, 1s, 2s
+    // - On 4xx (client error), fail immediately (no retry)
+    // - Returns error after max retries
+
+    it.todo('should throw when not connected');
+    // Expected behavior:
+    // - push() before connect() throws "Transport not connected"
+    // - push() after disconnect() throws "Transport not connected"
+
+    it('throws when push is called before connect', async () => {
+      const transport = new SseTransport();
+      await expect(transport.push('to', 'msg')).rejects.toThrow('not connected');
+    });
+
+    it('throws when poll is called before connect', async () => {
+      const transport = new SseTransport();
+      await expect(transport.poll()).rejects.toThrow('not connected');
+    });
+
+    it('throws when ack is called before connect', async () => {
+      const transport = new SseTransport();
+      await expect(transport.ack(['id'])).rejects.toThrow('not connected');
+    });
+  });
+
+  // ============================================================================
+  // Poll (hybrid mode)
+  // ============================================================================
+
+  describe('poll', () => {
+    it.todo('should return SSE-buffered messages when SSE is active');
+    // Expected behavior:
+    // - In SSE mode, poll() drains the internal message buffer
+    // - Does NOT make an HTTP request (messages arrive via SSE push)
+    // - Returns empty array if no new messages since last poll
+
+    it.todo('should fall back to HTTP polling when SSE is down');
+    // Expected behavior:
+    // - In HTTP fallback mode, poll() makes GET /messages/peek
+    // - Behaves identically to HttpTransport.poll()
+    // - Respects limit and since options
+
+    it.todo('should respect since parameter for cursor-based retrieval');
+    // Expected behavior:
+    // - poll({ since: '2026-03-30T20:00:00Z' }) returns only newer messages
+    // - In SSE mode: filters buffer by timestamp
+    // - In HTTP mode: passes as query param
+  });
+
+  // ============================================================================
+  // Acknowledge
+  // ============================================================================
+
+  describe('ack', () => {
+    it.todo('should acknowledge messages via HTTP POST');
+    // Expected behavior:
+    // - ack(['msg-1', 'msg-2']) sends POST /messages/ack
+    // - Works in both SSE and HTTP modes (always HTTP for ack)
+    // - Acknowledged messages are not returned by subsequent poll()
+  });
+
+  // ============================================================================
+  // Heartbeat
+  // ============================================================================
+
+  describe('heartbeat', () => {
+    it.todo('should send heartbeat via HTTP POST');
+    // Expected behavior:
+    // - POST /agents/{agentId}/heartbeat
+    // - Works in both SSE and HTTP modes
+    // - Does not depend on SSE connection state
+
+    it.todo('should detect SSE connection health from heartbeat response');
+    // Expected behavior:
+    // - Heartbeat response may include SSE connection status
+    // - If server reports SSE session expired, trigger reconnect
+  });
+
+  // ============================================================================
+  // Edge cases
+  // ============================================================================
+
+  describe('edge cases', () => {
+    it.todo('should handle rapid connect/disconnect cycles');
+    // Expected behavior:
+    // - connect() → disconnect() → connect() in quick succession
+    // - No resource leaks (EventSource properly closed)
+    // - Final state is consistent
+
+    it.todo('should handle server-initiated SSE close');
+    // Expected behavior:
+    // - Server sends SSE close/shutdown event
+    // - Transport transitions to reconnecting or HTTP fallback
+    // - No unhandled errors
+
+    it.todo('should handle network going offline then online');
+    // Expected behavior:
+    // - SSE connection drops (network offline)
+    // - Reconnect attempts fail (network offline)
+    // - When network returns, reconnect succeeds
+    // - Messages buffered server-side are delivered
+
+    it.todo('should not leak EventSource instances on repeated reconnects');
+    // Expected behavior:
+    // - Each reconnect properly closes the previous EventSource
+    // - No accumulation of open connections
+    // - Memory usage stays constant
+  });
+});