@inferencesh/sdk 0.22.1 → 0.24.0

package/dist/http/streamable.d.ts

@@ -46,6 +46,28 @@ export interface StreamableMessage<T = unknown> {
  * `source` is the URL to fetch, or a StreamRequest that sends the request.
  */
 export declare function streamable<T = unknown>(source: string | StreamRequest, options?: StreamableOptions): AsyncGenerator<T>;
+/**
+ * Raw streamable that yields the full message including wrapper.
+ * Use this when you need access to event type or fields.
+ */
+export declare function streamableRaw<T = unknown>(source: string | StreamRequest, options?: StreamableOptions): AsyncGenerator<StreamableMessage<T> | T>;
+/** How a StreamableManager reconnects after its stream fails. */
+export interface StreamReconnectOptions {
+    /**
+     * Failed connection attempts in a row before the manager gives up and calls
+     * `onError` (default 10). Any line received, heartbeats included, resets the count.
+     */
+    maxAttempts?: number;
+    /** Delay before the first retry in ms (default 1000). It doubles per attempt, with jitter. */
+    baseDelayMs?: number;
+    /** Longest delay between retries in ms (default 30000). */
+    maxDelayMs?: number;
+    /**
+     * Reconnect when nothing, not even a heartbeat, arrives for this many ms
+     * (default 30000; the API sends a heartbeat every 10s). 0 turns it off.
+     */
+    idleTimeoutMs?: number;
+}
 /**
  * StreamableManager provides a callback-based API similar to StreamManager
  * but uses fetch + ReadableStream instead of EventSource.
@@ -69,19 +91,46 @@ export type StreamableManagerOptions<T> = StreamableSource & {
     onData?: (data: T) => void;
     /** Called for partial updates with fields list */
     onPartialData?: (data: T, fields: string[]) => void;
-    /** Called on error */
+    /**
+     * Called when the stream fails. With `reconnect`, only once the manager
+     * gives up: a refusal no retry would change (4xx other than 408/429), or
+     * `maxAttempts` failures in a row.
+     */
     onError?: (error: Error) => void;
     /** Called when stream starts */
     onStart?: () => void;
-    /** Called when stream ends */
+    /**
+     * Called once when the manager is done: the stream ended cleanly, stop()
+     * was called, or it failed and will not retry.
+     */
     onEnd?: () => void;
     /** Called for delta events (streaming token deltas) */
     onDelta?: (delta: Record<string, any>, seq: number) => void;
+    /**
+     * Reconnect after the stream fails or goes silent (default false: a failure
+     * ends the stream). `true` uses the StreamReconnectOptions defaults. A clean
+     * end of the stream is not retried.
+     */
+    reconnect?: boolean | StreamReconnectOptions;
+    /** With `reconnect`: the stream failed and the manager retries after `delayMs`. */
+    onRetry?: (error: Error, attempt: number, delayMs: number) => void;
+    /**
+     * With `reconnect`: a retry got a new connection. Events sent while the
+     * stream was down are lost, so this is where the caller fetches the current
+     * state. The manager reads the new stream only after the returned promise
+     * settles, so what it reads is newer than what the caller fetched; a
+     * rejection counts as a failed attempt.
+     */
+    onReconnect?: (attempt: number) => void | Promise<void>;
 };
 export declare class StreamableManager<T> {
     private options;
     private abortController;
     private isRunning;
+    /** Bumped by start() and stop(), so a stopped run never acts again. */
+    private runId;
+    /** Ends a pending retry wait early (stop, online, tab visible). */
+    private wakeRetry;
     private eventListeners;
     constructor(options: StreamableManagerOptions<T>);
     /**
@@ -90,10 +139,17 @@ export declare class StreamableManager<T> {
      */
     addEventListener<E = unknown>(eventName: string, callback: (data: E, fields?: string[]) => void): () => void;
     start(): Promise<void>;
+    /**
+     * One connection: open the stream and dispatch its messages until it ends.
+     * Resolves on a clean end, throws when the request or the read fails.
+     */
+    private connect;
+    /** Route one message to onDelta, a typed event listener, onPartialData or onData. */
+    private dispatch;
+    /**
+     * Wait `delayMs` before the next attempt. In a browser, coming back online
+     * or the tab becoming visible retries at once; stop() ends the wait.
+     */
+    private waitToRetry;
     stop(): void;
 }
