@ellipsis-dev/sdk 0.1.0

package/dist/stream/index.js

@@ -0,0 +1,207 @@
+// src/stream/index.ts
+var SESSION_STREAM_PROTOCOL_VERSION = 2;
+var WS_CLOSE_NORMAL = 1e3;
+var WS_CLOSE_GOING_AWAY = 1001;
+var WS_CLOSE_UNSUPPORTED_PROTOCOL_VERSION = 1002;
+var WS_CLOSE_NO_PROTOCOL = 1003;
+var WS_CLOSE_AUTH_FAILED = 1008;
+var WS_CLOSE_SERVER_ERROR = 1011;
+var WS_CLOSE_OVER_CAPACITY = 1013;
+function sessionStatusWord(session) {
+  return session.surface?.status ?? session.status;
+}
+var StreamUnavailableError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "StreamUnavailableError";
+  }
+};
+var StreamAuthError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "StreamAuthError";
+  }
+};
+function streamQuery(afterSeq) {
+  const base = `protocol=${SESSION_STREAM_PROTOCOL_VERSION}`;
+  return afterSeq > 0 ? `${base}&after_seq=${afterSeq}` : base;
+}
+var HEARTBEAT_TIMEOUT_MS = 45e3;
+var DEFAULT_MAX_RECONNECTS = 5;
+function classifyCloseCode(code) {
+  switch (code) {
+    case WS_CLOSE_NORMAL:
+      return "normal";
+    case WS_CLOSE_AUTH_FAILED:
+    case 4401:
+    // dashboard ticket door: bad/expired ticket
+    case 4403:
+      return "auth";
+    case WS_CLOSE_UNSUPPORTED_PROTOCOL_VERSION:
+    case WS_CLOSE_NO_PROTOCOL:
+      return "unsupported";
+    default:
+      return "retry";
+  }
+}
+function nextReconnectDelayMs(attempt) {
+  const base = 500;
+  const max = 8e3;
+  return Math.min(max, base * 2 ** Math.max(0, attempt - 1));
+}
+function decideReconnect(params) {
+  const { closeKind, everReceivedFrame, attempt, maxReconnects } = params;
+  if (closeKind === "auth") return { action: "fail-auth" };
+  if (closeKind === "unsupported") return { action: "fallback" };
+  const cap = everReceivedFrame ? maxReconnects : Math.min(2, maxReconnects);
+  if (attempt >= cap) return { action: "fallback" };
+  return { action: "reconnect", delayMs: nextReconnectDelayMs(attempt) };
+}
+function connectOnce(sock, emit, signal) {
+  return new Promise((resolve) => {
+    let settled = false;
+    let heartbeat;
+    const finish = (result) => {
+      if (settled) return;
+      settled = true;
+      if (heartbeat) clearTimeout(heartbeat);
+      if (signal) signal.removeEventListener("abort", onAbort);
+      sock.close();
+      resolve(result);
+    };
+    const onAbort = () => finish({ kind: "aborted" });
+    const bumpHeartbeat = () => {
+      if (heartbeat) clearTimeout(heartbeat);
+      heartbeat = setTimeout(
+        () => finish({ kind: "error", err: new Error("heartbeat timeout") }),
+        HEARTBEAT_TIMEOUT_MS
+      );
+    };
+    if (signal) {
+      if (signal.aborted) {
+        finish({ kind: "aborted" });
+        return;
+      }
+      signal.addEventListener("abort", onAbort);
+    }
+    sock.onOpen(() => bumpHeartbeat());
+    sock.onMessage((data) => {
+      bumpHeartbeat();
+      let frame;
+      try {
+        frame = JSON.parse(data);
+      } catch {
+        return;
+      }
+      emit(frame);
+      if (frame.type === "done") {
+        finish({ kind: "done" });
+      } else if (frame.type === "error") {
+        finish({
+          kind: "frameError",
+          message: frame.message ?? "stream error"
+        });
+      }
+    });
+    sock.onClose((code) => finish({ kind: "closed", code }));
+    sock.onError((err) => finish({ kind: "error", err }));
+  });
+}
+function sleep(ms, signal) {
+  return new Promise((resolve) => {
+    const timer = setTimeout(resolve, ms);
+    signal?.addEventListener(
+      "abort",
+      () => {
+        clearTimeout(timer);
+        resolve();
+      },
+      { once: true }
+    );
+  });
+}
+async function streamSession(opts) {
+  const maxReconnects = opts.maxReconnects ?? DEFAULT_MAX_RECONNECTS;
+  let afterSeq = opts.afterSeq ?? 0;
+  let everReceivedFrame = false;
+  let attempt = 0;
+  let lastStatusWord = "";
+  let lastExitStatus = null;
+  const emit = (frame) => {
+    everReceivedFrame = true;
+    attempt = 0;
+    if (frame.type === "records_append") {
+      const records = frame.records;
+      for (const record of records) {
+        if (typeof record.feed_seq === "number") {
+          afterSeq = Math.max(afterSeq, record.feed_seq);
+        }
+      }
+    } else if (frame.type === "snapshot" || frame.type === "session") {
+      const session = frame.session;
+      lastStatusWord = sessionStatusWord(session);
+      lastExitStatus = session.exit_status ?? null;
+    }
+    opts.onFrame(frame);
+  };
+  for (; ; ) {
+    if (opts.signal?.aborted) return { type: "aborted" };
+    let res;
+    try {
+      const sock = await opts.openSocket({
+        sessionId: opts.sessionId,
+        afterSeq,
+        query: streamQuery(afterSeq)
+      });
+      res = await connectOnce(sock, emit, opts.signal);
+    } catch (err) {
+      res = {
+        kind: "error",
+        err: err instanceof Error ? err : new Error(String(err))
+      };
+    }
+    if (res.kind === "done") {
+      return {
+        type: "done",
+        status: lastStatusWord,
+        exitStatus: lastExitStatus
+      };
+    }
+    if (res.kind === "frameError")
+      return { type: "error", message: res.message };
+    if (res.kind === "aborted") return { type: "aborted" };
+    attempt++;
+    const decision = decideReconnect({
+      closeKind: res.kind === "closed" ? classifyCloseCode(res.code) : void 0,
+      everReceivedFrame,
+      attempt,
+      maxReconnects
+    });
+    if (decision.action === "fail-auth") {
+      throw new StreamAuthError("not authorized to stream this session");
+    }
+    if (decision.action === "fallback") {
+      const why = res.kind === "error" ? res.err.message : `stream closed (code ${res.code})`;
+      throw new StreamUnavailableError(why);
+    }
+    await sleep(decision.delayMs ?? 0, opts.signal);
+  }
+}
+export {
+  SESSION_STREAM_PROTOCOL_VERSION,
+  StreamAuthError,
+  StreamUnavailableError,
+  WS_CLOSE_AUTH_FAILED,
+  WS_CLOSE_GOING_AWAY,
+  WS_CLOSE_NORMAL,
+  WS_CLOSE_NO_PROTOCOL,
+  WS_CLOSE_OVER_CAPACITY,
+  WS_CLOSE_SERVER_ERROR,
+  WS_CLOSE_UNSUPPORTED_PROTOCOL_VERSION,
+  classifyCloseCode,
+  decideReconnect,
+  nextReconnectDelayMs,
+  sessionStatusWord,
+  streamQuery,
+  streamSession
+};