@furious.luke/argus-js 0.5.3 → 0.5.5

package/dist/index.d.cts

@@ -102,6 +102,12 @@ type SignalMessage = {
     turn_username?: string;
     turn_credential?: string;
     read_token?: string;
+} | {
+    type: "placement_redirect";
+    gateway_url: string;
+} | {
+    type: "unavailable";
+    retry_after_ms?: number;
 };
 /**
  * Callbacks emitted by the Publisher during its lifecycle.
@@ -119,6 +125,8 @@ interface PublisherCallbacks {
     onRecoveryRequired?: (event: PublisherRecoveryEvent) => void;
     /** Called when paced assistant text arrives alongside synthesized speech. */
     onAssistantText?: (event: AssistantTextEvent) => void;
+    /** Called on the same ordered data channel after an utterance's last caption. */
+    onAssistantTextFinished?: (event: AssistantTextFinishedEvent) => void;
     /** Called when the server accepts or rejects typed user input. */
     onUserTextResult?: (event: UserTextResultEvent) => void;
     /** Called once the explicitly requested outbound speech track arrives. */
@@ -128,6 +136,9 @@ interface AssistantTextEvent {
     utteranceId: string;
     text: string;
 }
+interface AssistantTextFinishedEvent {
+    utteranceId: string;
+}
 interface UserTextResultEvent {
     messageId: string;
     accepted: boolean;
@@ -160,7 +171,12 @@ interface GatewayReadyInfo {
  * Options for publishing a media stream.
  */
 interface PublisherOptions {
-    /** Gateway WebSocket URLs returned by POST /api/streams `gateway_urls`. All are raced simultaneously. */
+    /**
+     * Gateway WebSocket URLs returned by POST /api/streams `gateway_urls`. All are
+     * opened at once; the region whose `accepted` returns first is selected on
+     * network path, and only that region places the stream. The rest are held as
+     * standbys the publisher fails over to.
+     */
     gatewayURLs: string[];
     /** The short-lived join token from POST /api/streams. */
     token: string;
@@ -182,11 +198,26 @@ interface PublisherOptions {
      */
     turnTransportPolicy?: TurnTransportPolicy;
     /**
-     * Overall deadline for the initial accepted/proceed/ready gateway race.
-     * Unaccepted sockets are replaced after three seconds within this deadline.
-     * Defaults to 20 seconds.
+     * Overall deadline for the initial accepted/proceed/ready gateway race,
+     * spanning selection, placement, and any failovers. Sockets that have not sent
+     * `accepted` are replaced after three seconds within this deadline. Defaults to
+     * 20 seconds.
      */
     gatewayHandshakeTimeoutMs?: number;
+    /**
+     * How long the selected region has to return `ready` before the publisher
+     * abandons it and fails over to the next-fastest acknowledgement. This is a
+     * backstop for a region whose socket stays open but silent (a hung placement);
+     * a socket that closes or errors fails over immediately regardless. It is
+     * deliberately generous — placement includes the selected region's own
+     * control-plane round-trips, and a short deadline would abandon exactly the
+     * user-close-but-control-plane-distant regions this race is meant to prefer.
+     * Defaults to 8 seconds and is capped at 20 seconds: the gateway reaps a
+     * standby socket that has been accepted but not yet told to proceed, so the
+     * failover window must stay below that deadline or standbys would disappear
+     * before the browser fails over to them.
+     */
+    gatewayFailoverTimeoutMs?: number;
     /** Deadline after the initial offer for WebRTC to reach connected. Defaults to 30 seconds. */
     peerConnectionTimeoutMs?: number;
     /**

package/dist/index.d.ts

@@ -102,6 +102,12 @@ type SignalMessage = {
     turn_username?: string;
     turn_credential?: string;
     read_token?: string;
+} | {
+    type: "placement_redirect";
+    gateway_url: string;
+} | {
+    type: "unavailable";
+    retry_after_ms?: number;
 };
 /**
  * Callbacks emitted by the Publisher during its lifecycle.
@@ -119,6 +125,8 @@ interface PublisherCallbacks {
     onRecoveryRequired?: (event: PublisherRecoveryEvent) => void;
     /** Called when paced assistant text arrives alongside synthesized speech. */
     onAssistantText?: (event: AssistantTextEvent) => void;
+    /** Called on the same ordered data channel after an utterance's last caption. */
+    onAssistantTextFinished?: (event: AssistantTextFinishedEvent) => void;
     /** Called when the server accepts or rejects typed user input. */
     onUserTextResult?: (event: UserTextResultEvent) => void;
     /** Called once the explicitly requested outbound speech track arrives. */
@@ -128,6 +136,9 @@ interface AssistantTextEvent {
     utteranceId: string;
     text: string;
 }
+interface AssistantTextFinishedEvent {
+    utteranceId: string;
+}
 interface UserTextResultEvent {
     messageId: string;
     accepted: boolean;
@@ -160,7 +171,12 @@ interface GatewayReadyInfo {
  * Options for publishing a media stream.
  */
 interface PublisherOptions {
-    /** Gateway WebSocket URLs returned by POST /api/streams `gateway_urls`. All are raced simultaneously. */
+    /**
+     * Gateway WebSocket URLs returned by POST /api/streams `gateway_urls`. All are
+     * opened at once; the region whose `accepted` returns first is selected on
+     * network path, and only that region places the stream. The rest are held as
+     * standbys the publisher fails over to.
+     */
     gatewayURLs: string[];
     /** The short-lived join token from POST /api/streams. */
     token: string;
@@ -182,11 +198,26 @@ interface PublisherOptions {
      */
     turnTransportPolicy?: TurnTransportPolicy;
     /**
-     * Overall deadline for the initial accepted/proceed/ready gateway race.
-     * Unaccepted sockets are replaced after three seconds within this deadline.
-     * Defaults to 20 seconds.
+     * Overall deadline for the initial accepted/proceed/ready gateway race,
+     * spanning selection, placement, and any failovers. Sockets that have not sent
+     * `accepted` are replaced after three seconds within this deadline. Defaults to
+     * 20 seconds.
      */
     gatewayHandshakeTimeoutMs?: number;
+    /**
+     * How long the selected region has to return `ready` before the publisher
+     * abandons it and fails over to the next-fastest acknowledgement. This is a
+     * backstop for a region whose socket stays open but silent (a hung placement);
+     * a socket that closes or errors fails over immediately regardless. It is
+     * deliberately generous — placement includes the selected region's own
+     * control-plane round-trips, and a short deadline would abandon exactly the
+     * user-close-but-control-plane-distant regions this race is meant to prefer.
+     * Defaults to 8 seconds and is capped at 20 seconds: the gateway reaps a
+     * standby socket that has been accepted but not yet told to proceed, so the
+     * failover window must stay below that deadline or standbys would disappear
+     * before the browser fails over to them.
+     */
+    gatewayFailoverTimeoutMs?: number;
     /** Deadline after the initial offer for WebRTC to reach connected. Defaults to 30 seconds. */
     peerConnectionTimeoutMs?: number;
     /**

package/dist/index.js

@@ -69,6 +69,12 @@ var defaultSignalingReconnectTimeoutMs = 2e4;
 var defaultGatewayHandshakeTimeoutMs = 2e4;
 var defaultPeerConnectionTimeoutMs = 3e4;
 var initialGatewayAttemptTimeoutMs = 3e3;
+var defaultGatewayFailoverTimeoutMs = 8e3;
+var maxGatewayFailoverTimeoutMs = 2e4;
+var defaultGatewayRetryBackoffMs = 3e3;
+var minGatewayRetryBackoffMs = 250;
+var maxGatewayRetryBackoffMs = 5e3;
+var maxPlacementRedirects = 2;
 var signalingResumeAttemptTimeoutMs = 3e3;
 var signalingResumeMaxBackoffMs = 3e3;
 var senderRestartPauseMs = 100;
@@ -522,6 +528,16 @@ var Publisher = class {
   // -------------------------------------------------------------------------
   // Private helpers
   // -------------------------------------------------------------------------
+  // raceGateways opens every candidate gateway at once, then decides in two
+  // separate moments. SELECTION: the first socket to deliver `accepted` (a cheap,
+  // control-plane-free acknowledgement) is chosen on network path; the browser
+  // sends `proceed` on that one only and keeps the rest as standbys. PLACEMENT:
+  // the selected region does its control-plane work and returns `ready`. If the
+  // selection dies (socket close/error → immediately) or stalls past the failover
+  // deadline (a hung-but-open socket), the browser abandons it — closing the
+  // socket cancels that region's placement server-side — and selects the
+  // next-fastest standby. A `placement_redirect` points the browser at the region
+  // that already holds the stream so a mistimed failover self-heals.
   raceGateways(signal) {
     return new Promise((resolve, reject) => {
       const { gatewayURLs, token } = this.opts;
@@ -531,43 +547,149 @@ var Publisher = class {
       }
       const sockets = [];
       const attemptTimers = /* @__PURE__ */ new Map();
+      const reopenTimers = /* @__PURE__ */ new Set();
+      const standbys = [];
+      let selected = null;
+      let failoverTimer = null;
+      let redirects = 0;
       let settled = false;
       let timeoutTimer = null;
+      const failoverMs = Math.min(
+        maxGatewayFailoverTimeoutMs,
+        Math.max(0, this.opts.gatewayFailoverTimeoutMs ?? defaultGatewayFailoverTimeoutMs)
+      );
       const clearTimeoutTimer = () => {
         if (timeoutTimer !== null) clearTimeout(timeoutTimer);
         timeoutTimer = null;
       };
+      const clearFailoverTimer = () => {
+        if (failoverTimer !== null) clearTimeout(failoverTimer);
+        failoverTimer = null;
+      };
+      const clearReopenTimers = () => {
+        for (const timer of reopenTimers) clearTimeout(timer);
+        reopenTimers.clear();
+      };
       const clearAttemptTimer = (socket) => {
         const timer = attemptTimers.get(socket);
         if (timer !== void 0) clearTimeout(timer);
         attemptTimers.delete(socket);
       };
+      const detach = (socket) => {
+        clearAttemptTimer(socket);
+        socket.onmessage = null;
+        socket.onerror = null;
+        socket.onclose = null;
+      };
+      const dropStandby = (socket) => {
+        const i = standbys.indexOf(socket);
+        if (i !== -1) standbys.splice(i, 1);
+      };
       const closeAll = (except) => {
         for (const s of sockets) {
-          clearAttemptTimer(s);
           if (s !== except) {
-            s.onmessage = null;
-            s.onerror = null;
-            s.onclose = null;
+            detach(s);
             s.close();
           }
         }
       };
-      const checkAllFailed = () => {
-        if (settled) return;
+      const win = (ws, readyInfo, gatewayURL) => {
+        settled = true;
+        clearTimeoutTimer();
+        clearFailoverTimer();
+        clearReopenTimers();
+        signal.removeEventListener("abort", abort);
+        closeAll(ws);
+        resolve({ ws, readyInfo, gatewayURL });
+      };
+      const fail = (err) => {
+        settled = true;
+        clearTimeoutTimer();
+        clearFailoverTimer();
+        clearReopenTimers();
+        signal.removeEventListener("abort", abort);
+        closeAll();
+        reject(err);
+      };
+      const checkExhausted = () => {
+        if (settled || selected !== null || standbys.length > 0 || reopenTimers.size > 0) return;
         if (sockets.every((s) => s.readyState === WebSocket.CLOSED || s.readyState === WebSocket.CLOSING)) {
-          settled = true;
-          clearTimeoutTimer();
-          signal.removeEventListener("abort", abort);
-          reject(new Error("all gateways failed to connect"));
+          fail(new Error("all gateways failed to connect"));
         }
       };
-      const abort = () => {
+      const select = (ws) => {
+        selected = ws;
+        dropStandby(ws);
+        try {
+          ws.send(JSON.stringify({ type: "proceed" }));
+        } catch {
+          socketDown(ws);
+          return;
+        }
+        clearFailoverTimer();
+        failoverTimer = setTimeout(() => failover(ws), failoverMs);
+      };
+      const failover = (deadSocket) => {
+        if (settled || deadSocket !== selected) return;
+        clearFailoverTimer();
+        detach(deadSocket);
+        deadSocket.close();
+        selected = null;
+        const next = standbys.shift();
+        if (next) {
+          select(next);
+        } else {
+          checkExhausted();
+        }
+      };
+      const redirect = (gatewayURL) => {
         if (settled) return;
-        settled = true;
-        clearTimeoutTimer();
+        if (redirects >= maxPlacementRedirects) {
+          fail(new Error("too many placement redirects"));
+          return;
+        }
+        redirects++;
+        clearFailoverTimer();
         closeAll();
-        reject(new PublisherStoppedError("publisher stopped"));
+        standbys.length = 0;
+        selected = null;
+        try {
+          openGateway(gatewayURL);
+        } catch (err) {
+          fail(err instanceof Error ? err : new Error(String(err)));
+        }
+      };
+      const retryUnavailable = (ws, gatewayURL, retryAfterMs) => {
+        detach(ws);
+        ws.close();
+        const delay = Math.min(
+          maxGatewayRetryBackoffMs,
+          Math.max(minGatewayRetryBackoffMs, retryAfterMs ?? defaultGatewayRetryBackoffMs)
+        );
+        const timer = setTimeout(() => {
+          reopenTimers.delete(timer);
+          if (settled) return;
+          try {
+            openGateway(gatewayURL);
+          } catch (err) {
+            fail(err instanceof Error ? err : new Error(String(err)));
+          }
+        }, delay);
+        reopenTimers.add(timer);
+      };
+      const socketDown = (ws) => {
+        if (settled) return;
+        clearAttemptTimer(ws);
+        dropStandby(ws);
+        if (ws === selected) {
+          failover(ws);
+        } else {
+          checkExhausted();
+        }
+      };
+      const abort = () => {
+        if (settled) return;
+        fail(new PublisherStoppedError("publisher stopped"));
       };
       if (signal.aborted) {
         abort();
@@ -580,10 +702,7 @@ var Publisher = class {
       );
       timeoutTimer = setTimeout(() => {
         if (settled) return;
-        settled = true;
-        signal.removeEventListener("abort", abort);
-        closeAll();
-        reject(new Error(`gateway handshake timed out after ${timeoutMs}ms`));
+        fail(new Error(`gateway handshake timed out after ${timeoutMs}ms`));
       }, timeoutMs);
       const openGateway = (gatewayURL) => {
         if (settled) return;
@@ -595,58 +714,51 @@ var Publisher = class {
         const attemptTimer = setTimeout(() => {
           attemptTimers.delete(ws);
           if (settled || accepted) return;
-          ws.onmessage = null;
-          ws.onerror = null;
-          ws.onclose = null;
+          detach(ws);
           ws.close();
           try {
             openGateway(gatewayURL);
           } catch (err) {
-            settled = true;
-            clearTimeoutTimer();
-            signal.removeEventListener("abort", abort);
-            closeAll();
-            reject(err);
+            fail(err instanceof Error ? err : new Error(String(err)));
           }
         }, initialGatewayAttemptTimeoutMs);
         attemptTimers.set(ws, attemptTimer);
         ws.onmessage = (ev) => {
           if (settled) return;
+          let msg;
           try {
-            const msg = JSON.parse(ev.data);
-            if (!accepted && msg.type === "accepted") {
-              accepted = true;
-              clearAttemptTimer(ws);
-              ws.send(JSON.stringify({ type: "proceed" }));
-            } else if (accepted && msg.type === "ready") {
-              settled = true;
-              clearTimeoutTimer();
-              signal.removeEventListener("abort", abort);
-              closeAll(ws);
-              resolve({ ws, readyInfo: msg, gatewayURL });
-            }
+            msg = JSON.parse(ev.data);
           } catch {
+            return;
+          }
+          if (!accepted) {
+            if (msg.type === "unavailable") {
+              retryUnavailable(ws, gatewayURL, msg.retry_after_ms);
+              return;
+            }
+            if (msg.type !== "accepted") return;
+            accepted = true;
+            clearAttemptTimer(ws);
+            if (selected === null) select(ws);
+            else standbys.push(ws);
+            return;
+          }
+          if (ws !== selected) return;
+          if (msg.type === "ready") {
+            win(ws, msg, gatewayURL);
+          } else if (msg.type === "placement_redirect" && msg.gateway_url) {
+            redirect(msg.gateway_url);
           }
         };
-        ws.onerror = () => {
-          clearAttemptTimer(ws);
-          checkAllFailed();
-        };
-        ws.onclose = () => {
-          clearAttemptTimer(ws);
-          checkAllFailed();
-        };
+        ws.onerror = () => socketDown(ws);
+        ws.onclose = () => socketDown(ws);
       };
       try {
         for (const gatewayURL of gatewayURLs) {
           openGateway(gatewayURL);
         }
       } catch (err) {
-        settled = true;
-        clearTimeoutTimer();
-        signal.removeEventListener("abort", abort);
-        closeAll();
-        reject(err);
+        fail(err instanceof Error ? err : new Error(String(err)));
       }
     });
   }
@@ -1167,6 +1279,8 @@ var Publisher = class {
       const message = JSON.parse(data);
       if (message.type === "assistant_text" && message.utterance_id && message.text) {
         this.opts.callbacks?.onAssistantText?.({ utteranceId: message.utterance_id, text: message.text });
+      } else if (message.type === "assistant_text_finished" && message.utterance_id) {
+        this.opts.callbacks?.onAssistantTextFinished?.({ utteranceId: message.utterance_id });
       } else if ((message.type === "user_text_accepted" || message.type === "user_text_rejected") && message.message_id) {
         this.opts.callbacks?.onUserTextResult?.({
           messageId: message.message_id,