-/**
- * Raw streamable that yields the full message including wrapper.
- * Use this when you need access to event type or fields.
- */
-export declare function streamableRaw<T = unknown>(source: string | StreamRequest, options?: StreamableOptions): AsyncGenerator<StreamableMessage<T> | T>;

package/dist/http/streamable.js

@@ -28,19 +28,46 @@ async function openStream(source, { headers = {}, body, method = body ? 'POST' :
     }
     return res.body;
 }
+/** The error a stream read sees when its signal aborts. */
+function abortError() {
+    const error = new Error('The operation was aborted');
+    error.name = 'AbortError';
+    return error;
+}
 /**
- * Stream NDJSON from an HTTP endpoint using fetch + ReadableStream.
- * Yields parsed JSON objects, automatically filtering heartbeats.
- * `source` is the URL to fetch, or a StreamRequest that sends the request.
+ * Resolves with `promise`, or rejects with an AbortError once `signal`
+ * aborts. A request or body that ignores the signal cannot hold the caller.
  */
-export async function* streamable(source, options = {}) {
-    const { skipHeartbeats = true } = options;
-    const reader = (await openStream(source, options)).getReader();
+function untilAborted(promise, signal) {
+    if (!signal)
+        return promise;
+    if (signal.aborted)
+        return Promise.reject(abortError());
+    return new Promise((resolve, reject) => {
+        const onAbort = () => reject(abortError());
+        signal.addEventListener('abort', onAbort, { once: true });
+        promise.then(resolve, reject).finally(() => signal.removeEventListener('abort', onAbort));
+    });
+}
+/** Run a cleanup that may throw or reject; its failure changes nothing. */
+function quietly(cleanup) {
+    try {
+        cleanup()?.catch(() => { });
+    }
+    catch {
+        // Already closed.
+    }
+}
+/** Every parsed NDJSON line of `body`, heartbeats included. Aborting `signal` ends the read with an AbortError. */
+async function* readLines(body, signal) {
+    const reader = body.getReader();
     const decoder = new TextDecoder();
     let buffer = '';
+    const cancel = () => quietly(() => reader.cancel?.());
+    signal?.addEventListener('abort', cancel, { once: true });
     try {
         while (true) {
-            const { done, value } = await reader.read();
+            const { done, value } = await untilAborted(reader.read(), signal);
             if (done)
                 break;
             buffer += decoder.decode(value, { stream: true });
@@ -49,42 +76,91 @@ export async function* streamable(source, options = {}) {
             for (const line of lines) {
                 if (!line.trim())
                     continue;
-                const parsed = JSON.parse(line);
-                // Skip heartbeats
-                if (skipHeartbeats && parsed.type === 'heartbeat') {
-                    continue;
-                }
-                // If it's a wrapped message with event/data/fields, yield the data
-                // Otherwise yield the entire parsed object
-                if ('data' in parsed && parsed.data !== undefined) {
-                    yield parsed.data;
-                }
-                else {
-                    yield parsed;
-                }
+                yield JSON.parse(line);
             }
         }
         // Handle remaining buffer
         if (buffer.trim()) {
-            const parsed = JSON.parse(buffer);
-            if (!(skipHeartbeats && parsed.type === 'heartbeat')) {
-                if ('data' in parsed && parsed.data !== undefined) {
-                    yield parsed.data;
-                }
-                else {
-                    yield parsed;
-                }
-            }
+            yield JSON.parse(buffer);
         }
     }
     finally {
-        reader.releaseLock();
+        signal?.removeEventListener('abort', cancel);
+        try {
+            reader.releaseLock();
+        }
+        catch {
+            // A read still pending after an abort can make releaseLock throw.
+        }
+    }
+}
+const isHeartbeat = (parsed) => typeof parsed === 'object' && parsed !== null && parsed.type === 'heartbeat';
+/**
+ * Stream NDJSON from an HTTP endpoint using fetch + ReadableStream.
+ * Yields parsed JSON objects, automatically filtering heartbeats.
+ * `source` is the URL to fetch, or a StreamRequest that sends the request.
+ */
+export async function* streamable(source, options = {}) {
+    for await (const parsed of streamableRaw(source, options)) {
+        const message = parsed;
+        // If it's a wrapped message with event/data/fields, yield the data
+        // Otherwise yield the entire parsed object
+        if (typeof message === 'object' && message !== null && 'data' in message && message.data !== undefined) {
+            yield message.data;
+        }
+        else {
+            yield parsed;
+        }
     }
 }
+/**
+ * Raw streamable that yields the full message including wrapper.
+ * Use this when you need access to event type or fields.
+ */
+export async function* streamableRaw(source, options = {}) {
+    const { skipHeartbeats = true } = options;
+    for await (const parsed of readLines(await openStream(source, options), options.signal)) {
+        if (skipHeartbeats && isHeartbeat(parsed))
+            continue;
+        yield parsed;
+    }
+}
+const RECONNECT_DEFAULTS = {
+    maxAttempts: 10,
+    baseDelayMs: 1000,
+    maxDelayMs: 30000,
+    idleTimeoutMs: 30000,
+};
+/** The HTTP status an error carries, if any. */
+function errorStatus(error) {
+    const { statusCode, status } = error;
+    if (typeof statusCode === 'number')
+        return statusCode;
+    if (typeof status === 'number')
+        return status;
+    const match = /^HTTP (\d{3})\b/.exec(error.message);
+    return match ? Number(match[1]) : undefined;
+}
+/** A refusal that a retry would get again: any 4xx except 408 (timeout) and 429 (rate limit). */
+function isRetryable(error) {
+    const status = errorStatus(error);
+    if (status === undefined)
+        return true;
+    return !(status >= 400 && status < 500 && status !== 408 && status !== 429);
+}
+/** Exponential backoff for retry `attempt` (1-based), jittered to [50%, 100%] of the step. */
+function backoffDelay(policy, attempt) {
+    const step = Math.min(policy.maxDelayMs, policy.baseDelayMs * 2 ** (attempt - 1));
+    return Math.round(step / 2 + Math.random() * (step / 2));
+}
 export class StreamableManager {
     constructor(options) {
         this.abortController = null;
         this.isRunning = false;
+        /** Bumped by start() and stop(), so a stopped run never acts again. */
+        this.runId = 0;
+        /** Ends a pending retry wait early (stop, online, tab visible). */
+        this.wakeRetry = null;
         this.eventListeners = new Map();
         this.options = options;
     }
@@ -111,116 +187,198 @@ export class StreamableManager {
         if (this.isRunning)
             return;
         this.isRunning = true;
-        this.abortController = new AbortController();
+        const run = ++this.runId;
+        const active = () => this.runId === run;
+        const { reconnect } = this.options;
+        const policy = reconnect
+            ? { ...RECONNECT_DEFAULTS, ...(reconnect === true ? {} : reconnect) }
+            : null;
+        // Failed attempts in a row; any line received resets it.
+        let failures = 0;
+        let attempts = 0;
         try {
             this.options.onStart?.();
-            const { options } = this;
-            const stream = 'request' in options
-                ? streamableRaw(options.request, { body: options.body, signal: this.abortController.signal })
-                : streamableRaw(options.url, {
-                    headers: options.headers,
-                    body: options.body,
-                    signal: this.abortController.signal,
-                    credentials: options.credentials,
-                });
-            for await (const message of stream) {
-                if (!this.isRunning)
-                    break;
-                const wrapper = message;
-                // Handle delta events
-                if (wrapper.event === 'delta' && this.options.onDelta) {
-                    const payload = wrapper.data;
-                    if (payload && payload.delta) {
-                        this.options.onDelta(payload.delta, payload.seq);
-                    }
-                    continue;
+            while (active()) {
+                const retry = attempts++ > 0 ? failures : 0;
+                const idle = { timedOut: false };
+                let error = null;
+                try {
+                    await this.connect(active, policy?.idleTimeoutMs ?? 0, idle, retry, () => {
+                        failures = 0;
+                    });
                 }
-                // Handle typed events ({"event": "...", "data": ...})
-                if (wrapper.event && this.eventListeners.has(wrapper.event)) {
-                    const listeners = this.eventListeners.get(wrapper.event);
-                    const eventData = wrapper.data !== undefined ? wrapper.data : message;
-                    const fields = wrapper.fields;
-                    listeners.forEach(callback => callback(eventData, fields));
-                    continue;
+                catch (err) {
+                    error = err instanceof Error ? err : new Error(String(err));
                 }
-                // Check if it's a partial update
-                if (typeof message === 'object' &&
-                    message !== null &&
-                    'data' in message &&
-                    'fields' in message &&
-                    Array.isArray(wrapper.fields)) {
-                    if (this.options.onPartialData && wrapper.data !== undefined) {
-                        this.options.onPartialData(wrapper.data, wrapper.fields);
-                    }
-                    else if (wrapper.data !== undefined) {
-                        this.options.onData?.(wrapper.data);
-                    }
+                if (!active())
+                    break;
+                if (idle.timedOut) {
+                    error = new Error(`Stream received nothing for ${policy.idleTimeoutMs}ms`);
                 }
-                else if (wrapper.data !== undefined) {
-                    // Has data wrapper but no fields - unwrap
-                    this.options.onData?.(wrapper.data);
+                if (!error)
+                    break; // ended cleanly
+                if (!policy) {
+                    if (error.name !== 'AbortError')
+                        this.options.onError?.(error);
+                    break;
                 }
-                else {
-                    this.options.onData?.(message);
+                if (!isRetryable(error) || failures >= policy.maxAttempts) {
+                    this.options.onError?.(error);
+                    break;
                 }
+                failures++;
+                const delay = backoffDelay(policy, failures);
+                this.options.onRetry?.(error, failures, delay);
+                await this.waitToRetry(delay);
             }
         }
         catch (err) {
-            if (err instanceof Error && err.name === 'AbortError') {
-                // Intentional stop, not an error
-            }
-            else {
+            // A callback threw outside a connection.
+            if (active())
                 this.options.onError?.(err instanceof Error ? err : new Error(String(err)));
-            }
         }
         finally {
-            this.isRunning = false;
+            if (active()) {
+                this.isRunning = false;
+                this.abortController = null;
+            }
             this.options.onEnd?.();
         }
     }
-    stop() {
-        this.isRunning = false;
-        this.abortController?.abort();
-        this.abortController = null;
-    }
-}
-/**
- * Raw streamable that yields the full message including wrapper.
- * Use this when you need access to event type or fields.
- */
-export async function* streamableRaw(source, options = {}) {
-    const { skipHeartbeats = true } = options;
-    const reader = (await openStream(source, options)).getReader();
-    const decoder = new TextDecoder();
-    let buffer = '';
-    try {
-        while (true) {
-            const { done, value } = await reader.read();
-            if (done)
-                break;
-            buffer += decoder.decode(value, { stream: true });
-            const lines = buffer.split('\n');
-            buffer = lines.pop();
-            for (const line of lines) {
-                if (!line.trim())
-                    continue;
-                const parsed = JSON.parse(line);
-                // Skip heartbeats
-                if (skipHeartbeats && parsed.type === 'heartbeat') {
-                    continue;
+    /**
+     * One connection: open the stream and dispatch its messages until it ends.
+     * Resolves on a clean end, throws when the request or the read fails.
+     */
+    async connect(active, idleTimeoutMs, idle, retry, onActivity) {
+        const controller = new AbortController();
+        this.abortController = controller;
+        const { signal } = controller;
+        let watchdog;
+        const disarm = () => {
+            if (watchdog !== undefined)
+                clearTimeout(watchdog);
+            watchdog = undefined;
+        };
+        const arm = () => {
+            if (idleTimeoutMs <= 0)
+                return;
+            disarm();
+            watchdog = setTimeout(() => {
+                idle.timedOut = true;
+                controller.abort();
+            }, idleTimeoutMs);
+        };
+        try {
+            arm();
+            const { options } = this;
+            const body = await untilAborted('request' in options
+                ? openStream(options.request, { body: options.body, signal })
+                : openStream(options.url, {
+                    headers: options.headers,
+                    body: options.body,
+                    signal,
+                    credentials: options.credentials,
+                }), signal);
+            if (retry > 0 && this.options.onReconnect) {
+                disarm();
+                try {
+                    await this.options.onReconnect(retry);
+                }
+                catch (err) {
+                    quietly(() => body.cancel?.());
+                    throw err;
+                }
+                if (!active()) {
+                    quietly(() => body.cancel?.());
+                    return;
                 }
-                yield parsed;
+                arm();
+            }
+            for await (const message of readLines(body, signal)) {
+                if (!active())
+                    break;
+                arm();
+                onActivity();
+                if (isHeartbeat(message))
+                    continue;
+                this.dispatch(message);
             }
         }
-        // Handle remaining buffer
-        if (buffer.trim()) {
-            const parsed = JSON.parse(buffer);
-            if (!(skipHeartbeats && parsed.type === 'heartbeat')) {
-                yield parsed;
+        finally {
+            disarm();
+        }
+    }
+    /** Route one message to onDelta, a typed event listener, onPartialData or onData. */
+    dispatch(message) {
+        const wrapper = message;
+        // Handle delta events
+        if (wrapper.event === 'delta' && this.options.onDelta) {
+            const payload = wrapper.data;
+            if (payload && payload.delta) {
+                this.options.onDelta(payload.delta, payload.seq);
+            }
+            return;
+        }
+        // Handle typed events ({"event": "...", "data": ...})
+        if (wrapper.event && this.eventListeners.has(wrapper.event)) {
+            const listeners = this.eventListeners.get(wrapper.event);
+            const eventData = wrapper.data !== undefined ? wrapper.data : message;
+            const fields = wrapper.fields;
+            listeners.forEach(callback => callback(eventData, fields));
+            return;
+        }
+        // Check if it's a partial update
+        if (typeof message === 'object' &&
+            message !== null &&
+            'data' in message &&
+            'fields' in message &&
+            Array.isArray(wrapper.fields)) {
+            if (this.options.onPartialData && wrapper.data !== undefined) {
+                this.options.onPartialData(wrapper.data, wrapper.fields);
+            }
+            else if (wrapper.data !== undefined) {
+                this.options.onData?.(wrapper.data);
             }
         }
+        else if (wrapper.data !== undefined) {
+            // Has data wrapper but no fields - unwrap
+            this.options.onData?.(wrapper.data);
+        }
+        else {
+            this.options.onData?.(message);
+        }
     }
-    finally {
-        reader.releaseLock();
+    /**
+     * Wait `delayMs` before the next attempt. In a browser, coming back online
+     * or the tab becoming visible retries at once; stop() ends the wait.
+     */
+    waitToRetry(delayMs) {
+        return new Promise((resolve) => {
+            const win = typeof window !== 'undefined' && typeof window.addEventListener === 'function' ? window : undefined;
+            const doc = typeof document !== 'undefined' && typeof document.addEventListener === 'function' ? document : undefined;
+            const onVisible = () => {
+                if (doc?.visibilityState === 'visible')
+                    wake();
+            };
+            const wake = () => {
+                clearTimeout(timer);
+                win?.removeEventListener('online', wake);
+                doc?.removeEventListener('visibilitychange', onVisible);
+                if (this.wakeRetry === wake)
+                    this.wakeRetry = null;
+                resolve();
+            };
+            const timer = setTimeout(wake, delayMs);
+            win?.addEventListener('online', wake);
+            doc?.addEventListener('visibilitychange', onVisible);
+            this.wakeRetry = wake;
+        });
+    }
+    stop() {
+        this.isRunning = false;
+        this.runId++;
+        this.abortController?.abort();
+        this.abortController = null;
+        this.wakeRetry?.();
     }
 }