retrace-sdk 0.1.5 → 0.1.6

package/dist/transport.d.ts

@@ -5,8 +5,10 @@ export interface Transport {
 export declare class WSTransport implements Transport {
     private ws;
     private connected;
+    private closed;
     private backoff;
     private queue;
+    get isConnected(): boolean;
     connect(): void;
     private reconnect;
     private flushQueue;

package/dist/transport.js

@@ -3,9 +3,13 @@ import { getConfig } from "./config.js";
 export class WSTransport {
     ws = null;
     connected = false;
+    closed = false;
     backoff = 1000;
     queue = [];
+    get isConnected() { return this.connected; }
     connect() {
+        if (this.closed)
+            return;
         const cfg = getConfig();
         const url = `${cfg.wsUrl}/ws/v1/stream`;
         this.ws = new WebSocket(url);
@@ -26,15 +30,17 @@ export class WSTransport {
         this.ws.on("close", () => {
             this.connected = false;
             this.ws = null;
-            setTimeout(() => this.reconnect(), this.backoff);
-            this.backoff = Math.min(this.backoff * 2, 30000);
+            if (!this.closed) {
+                setTimeout(() => this.reconnect(), this.backoff);
+                this.backoff = Math.min(this.backoff * 2, 30000);
+            }
         });
         this.ws.on("error", () => {
             this.ws?.close();
         });
     }
     reconnect() {
-        if (!this.connected && !this.ws)
+        if (!this.closed && !this.connected && !this.ws)
             this.connect();
     }
     flushQueue() {
@@ -49,11 +55,12 @@ export class WSTransport {
         }
         else {
             this.queue.push(msg);
-            if (!this.ws)
+            if (!this.ws && !this.closed)
                 this.connect();
         }
     }
     close() {
+        this.closed = true;
         if (this.ws) {
             this.ws.close();
             this.ws = null;
@@ -114,11 +121,61 @@ export function createTransport(mode = "auto") {
         return new HTTPTransport();
     if (mode === "ws")
         return new WSTransport();
-    // Auto: try WS
-    try {
-        return new WSTransport();
-    }
-    catch {
-        return new HTTPTransport();
-    }
+    // Auto: start with WS, fall back to HTTP if connection fails within timeout
+    const ws = new WSTransport();
+    const http = new HTTPTransport();
+    let useWs = true;
+    let decided = false;
+    const buffer = [];
+    const fallbackTimer = setTimeout(() => {
+        if (!decided && !ws.isConnected) {
+            decided = true;
+            useWs = false;
+            ws.close();
+            for (const item of buffer.splice(0))
+                http.send(item.eventType, item.data);
+        }
+    }, 5000);
+    ws.connect();
+    const originalSend = ws.send.bind(ws);
+    const checkConnected = () => {
+        if (!decided && ws.isConnected) {
+            decided = true;
+            clearTimeout(fallbackTimer);
+            for (const item of buffer.splice(0))
+                originalSend(item.eventType, item.data);
+        }
+    };
+    return {
+        send(eventType, data) {
+            checkConnected();
+            if (decided) {
+                if (useWs)
+                    originalSend(eventType, data);
+                else
+                    http.send(eventType, data);
+            }
+            else {
+                buffer.push({ eventType, data });
+            }
+        },
+        close() {
+            clearTimeout(fallbackTimer);
+            if (!decided) {
+                // WS not yet connected — force HTTP fallback to avoid data loss
+                decided = true;
+                useWs = false;
+                ws.close();
+                for (const item of buffer.splice(0))
+                    http.send(item.eventType, item.data);
+                http.close();
+            }
+            else if (useWs) {
+                ws.close();
+            }
+            else {
+                http.close();
+            }
+        },
+    };
 }

package/dist/transport.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/transport.test.js

@@ -0,0 +1,67 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+import { configure } from "./config.js";
+// Mock WebSocket to never connect (simulates unreachable WS endpoint)
+const mockWsInstances = [];
+vi.mock("ws", () => {
+    const MockWebSocket = function () {
+        this.readyState = 0;
+        this._listeners = {};
+        this.on = (event, cb) => { (this._listeners[event] ??= []).push(cb); return this; };
+        this.send = vi.fn();
+        this.close = vi.fn(() => {
+            this.readyState = 3;
+            for (const cb of (this._listeners["close"] ?? []))
+                cb();
+        });
+        mockWsInstances.push(this);
+    };
+    MockWebSocket.OPEN = 1;
+    return { default: MockWebSocket };
+});
+beforeEach(() => {
+    configure({ apiKey: "rt_live_test", baseUrl: "http://localhost:3001", enabled: true });
+    mockWsInstances.length = 0;
+});
+afterEach(() => {
+    vi.unstubAllGlobals();
+});
+describe("Auto transport fallback on early close()", () => {
+    it("flushes to HTTP when close() is called before WS connects", async () => {
+        const mockFetch = vi.fn().mockResolvedValue({ ok: true });
+        vi.stubGlobal("fetch", mockFetch);
+        const { createTransport } = await import("./transport.js");
+        const transport = createTransport("auto");
+        // Send trace events immediately (before WS could connect)
+        transport.send("trace_started", { id: "t1", name: "fast-trace", status: "running", started_at: "2026-01-01T00:00:00Z", total_tokens: 0, total_cost: 0, total_duration_ms: 0 });
+        transport.send("span_started", { id: "s1", trace_id: "t1", span_type: "llm_call", name: "call", started_at: "2026-01-01T00:00:00Z" });
+        transport.send("span_ended", { id: "s1", ended_at: "2026-01-01T00:00:01Z", output: "response" });
+        transport.send("trace_ended", { id: "t1", ended_at: "2026-01-01T00:00:01Z", status: "completed" });
+        // Close immediately — WS has NOT connected yet
+        transport.close();
+        // Should have fallen back to HTTP and flushed
+        expect(mockFetch).toHaveBeenCalledTimes(1);
+        const [url, opts] = mockFetch.mock.calls[0];
+        expect(url).toBe("http://localhost:3001/api/v1/traces");
+        const body = JSON.parse(opts.body);
+        expect(body.id).toBe("t1");
+        expect(body.name).toBe("fast-trace");
+        expect(body.spans).toHaveLength(1);
+        expect(body.spans[0].output).toBe("response");
+    });
+    it("does NOT reconnect after intentional close()", async () => {
+        vi.stubGlobal("fetch", vi.fn().mockResolvedValue({ ok: true }));
+        const { WSTransport } = await import("./transport.js");
+        const ws = new WSTransport();
+        ws.connect();
+        // Should have created a WS instance
+        expect(mockWsInstances.length).toBeGreaterThan(0);
+        const instanceCount = mockWsInstances.length;
+        // Close intentionally
+        ws.close();
+        // Trigger the "close" event that was registered — already fired by our mock's close()
+        // Wait a tick for any setTimeout reconnect to fire
+        await new Promise(r => setTimeout(r, 1100));
+        // Should NOT have created new WS instances (no reconnect)
+        expect(mockWsInstances.length).toBe(instanceCount);
+    });
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "retrace-sdk",
-  "version": "0.1.5",
+  "version": "0.1.6",
   "description": "The execution replay engine for AI agents. Record, replay, fork, and share agent executions.",
   "type": "module",
   "main": "dist/index.js",

package/src/transport.test.ts

@@ -0,0 +1,80 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+import { configure } from "./config.js";
+
+// Mock WebSocket to never connect (simulates unreachable WS endpoint)
+const mockWsInstances: Array<Record<string, unknown>> = [];
+vi.mock("ws", () => {
+  const MockWebSocket = function (this: Record<string, unknown>) {
+    this.readyState = 0;
+    this._listeners = {} as Record<string, Array<() => void>>;
+    this.on = (event: string, cb: () => void) => { ((this._listeners as Record<string, Array<() => void>>)[event] ??= []).push(cb); return this; };
+    this.send = vi.fn();
+    this.close = vi.fn(() => {
+      this.readyState = 3;
+      for (const cb of ((this._listeners as Record<string, Array<() => void>>)["close"] ?? [])) cb();
+    });
+    mockWsInstances.push(this);
+  } as unknown as { new(): Record<string, unknown>; OPEN: number };
+  MockWebSocket.OPEN = 1;
+  return { default: MockWebSocket };
+});
+
+beforeEach(() => {
+  configure({ apiKey: "rt_live_test", baseUrl: "http://localhost:3001", enabled: true });
+  mockWsInstances.length = 0;
+});
+
+afterEach(() => {
+  vi.unstubAllGlobals();
+});
+
+describe("Auto transport fallback on early close()", () => {
+  it("flushes to HTTP when close() is called before WS connects", async () => {
+    const mockFetch = vi.fn().mockResolvedValue({ ok: true });
+    vi.stubGlobal("fetch", mockFetch);
+
+    const { createTransport } = await import("./transport.js");
+    const transport = createTransport("auto");
+
+    // Send trace events immediately (before WS could connect)
+    transport.send("trace_started", { id: "t1", name: "fast-trace", status: "running", started_at: "2026-01-01T00:00:00Z", total_tokens: 0, total_cost: 0, total_duration_ms: 0 });
+    transport.send("span_started", { id: "s1", trace_id: "t1", span_type: "llm_call", name: "call", started_at: "2026-01-01T00:00:00Z" });
+    transport.send("span_ended", { id: "s1", ended_at: "2026-01-01T00:00:01Z", output: "response" });
+    transport.send("trace_ended", { id: "t1", ended_at: "2026-01-01T00:00:01Z", status: "completed" });
+
+    // Close immediately — WS has NOT connected yet
+    transport.close();
+
+    // Should have fallen back to HTTP and flushed
+    expect(mockFetch).toHaveBeenCalledTimes(1);
+    const [url, opts] = mockFetch.mock.calls[0];
+    expect(url).toBe("http://localhost:3001/api/v1/traces");
+    const body = JSON.parse(opts.body);
+    expect(body.id).toBe("t1");
+    expect(body.name).toBe("fast-trace");
+    expect(body.spans).toHaveLength(1);
+    expect(body.spans[0].output).toBe("response");
+  });
+
+  it("does NOT reconnect after intentional close()", async () => {
+    vi.stubGlobal("fetch", vi.fn().mockResolvedValue({ ok: true }));
+
+    const { WSTransport } = await import("./transport.js");
+    const ws = new WSTransport();
+    ws.connect();
+
+    // Should have created a WS instance
+    expect(mockWsInstances.length).toBeGreaterThan(0);
+    const instanceCount = mockWsInstances.length;
+
+    // Close intentionally
+    ws.close();
+
+    // Trigger the "close" event that was registered — already fired by our mock's close()
+    // Wait a tick for any setTimeout reconnect to fire
+    await new Promise(r => setTimeout(r, 1100));
+
+    // Should NOT have created new WS instances (no reconnect)
+    expect(mockWsInstances.length).toBe(instanceCount);
+  });
+});

package/src/transport.ts

@@ -9,10 +9,14 @@ export interface Transport {
 export class WSTransport implements Transport {
   private ws: WebSocket | null = null;
   private connected = false;
+  private closed = false;
   private backoff = 1000;
   private queue: string[] = [];
 
+  get isConnected() { return this.connected; }
+
   connect() {
+    if (this.closed) return;
     const cfg = getConfig();
     const url = `${cfg.wsUrl}/ws/v1/stream`;
     this.ws = new WebSocket(url);
@@ -35,8 +39,10 @@ export class WSTransport implements Transport {
     this.ws.on("close", () => {
       this.connected = false;
       this.ws = null;
-      setTimeout(() => this.reconnect(), this.backoff);
-      this.backoff = Math.min(this.backoff * 2, 30000);
+      if (!this.closed) {
+        setTimeout(() => this.reconnect(), this.backoff);
+        this.backoff = Math.min(this.backoff * 2, 30000);
+      }
     });
 
     this.ws.on("error", () => {
@@ -45,7 +51,7 @@ export class WSTransport implements Transport {
   }
 
   private reconnect() {
-    if (!this.connected && !this.ws) this.connect();
+    if (!this.closed && !this.connected && !this.ws) this.connect();
   }
 
   private flushQueue() {
@@ -60,11 +66,12 @@ export class WSTransport implements Transport {
       this.ws.send(msg);
     } else {
       this.queue.push(msg);
-      if (!this.ws) this.connect();
+      if (!this.ws && !this.closed) this.connect();
     }
   }
 
   close() {
+    this.closed = true;
     if (this.ws) {
       this.ws.close();
       this.ws = null;
@@ -124,10 +131,58 @@ export class HTTPTransport implements Transport {
 export function createTransport(mode: "ws" | "http" | "auto" = "auto"): Transport {
   if (mode === "http") return new HTTPTransport();
   if (mode === "ws") return new WSTransport();
-  // Auto: try WS
-  try {
-    return new WSTransport();
-  } catch {
-    return new HTTPTransport();
-  }
+
+  // Auto: start with WS, fall back to HTTP if connection fails within timeout
+  const ws = new WSTransport();
+  const http = new HTTPTransport();
+  let useWs = true;
+  let decided = false;
+  const buffer: Array<{ eventType: string; data: Record<string, unknown> }> = [];
+
+  const fallbackTimer = setTimeout(() => {
+    if (!decided && !ws.isConnected) {
+      decided = true;
+      useWs = false;
+      ws.close();
+      for (const item of buffer.splice(0)) http.send(item.eventType, item.data);
+    }
+  }, 5000);
+
+  ws.connect();
+
+  const originalSend = ws.send.bind(ws);
+  const checkConnected = () => {
+    if (!decided && ws.isConnected) {
+      decided = true;
+      clearTimeout(fallbackTimer);
+      for (const item of buffer.splice(0)) originalSend(item.eventType, item.data);
+    }
+  };
+
+  return {
+    send(eventType: string, data: Record<string, unknown>) {
+      checkConnected();
+      if (decided) {
+        if (useWs) originalSend(eventType, data);
+        else http.send(eventType, data);
+      } else {
+        buffer.push({ eventType, data });
+      }
+    },
+    close() {
+      clearTimeout(fallbackTimer);
+      if (!decided) {
+        // WS not yet connected — force HTTP fallback to avoid data loss
+        decided = true;
+        useWs = false;
+        ws.close();
+        for (const item of buffer.splice(0)) http.send(item.eventType, item.data);
+        http.close();
+      } else if (useWs) {
+        ws.close();
+      } else {
+        http.close();
+      }
+    },
+  };
 }