@emit-vision/sdk-js 0.1.0 → 0.2.0

package/dist/index.d.ts

@@ -56,8 +56,14 @@ export type EmitVisionOptions = {
     fetchImpl?: typeof fetch;
     /** TTL in milliseconds for in-memory flag evaluation cache. Default: 60 000 (1 minute). */
     flagEvalTtlMs?: number;
+    /** Initial delay (ms) before retrying after a flush failure. Default: 1000. Doubles each consecutive failure up to {@link retryBackoffMaxMs}. Set to 0 to retry immediately on every tick. */
+    retryBackoffInitialMs?: number;
+    /** Maximum delay (ms) between flush retries. Default: 30000. */
+    retryBackoffMaxMs?: number;
+    /** Disable the SDK after this many consecutive flush failures: the queue is dropped, future captures become no-ops, and a single warning is logged. Default: 20. Set to 0 to disable the cap and retry forever. */
+    maxConsecutiveFlushFailures?: number;
 };
-type RequiredEmitVisionOptions = Required<Pick<EmitVisionOptions, "apiKey" | "endpoint" | "flushIntervalMs" | "batchSize" | "fetchImpl" | "flushOnCapture" | "flagEvalTtlMs">> & Pick<EmitVisionOptions, "environment" | "release" | "sessionId" | "label" | "deployment" | "featureFlags" | "debug"> & {
+type RequiredEmitVisionOptions = Required<Pick<EmitVisionOptions, "apiKey" | "endpoint" | "flushIntervalMs" | "batchSize" | "fetchImpl" | "flushOnCapture" | "flagEvalTtlMs" | "retryBackoffInitialMs" | "retryBackoffMaxMs" | "maxConsecutiveFlushFailures">> & Pick<EmitVisionOptions, "environment" | "release" | "sessionId" | "label" | "deployment" | "featureFlags" | "debug"> & {
     autoCapture: Required<AutoCaptureOptions> & {
         flagExposures: boolean;
     };
@@ -74,6 +80,7 @@ declare class EmitVisionClient {
     private flushScheduled;
     private readonly fetchImpl;
     private readonly flagCache;
+    private readonly retry;
     constructor(options: RequiredEmitVisionOptions);
     captureEvent(name: string, properties?: Record<string, unknown>, options?: CaptureOptions): void;
     captureError(error: unknown, options?: CaptureOptions): void;
@@ -102,6 +109,8 @@ declare class EmitVisionClient {
     private fetchAndCacheFlags;
     setTags(tags: Record<string, string>): void;
     flush(): Promise<void>;
+    private handleFlushFailure;
+    private stopBackgroundWork;
     close(): void;
     private enqueue;
     private scheduleFlush;

package/dist/index.js

@@ -1,3 +1,4 @@
+import { FlushRetryController } from "./retry.js";
 const SDK_NAME = "emit-vision-js";
 const SDK_VERSION = "0.1.0";
 class EmitVisionClient {
@@ -12,6 +13,7 @@ class EmitVisionClient {
     flushScheduled = false;
     fetchImpl;
     flagCache = new Map();
+    retry;
     constructor(options) {
         this.options = options;
         this.fetchImpl = options.fetchImpl;
@@ -19,8 +21,13 @@ class EmitVisionClient {
             ? { ...options.deployment }
             : undefined;
         this.featureFlags = options.featureFlags ? { ...options.featureFlags } : {};
+        this.retry = new FlushRetryController({
+            initialMs: options.retryBackoffInitialMs,
+            maxMs: options.retryBackoffMaxMs,
+            failureCap: options.maxConsecutiveFlushFailures,
+        });
         this.timer = setInterval(() => {
-            if (this.queue.length === 0) {
+            if (this.queue.length === 0 || this.retry.isBackingOff()) {
                 return;
             }
             this.flush().catch((err) => this.debug("background flush error", { error: err }));
@@ -185,6 +192,9 @@ class EmitVisionClient {
         this.debug("updated tags", this.tags);
     }
     async flush() {
+        if (this.retry.isDisabled()) {
+            return;
+        }
         const batch = this.queue.splice(0, this.options.batchSize);
         if (batch.length === 0) {
             return;
@@ -208,31 +218,69 @@ class EmitVisionClient {
             });
         }
         catch (err) {
-            this.queue.unshift(...batch);
-            this.debug("flush network error", {
-                error: err,
-                restoredCount: batch.length,
-            });
+            this.handleFlushFailure(batch, { reason: "network", error: err });
             throw err;
         }
         if (!response.ok) {
-            this.queue.unshift(...batch);
-            this.debug("flush failed", {
+            const error = new Error(`emit-vision flush failed with ${response.status}`);
+            this.handleFlushFailure(batch, {
+                reason: "status",
                 status: response.status,
-                restoredCount: batch.length,
             });
-            throw new Error(`emit-vision flush failed with ${response.status}`);
+            throw error;
         }
+        this.retry.reset();
         this.debug("flush complete", { count: batch.length });
         if (this.options.flushOnCapture && this.queue.length > 0) {
             this.scheduleFlush();
         }
     }
-    close() {
+    handleFlushFailure(batch, detail) {
+        const result = this.retry.recordFailure();
+        if (result.justDisabled) {
+            const droppedQueued = this.queue.length;
+            const droppedBatch = batch.length;
+            this.queue = [];
+            this.stopBackgroundWork();
+            const message = `[emit-vision${this.options.label ? `:${this.options.label}` : ""}] ` +
+                `disabled after ${result.consecutiveFailures} consecutive flush failures; ` +
+                `dropping ${droppedQueued + droppedBatch} queued events. ` +
+                `Re-init the SDK to resume.`;
+            if (typeof console.warn === "function") {
+                console.warn(message);
+            }
+            this.debug("disabled", {
+                consecutiveFailures: result.consecutiveFailures,
+                dropped: droppedQueued + droppedBatch,
+            });
+            return;
+        }
+        this.queue.unshift(...batch);
+        if (detail.reason === "network") {
+            this.debug("flush network error", {
+                error: detail.error,
+                restoredCount: batch.length,
+                consecutiveFailures: result.consecutiveFailures,
+                backoffMs: result.backoffMs,
+            });
+        }
+        else {
+            this.debug("flush failed", {
+                status: detail.status,
+                restoredCount: batch.length,
+                consecutiveFailures: result.consecutiveFailures,
+                backoffMs: result.backoffMs,
+            });
+        }
+    }
+    stopBackgroundWork() {
         if (this.timer) {
             clearInterval(this.timer);
             this.timer = undefined;
         }
+    }
+    close() {
+        this.stopBackgroundWork();
         if (typeof window !== "undefined" && this.options.autoCapture.errors) {
             window.removeEventListener("error", this.handleWindowError);
         }
@@ -243,6 +291,9 @@ class EmitVisionClient {
         this.debug("closed client");
     }
     enqueue(payload) {
+        if (this.retry.isDisabled()) {
+            return;
+        }
         this.queue.push(payload);
         this.debug("queued payload", {
             type: payload.type,
@@ -255,10 +306,13 @@ class EmitVisionClient {
             this.debug("capture flush scheduled", {
                 queueSize: this.queue.length,
             });
-            this.flush().catch((err) => this.debug("capture flush error", { error: err }));
+            if (!this.retry.isBackingOff()) {
+                this.flush().catch((err) => this.debug("capture flush error", { error: err }));
+            }
             return;
         }
-        if (this.queue.length >= this.options.batchSize) {
+        if (this.queue.length >= this.options.batchSize &&
+            !this.retry.isBackingOff()) {
             this.flush().catch((err) => this.debug("batch flush error", { error: err }));
         }
     }
@@ -269,7 +323,7 @@ class EmitVisionClient {
         this.flushScheduled = true;
         queueMicrotask(() => {
             this.flushScheduled = false;
-            if (this.queue.length === 0) {
+            if (this.queue.length === 0 || this.retry.isBackingOff()) {
                 return;
             }
             this.flush().catch((err) => this.debug("scheduled flush error", { error: err }));
@@ -358,6 +412,9 @@ export function init(options) {
         fetchImpl: options.fetchImpl ?? globalThis.fetch.bind(globalThis),
         flushOnCapture: options.flushOnCapture ?? false,
         flagEvalTtlMs: options.flagEvalTtlMs ?? 60_000,
+        retryBackoffInitialMs: options.retryBackoffInitialMs ?? 1_000,
+        retryBackoffMaxMs: options.retryBackoffMaxMs ?? 30_000,
+        maxConsecutiveFlushFailures: options.maxConsecutiveFlushFailures ?? 20,
         apiKey: transport.apiKey,
         endpoint: transport.endpoint ?? options.endpoint ?? "http://localhost:4301",
         autoCapture,

package/dist/retry.d.ts

@@ -0,0 +1,25 @@
+export type FlushRetryOptions = {
+    /** Initial backoff in ms after the first failure. Doubles each consecutive failure. Set to 0 to disable backoff. */
+    initialMs: number;
+    /** Maximum backoff in ms between retries. */
+    maxMs: number;
+    /** Hard-shutdown threshold: after this many consecutive failures the SDK disables itself permanently. Set to 0 to disable the cap. */
+    failureCap: number;
+};
+export type RecordFailureResult = {
+    backoffMs: number;
+    consecutiveFailures: number;
+    justDisabled: boolean;
+};
+export declare class FlushRetryController {
+    private readonly opts;
+    private consecutiveFailures;
+    private backoffUntil;
+    private disabled;
+    constructor(opts: FlushRetryOptions);
+    isDisabled(): boolean;
+    isBackingOff(now?: number): boolean;
+    msUntilReady(now?: number): number;
+    reset(): void;
+    recordFailure(now?: number): RecordFailureResult;
+}

package/dist/retry.js

@@ -0,0 +1,56 @@
+export class FlushRetryController {
+    opts;
+    consecutiveFailures = 0;
+    backoffUntil = 0;
+    disabled = false;
+    constructor(opts) {
+        this.opts = opts;
+    }
+    isDisabled() {
+        return this.disabled;
+    }
+    isBackingOff(now = Date.now()) {
+        return !this.disabled && now < this.backoffUntil;
+    }
+    msUntilReady(now = Date.now()) {
+        if (this.disabled)
+            return Infinity;
+        return Math.max(0, this.backoffUntil - now);
+    }
+    reset() {
+        this.consecutiveFailures = 0;
+        this.backoffUntil = 0;
+    }
+    recordFailure(now = Date.now()) {
+        this.consecutiveFailures += 1;
+        if (this.opts.failureCap > 0 &&
+            this.consecutiveFailures >= this.opts.failureCap) {
+            const wasDisabled = this.disabled;
+            this.disabled = true;
+            this.backoffUntil = 0;
+            return {
+                backoffMs: 0,
+                consecutiveFailures: this.consecutiveFailures,
+                justDisabled: !wasDisabled,
+            };
+        }
+        if (this.opts.initialMs <= 0) {
+            this.backoffUntil = 0;
+            return {
+                backoffMs: 0,
+                consecutiveFailures: this.consecutiveFailures,
+                justDisabled: false,
+            };
+        }
+        const exp = Math.min(this.opts.initialMs * Math.pow(2, this.consecutiveFailures - 1), this.opts.maxMs);
+        // ±20% jitter so multiple clients don't synchronize their retries
+        const jitter = exp * 0.2 * (Math.random() * 2 - 1);
+        const backoffMs = Math.max(0, Math.floor(exp + jitter));
+        this.backoffUntil = now + backoffMs;
+        return {
+            backoffMs,
+            consecutiveFailures: this.consecutiveFailures,
+            justDisabled: false,
+        };
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@emit-vision/sdk-js",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Browser SDK for self-hosted emit-vision analytics and error tracking.",
   "private": false,
   "license": "MIT",