@meowpanel/api 0.13.0 → 0.14.0

package/script/src/sse.d.ts

@@ -1,5 +1,33 @@
-/** State of an {@link SseConnection}. */
-export type SseState = 'disconnected' | 'connecting' | 'connected' | 'error';
+import { TypedEmitter } from './emitter.js';
+/**
+ * State of an {@link SseConnection}.
+ *
+ * `reconnecting` covers both the backoff wait and the retry request. `error` is terminal: the
+ * stream was refused with a status a retry cannot fix, or reconnecting is turned off.
+ */
+export type SseState = 'disconnected' | 'connecting' | 'connected' | 'reconnecting' | 'error';
+/** Events emitted by {@link SseConnection}. */
+export interface SseConnectionEvents {
+    /** The connection state changed. */
+    state: SseState;
+}
+/** Options for {@link SseConnection}. */
+export interface SseOptions {
+    /** Reconnect after the stream drops or a connection attempt fails. Defaults to `true`. */
+    reconnect?: boolean;
+    /** Delay before the first reconnect attempt. Doubles per failed attempt. Defaults to 1 second. */
+    minReconnectDelayMs?: number;
+    /** Upper bound for the reconnect delay. Defaults to 30 seconds. */
+    maxReconnectDelayMs?: number;
+    /**
+     * Treat the stream as dead after this long without receiving any bytes, and reconnect.
+     *
+     * A connection that dies without closing (lost network, dropped NAT entry) otherwise stays
+     * `connected` forever. Only set this against a server that sends periodic keepalives,
+     * comfortably above their interval. `0` disables it, which is the default.
+     */
+    idleTimeoutMs?: number;
+}
 /**
  * A generic, `fetch`-based Server-Sent Events client.
  *
@@ -7,9 +35,13 @@ export type SseState = 'disconnected' | 'connecting' | 'connected' | 'error';
  * header, making it compatible with bearer token auth in all environments
  * (browser, Deno, Node.js).
  *
+ * Like `EventSource`, it reconnects with exponential backoff whenever the stream ends without
+ * {@link disconnect} being called, including a clean close by the server.
+ *
  * @example
  * ```ts ignore
  * const sse = new SseConnection('https://panel.example.com/v1/sse', token);
+ * sse.on('state', (state) => console.log('SSE is', state));
  * sse.connect(
  *   (event, data) => console.log(event, data),
  *   (err) => console.error('SSE error:', err),
@@ -18,16 +50,22 @@ export type SseState = 'disconnected' | 'connecting' | 'connected' | 'error';
  * sse.disconnect();
  * ```
  */
-export declare class SseConnection {
+export declare class SseConnection extends TypedEmitter<SseConnectionEvents> {
     private readonly url;
     private token;
     private abortController?;
+    private reconnectTimer?;
     private _state;
+    private attempt;
+    private readonly options;
     /**
-     * @param url   The full URL to connect to.
-     * @param token Bearer token used in the `Authorization` header.
+     * @param url     The full URL to connect to.
+     * @param token   Bearer token used in the `Authorization` header, or a function returning the
+     *                current one. A function is read on every attempt, so reconnects pick up a
+     *                refreshed token.
+     * @param options Reconnect and idle-timeout behavior.
      */
-    constructor(url: string, token: string);
+    constructor(url: string, token: string | (() => string), options?: SseOptions);
     /** Update the bearer token for subsequent reconnections. */
     updateToken(token: string): void;
     /** Current connection state. */
@@ -37,16 +75,30 @@ export declare class SseConnection {
     /**
      * Open the SSE connection and begin streaming events.
      *
-     * This method is **non-blocking**: it starts the connection and returns immediately
-     * after the HTTP response headers are received. Events are delivered asynchronously
-     * via the `onEvent` callback.
+     * This method is **non-blocking**: it starts the connection and returns immediately.
+     * Events are delivered asynchronously via the `onEvent` callback, and state changes via the
+     * `state` event.
      *
      * @param onEvent Callback invoked for each received SSE event, with the event name and raw data string.
-     * @param onError Optional callback invoked if the connection fails or is lost (not called on intentional disconnect).
+     * @param onError Optional callback invoked each time a connection attempt fails or an open stream
+     *                is lost (not called on intentional disconnect). Reconnecting continues unless
+     *                {@link state} is `error`.
      */
     connect(onEvent: (event: string, data: string) => void, onError?: (error: Error) => void): void;
-    /** Close the SSE connection and stop receiving events. */
+    /** Close the SSE connection, cancel any pending reconnect, and stop receiving events. */
     disconnect(): void;
+    private open;
+    /**
+     * Exponential backoff with jitter, so clients that lost the same server do not all retry at
+     * the same instant when it comes back.
+     */
+    private nextReconnectDelay;
+    /**
+     * 401 is retryable because the token is re-read on every attempt and may have been refreshed
+     * in the meantime. Other client errors (403, 404, ...) will not change on their own.
+     */
+    private static isRetryableStatus;
+    private setState;
     /** Parse the raw `ReadableStream` body into SSE frames, calling `onEvent` for each complete frame. */
     private readStream;
 }

package/script/src/sse.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"sse.d.ts","sourceRoot":"","sources":["../../src/src/sse.ts"],"names":[],"mappings":"AAAA,yCAAyC;AACzC,MAAM,MAAM,QAAQ,GAAG,cAAc,GAAG,YAAY,GAAG,WAAW,GAAG,OAAO,CAAC;AAE7E;;;;;;;;;;;;;;;;;GAiBG;AACH,qBAAa,aAAa;IASxB,OAAO,CAAC,QAAQ,CAAC,GAAG;IACpB,OAAO,CAAC,KAAK;IATd,OAAO,CAAC,eAAe,CAAC,CAAkB;IAC1C,OAAO,CAAC,MAAM,CAA4B;IAE1C;;;OAGG;gBAEe,GAAG,EAAE,MAAM,EACpB,KAAK,EAAE,MAAM;IAGtB,4DAA4D;IACrD,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI;IAIvC,gCAAgC;IAChC,IAAW,KAAK,IAAI,QAAQ,CAE3B;IAED,mDAAmD;IACnD,IAAW,WAAW,IAAI,OAAO,CAEhC;IAED;;;;;;;;;OASG;IACI,OAAO,CACb,OAAO,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,KAAK,IAAI,EAC9C,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,GAC9B,IAAI;IAyCP,0DAA0D;IACnD,UAAU,IAAI,IAAI;IAMzB,sGAAsG;YACxF,UAAU;CAmCxB"}
+{"version":3,"file":"sse.d.ts","sourceRoot":"","sources":["../../src/src/sse.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAE5C;;;;;GAKG;AACH,MAAM,MAAM,QAAQ,GAAG,cAAc,GAAG,YAAY,GAAG,WAAW,GAAG,cAAc,GAAG,OAAO,CAAC;AAE9F,+CAA+C;AAC/C,MAAM,WAAW,mBAAmB;IACnC,oCAAoC;IACpC,KAAK,EAAE,QAAQ,CAAC;CAChB;AAED,yCAAyC;AACzC,MAAM,WAAW,UAAU;IAC1B,0FAA0F;IAC1F,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,kGAAkG;IAClG,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B,mEAAmE;IACnE,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B;;;;;;OAMG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;CACvB;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,qBAAa,aAAc,SAAQ,YAAY,CAAC,mBAAmB,CAAC;IAelE,OAAO,CAAC,QAAQ,CAAC,GAAG;IACpB,OAAO,CAAC,KAAK;IAfd,OAAO,CAAC,eAAe,CAAC,CAAkB;IAC1C,OAAO,CAAC,cAAc,CAAC,CAAgC;IACvD,OAAO,CAAC,MAAM,CAA4B;IAC1C,OAAO,CAAC,OAAO,CAAK;IACpB,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAuB;IAE/C;;;;;;OAMG;gBAEe,GAAG,EAAE,MAAM,EACpB,KAAK,EAAE,MAAM,GAAG,CAAC,MAAM,MAAM,CAAC,EACtC,OAAO,GAAE,UAAe;IAYzB,4DAA4D;IACrD,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI;IAIvC,gCAAgC;IAChC,IAAW,KAAK,IAAI,QAAQ,CAE3B;IAED,mDAAmD;IACnD,IAAW,WAAW,IAAI,OAAO,CAEhC;IAED;;;;;;;;;;;OAWG;IACI,OAAO,CACb,OAAO,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,KAAK,IAAI,EAC9C,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,GAC9B,IAAI;IAMP,yFAAyF;IAClF,UAAU,IAAI,IAAI;IAQzB,OAAO,CAAC,IAAI;IA2EZ;;;OAGG;IACH,OAAO,CAAC,kBAAkB;IAO1B;;;OAGG;IACH,OAAO,CAAC,MAAM,CAAC,iBAAiB;IAIhC,OAAO,CAAC,QAAQ;IAMhB,sGAAsG;YACxF,UAAU;CAqCxB"}

package/script/src/sse.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.SseConnection = void 0;
+const emitter_js_1 = require("./emitter.js");
 /**
  * A generic, `fetch`-based Server-Sent Events client.
  *
@@ -8,9 +9,13 @@ exports.SseConnection = void 0;
  * header, making it compatible with bearer token auth in all environments
  * (browser, Deno, Node.js).
  *
+ * Like `EventSource`, it reconnects with exponential backoff whenever the stream ends without
+ * {@link disconnect} being called, including a clean close by the server.
+ *
  * @example
  * ```ts ignore
  * const sse = new SseConnection('https://panel.example.com/v1/sse', token);
+ * sse.on('state', (state) => console.log('SSE is', state));
  * sse.connect(
  *   (event, data) => console.log(event, data),
  *   (err) => console.error('SSE error:', err),
@@ -19,18 +24,32 @@ exports.SseConnection = void 0;
  * sse.disconnect();
  * ```
  */
-class SseConnection {
+class SseConnection extends emitter_js_1.TypedEmitter {
     url;
     token;
     abortController;
+    reconnectTimer;
     _state = 'disconnected';
+    attempt = 0;
+    options;
     /**
-     * @param url   The full URL to connect to.
-     * @param token Bearer token used in the `Authorization` header.
+     * @param url     The full URL to connect to.
+     * @param token   Bearer token used in the `Authorization` header, or a function returning the
+     *                current one. A function is read on every attempt, so reconnects pick up a
+     *                refreshed token.
+     * @param options Reconnect and idle-timeout behavior.
      */
-    constructor(url, token) {
+    constructor(url, token, options = {}) {
+        super();
         this.url = url;
         this.token = token;
+        this.options = {
+            reconnect: true,
+            minReconnectDelayMs: 1_000,
+            maxReconnectDelayMs: 30_000,
+            idleTimeoutMs: 0,
+            ...options,
+        };
     }
     /** Update the bearer token for subsequent reconnections. */
     updateToken(token) {
@@ -47,60 +66,121 @@ class SseConnection {
     /**
      * Open the SSE connection and begin streaming events.
      *
-     * This method is **non-blocking**: it starts the connection and returns immediately
-     * after the HTTP response headers are received. Events are delivered asynchronously
-     * via the `onEvent` callback.
+     * This method is **non-blocking**: it starts the connection and returns immediately.
+     * Events are delivered asynchronously via the `onEvent` callback, and state changes via the
+     * `state` event.
      *
      * @param onEvent Callback invoked for each received SSE event, with the event name and raw data string.
-     * @param onError Optional callback invoked if the connection fails or is lost (not called on intentional disconnect).
+     * @param onError Optional callback invoked each time a connection attempt fails or an open stream
+     *                is lost (not called on intentional disconnect). Reconnecting continues unless
+     *                {@link state} is `error`.
      */
     connect(onEvent, onError) {
         this.disconnect();
-        this._state = 'connecting';
+        this.attempt = 0;
+        this.open(onEvent, onError);
+    }
+    /** Close the SSE connection, cancel any pending reconnect, and stop receiving events. */
+    disconnect() {
+        clearTimeout(this.reconnectTimer);
+        this.reconnectTimer = undefined;
+        this.abortController?.abort();
+        this.abortController = undefined;
+        this.setState('disconnected');
+    }
+    open(onEvent, onError) {
+        this.setState(this.attempt === 0 ? 'connecting' : 'reconnecting');
         const controller = new AbortController();
         this.abortController = controller;
         (async () => {
+            const { idleTimeoutMs } = this.options;
+            let idleTimer;
+            let idledOut = false;
+            const resetIdleTimer = () => {
+                if (!idleTimeoutMs)
+                    return;
+                clearTimeout(idleTimer);
+                idleTimer = setTimeout(() => {
+                    idledOut = true;
+                    controller.abort();
+                }, idleTimeoutMs);
+            };
+            let retry = true;
+            let error;
             try {
+                resetIdleTimer();
+                const token = typeof this.token === 'function' ? this.token() : this.token;
                 const response = await globalThis.fetch(this.url, {
                     headers: {
-                        'Authorization': `Bearer ${this.token}`,
+                        'Authorization': `Bearer ${token}`,
                         'Accept': 'text/event-stream',
                         'Cache-Control': 'no-cache',
                     },
                     signal: controller.signal,
                 });
-                // Guard against a concurrent connect() that replaced our controller.
-                if (this.abortController !== controller)
-                    return;
                 if (!response.ok || !response.body) {
+                    await response.body?.cancel();
+                    retry = response.ok || SseConnection.isRetryableStatus(response.status);
                     throw new Error(`SSE connection failed: HTTP ${response.status}`);
                 }
-                this._state = 'connected';
-                await this.readStream(response.body, onEvent);
+                this.attempt = 0;
+                this.setState('connected');
+                await this.readStream(response.body, onEvent, resetIdleTimer);
+                error = new Error('SSE stream closed by the server');
             }
             catch (err) {
-                if (err.name !== 'AbortError') {
-                    // Only update state if this is still the active connection.
-                    if (this.abortController !== controller)
-                        return;
-                    this._state = 'error';
-                    onError?.(err instanceof Error ? err : new Error(String(err)));
-                    return;
-                }
+                error = idledOut
+                    ? new Error(`SSE stream received nothing for ${idleTimeoutMs}ms`)
+                    : err instanceof Error
+                        ? err
+                        : new Error(String(err));
             }
-            if (this.abortController === controller) {
-                this._state = 'disconnected';
+            finally {
+                clearTimeout(idleTimer);
             }
+            // disconnect() or a newer connect() replaced this attempt, so it ends silently.
+            if (this.abortController !== controller)
+                return;
+            onError?.(error);
+            if (this.abortController !== controller)
+                return;
+            if (!retry || !this.options.reconnect) {
+                this.abortController = undefined;
+                this.setState('error');
+                return;
+            }
+            this.setState('reconnecting');
+            this.reconnectTimer = setTimeout(() => {
+                this.reconnectTimer = undefined;
+                this.open(onEvent, onError);
+            }, this.nextReconnectDelay());
         })();
     }
-    /** Close the SSE connection and stop receiving events. */
-    disconnect() {
-        this.abortController?.abort();
-        this.abortController = undefined;
-        this._state = 'disconnected';
+    /**
+     * Exponential backoff with jitter, so clients that lost the same server do not all retry at
+     * the same instant when it comes back.
+     */
+    nextReconnectDelay() {
+        const { minReconnectDelayMs, maxReconnectDelayMs } = this.options;
+        const base = Math.min(maxReconnectDelayMs, minReconnectDelayMs * 2 ** this.attempt);
+        this.attempt++;
+        return base / 2 + Math.random() * (base / 2);
+    }
+    /**
+     * 401 is retryable because the token is re-read on every attempt and may have been refreshed
+     * in the meantime. Other client errors (403, 404, ...) will not change on their own.
+     */
+    static isRetryableStatus(status) {
+        return status >= 500 || status === 401 || status === 408 || status === 429;
+    }
+    setState(state) {
+        if (this._state === state)
+            return;
+        this._state = state;
+        this.emit('state', state);
     }
     /** Parse the raw `ReadableStream` body into SSE frames, calling `onEvent` for each complete frame. */
-    async readStream(body, onEvent) {
+    async readStream(body, onEvent, onChunk) {
         const reader = body.getReader();
         const decoder = new TextDecoder();
         let buffer = '';
@@ -111,6 +191,7 @@ class SseConnection {
                 const { done, value } = await reader.read();
                 if (done)
                     break;
+                onChunk();
                 buffer += decoder.decode(value, { stream: true });
                 const lines = buffer.split('\n');
                 buffer = lines.pop() ?? '';