@furious.luke/argus-js 0.2.1 → 0.3.1

package/dist/index.d.cts

@@ -18,9 +18,29 @@ type SignalMessage = {
 } | {
     type: "connection_state";
     state: string;
+} | {
+    type: "media_stall";
+    track: string;
+    frame_age_ms: number;
+} | {
+    type: "media_resumed";
+    track: string;
+    duration_ms: number;
+} | {
+    type: "media_track_ended";
+    track: string;
+    reason?: string;
+} | {
+    type: "recovery_event";
+    event: "recovery_started" | "recovery_retry" | "recovery_failed";
+    track: string;
+    action?: "sender_restart" | "ice_restart";
+    reason?: "capture_ended" | "automatic_recovery_failed";
 } | {
     type: "error";
     error: string;
+} | {
+    type: "resumed";
 } | {
     type: "accepted";
 } | {
@@ -38,10 +58,24 @@ type SignalMessage = {
 interface PublisherCallbacks {
     /** Called when the WebRTC peer connection state changes. */
     onConnectionStateChange?: (state: RTCPeerConnectionState) => void;
-    /** Called when a fatal error occurs (e.g. signaling error, WebSocket close). */
+    /** Called when a fatal error occurs, including when signaling cannot resume before its deadline. */
     onError?: (error: Error) => void;
     /** Called when the browser has successfully connected to the media server. */
     onConnected?: () => void;
+    /** Called for each transition in automatic media recovery. */
+    onRecoveryStateChange?: (event: PublisherRecoveryEvent) => void;
+    /** Called when recovery requires the host application to obtain a new screen share. */
+    onRecoveryRequired?: (event: PublisherRecoveryEvent) => void;
+}
+type PublisherRecoveryState = "recovering" | "recovered" | "failed";
+type PublisherRecoveryAction = "sender_restart" | "ice_restart";
+type PublisherRecoveryFailureReason = "capture_ended" | "automatic_recovery_failed";
+/** A transition in the publisher's fixed automatic media-recovery ladder. */
+interface PublisherRecoveryEvent {
+    state: PublisherRecoveryState;
+    track: string;
+    action?: PublisherRecoveryAction;
+    reason?: PublisherRecoveryFailureReason;
 }
 /**
  * TURN and read-token info delivered in the gateway `ready` message.
@@ -51,6 +85,7 @@ interface GatewayReadyInfo {
     turn_urls?: string[];
     turn_username?: string;
     turn_credential?: string;
+    /** One-hour token used for frame reads and resuming signaling in the selected region. */
     read_token?: string;
 }
 /**
@@ -63,6 +98,8 @@ interface PublisherOptions {
     token: string;
     /** Optional extra ICE servers (e.g. STUN). TURN is supplied by the winning gateway. */
     iceServers?: RTCIceServer[];
+    /** How long to retry a dropped signaling connection to the selected gateway. Defaults to 20 seconds. */
+    signalingReconnectTimeoutMs?: number;
     /** Callbacks for lifecycle events. */
     callbacks?: PublisherCallbacks;
 }
@@ -97,8 +134,18 @@ declare class Publisher {
     private pendingRemoteCandidates;
     private localStream;
     private readToken;
+    private selectedGatewayURL;
+    private stopped;
+    private reconnecting;
+    private reconnectGeneration;
+    private resumeSocket;
+    private recoveryGeneration;
+    private recoveringMedia;
+    private recoveryRequired;
+    private recoveryAction;
+    private trackEndHandlers;
     constructor(opts: PublisherOptions);
-    /** The read token received from the gateway after connecting, for fetching frames. */
+    /** The read token used for frame fetches and signaling resume in the selected region. */
     get frameReadToken(): string | null;
     /**
      * Starts the publisher: races all gateways to find the fastest, completes
@@ -116,7 +163,23 @@ declare class Publisher {
     /** Returns true if the peer connection is in the "connected" state. */
     get isConnected(): boolean;
     private raceGateways;
+    private installSignaling;
+    private resumeSignaling;
+    private openResumeSocket;
+    private wait;
+    private terminateWithError;
     private handleSignal;
+    private beginMediaRecovery;
+    private restartSenders;
+    private renegotiate;
+    private completeMediaRecovery;
+    private failMediaRecovery;
+    private cancelMediaRecovery;
+    private isCurrentRecovery;
+    private emitRecoveryTransition;
+    private sendRecoveryDiagnostic;
+    private watchStreamTracks;
+    private unwatchStreamTracks;
     /** Waits for ICE gathering to reach the "complete" state. */
     private gatherComplete;
 }
@@ -238,4 +301,4 @@ declare function captureCamera(opts?: CaptureCameraOptions): Promise<MediaStream
  */
 declare function captureScreen(opts?: CaptureScreenOptions): Promise<MediaStream>;
 
-export { type CaptureCameraOptions, type CaptureScreenOptions, type GatewayReadyInfo, Publisher, type PublisherCallbacks, type PublisherOptions, type SignalMessage, captureCamera, captureScreen };
+export { type CaptureCameraOptions, type CaptureScreenOptions, type GatewayReadyInfo, Publisher, type PublisherCallbacks, type PublisherOptions, type PublisherRecoveryAction, type PublisherRecoveryEvent, type PublisherRecoveryFailureReason, type PublisherRecoveryState, type SignalMessage, captureCamera, captureScreen };

package/dist/index.d.ts

@@ -18,9 +18,29 @@ type SignalMessage = {
 } | {
     type: "connection_state";
     state: string;
+} | {
+    type: "media_stall";
+    track: string;
+    frame_age_ms: number;
+} | {
+    type: "media_resumed";
+    track: string;
+    duration_ms: number;
+} | {
+    type: "media_track_ended";
+    track: string;
+    reason?: string;
+} | {
+    type: "recovery_event";
+    event: "recovery_started" | "recovery_retry" | "recovery_failed";
+    track: string;
+    action?: "sender_restart" | "ice_restart";
+    reason?: "capture_ended" | "automatic_recovery_failed";
 } | {
     type: "error";
     error: string;
+} | {
+    type: "resumed";
 } | {
     type: "accepted";
 } | {
@@ -38,10 +58,24 @@ type SignalMessage = {
 interface PublisherCallbacks {
     /** Called when the WebRTC peer connection state changes. */
     onConnectionStateChange?: (state: RTCPeerConnectionState) => void;
-    /** Called when a fatal error occurs (e.g. signaling error, WebSocket close). */
+    /** Called when a fatal error occurs, including when signaling cannot resume before its deadline. */
     onError?: (error: Error) => void;
     /** Called when the browser has successfully connected to the media server. */
     onConnected?: () => void;
+    /** Called for each transition in automatic media recovery. */
+    onRecoveryStateChange?: (event: PublisherRecoveryEvent) => void;
+    /** Called when recovery requires the host application to obtain a new screen share. */
+    onRecoveryRequired?: (event: PublisherRecoveryEvent) => void;
+}
+type PublisherRecoveryState = "recovering" | "recovered" | "failed";
+type PublisherRecoveryAction = "sender_restart" | "ice_restart";
+type PublisherRecoveryFailureReason = "capture_ended" | "automatic_recovery_failed";
+/** A transition in the publisher's fixed automatic media-recovery ladder. */
+interface PublisherRecoveryEvent {
+    state: PublisherRecoveryState;
+    track: string;
+    action?: PublisherRecoveryAction;
+    reason?: PublisherRecoveryFailureReason;
 }
 /**
  * TURN and read-token info delivered in the gateway `ready` message.
@@ -51,6 +85,7 @@ interface GatewayReadyInfo {
     turn_urls?: string[];
     turn_username?: string;
     turn_credential?: string;
+    /** One-hour token used for frame reads and resuming signaling in the selected region. */
     read_token?: string;
 }
 /**
@@ -63,6 +98,8 @@ interface PublisherOptions {
     token: string;
     /** Optional extra ICE servers (e.g. STUN). TURN is supplied by the winning gateway. */
     iceServers?: RTCIceServer[];
+    /** How long to retry a dropped signaling connection to the selected gateway. Defaults to 20 seconds. */
+    signalingReconnectTimeoutMs?: number;
     /** Callbacks for lifecycle events. */
     callbacks?: PublisherCallbacks;
 }
@@ -97,8 +134,18 @@ declare class Publisher {
     private pendingRemoteCandidates;
     private localStream;
     private readToken;
+    private selectedGatewayURL;
+    private stopped;
+    private reconnecting;
+    private reconnectGeneration;
+    private resumeSocket;
+    private recoveryGeneration;
+    private recoveringMedia;
+    private recoveryRequired;
+    private recoveryAction;
+    private trackEndHandlers;
     constructor(opts: PublisherOptions);
-    /** The read token received from the gateway after connecting, for fetching frames. */
+    /** The read token used for frame fetches and signaling resume in the selected region. */
     get frameReadToken(): string | null;
     /**
      * Starts the publisher: races all gateways to find the fastest, completes
@@ -116,7 +163,23 @@ declare class Publisher {
     /** Returns true if the peer connection is in the "connected" state. */
     get isConnected(): boolean;
     private raceGateways;
+    private installSignaling;
+    private resumeSignaling;
+    private openResumeSocket;
+    private wait;
+    private terminateWithError;
     private handleSignal;
+    private beginMediaRecovery;
+    private restartSenders;
+    private renegotiate;
+    private completeMediaRecovery;
+    private failMediaRecovery;
+    private cancelMediaRecovery;
+    private isCurrentRecovery;
+    private emitRecoveryTransition;
+    private sendRecoveryDiagnostic;
+    private watchStreamTracks;
+    private unwatchStreamTracks;
     /** Waits for ICE gathering to reach the "complete" state. */
     private gatherComplete;
 }
@@ -238,4 +301,4 @@ declare function captureCamera(opts?: CaptureCameraOptions): Promise<MediaStream
  */
 declare function captureScreen(opts?: CaptureScreenOptions): Promise<MediaStream>;
 
-export { type CaptureCameraOptions, type CaptureScreenOptions, type GatewayReadyInfo, Publisher, type PublisherCallbacks, type PublisherOptions, type SignalMessage, captureCamera, captureScreen };
+export { type CaptureCameraOptions, type CaptureScreenOptions, type GatewayReadyInfo, Publisher, type PublisherCallbacks, type PublisherOptions, type PublisherRecoveryAction, type PublisherRecoveryEvent, type PublisherRecoveryFailureReason, type PublisherRecoveryState, type SignalMessage, captureCamera, captureScreen };

package/dist/index.js

@@ -45,6 +45,12 @@ function parseSignal(data) {
 }
 
 // src/publisher.ts
+var defaultSignalingReconnectTimeoutMs = 2e4;
+var signalingResumeAttemptTimeoutMs = 3e3;
+var signalingResumeMaxBackoffMs = 3e3;
+var senderRestartPauseMs = 100;
+var senderRecoveryWaitMs = 4e3;
+var iceRecoveryWaitMs = 8e3;
 var Publisher = class {
   opts;
   sig = null;
@@ -53,10 +59,20 @@ var Publisher = class {
   pendingRemoteCandidates = [];
   localStream = null;
   readToken = null;
+  selectedGatewayURL = null;
+  stopped = true;
+  reconnecting = false;
+  reconnectGeneration = 0;
+  resumeSocket = null;
+  recoveryGeneration = 0;
+  recoveringMedia = false;
+  recoveryRequired = false;
+  recoveryAction = null;
+  trackEndHandlers = /* @__PURE__ */ new Map();
   constructor(opts) {
     this.opts = opts;
   }
-  /** The read token received from the gateway after connecting, for fetching frames. */
+  /** The read token used for frame fetches and signaling resume in the selected region. */
   get frameReadToken() {
     return this.readToken;
   }
@@ -67,8 +83,12 @@ var Publisher = class {
    * use onConnected for that).
    */
   async start(stream) {
+    this.stopped = false;
+    this.recoveryRequired = false;
     this.localStream = stream;
-    const { ws, readyInfo } = await this.raceGateways();
+    this.watchStreamTracks(stream);
+    const { ws, readyInfo, gatewayURL } = await this.raceGateways();
+    this.selectedGatewayURL = gatewayURL;
     if (readyInfo.read_token) {
       this.readToken = readyInfo.read_token;
     }
@@ -103,17 +123,17 @@ var Publisher = class {
     const offer = await this.pc.createOffer();
     await this.pc.setLocalDescription(offer);
     await this.gatherComplete();
-    this.sig = SignalingChannel.wrap(ws);
-    this.sig.onMessage = (msg) => this.handleSignal(msg);
-    this.sig.onClose = () => this.opts.callbacks?.onError?.(new Error("signaling closed"));
-    this.sig.onError = (err) => this.opts.callbacks?.onError?.(err);
+    const signaling = this.installSignaling(ws);
     const local = this.pc.localDescription;
     if (!local) throw new Error("local description missing after gather");
-    this.sig.send({ type: "offer", sdp: local.sdp, sdp_type: "offer" });
+    signaling.send({ type: "offer", sdp: local.sdp, sdp_type: "offer" });
   }
   /** Replaces the currently published stream with a new one. */
   async replaceStream(stream) {
     if (!this.pc) throw new Error("publisher not started");
+    this.cancelMediaRecovery();
+    this.recoveryRequired = false;
+    this.unwatchStreamTracks();
     const senders = this.pc.getSenders();
     for (const sender of senders) {
       if (sender.track) {
@@ -124,21 +144,20 @@ var Publisher = class {
       this.pc.addTrack(track, stream);
     }
     this.localStream = stream;
-    const offer = await this.pc.createOffer();
-    await this.pc.setLocalDescription(offer);
-    await this.gatherComplete();
-    const local = this.pc.localDescription;
-    if (!local) throw new Error("local description missing");
-    this.sig?.send({
-      type: "offer",
-      sdp: local.sdp,
-      sdp_type: "offer"
-    });
+    this.watchStreamTracks(stream);
+    await this.renegotiate(false);
   }
   /** Stops publishing and tears down the peer connection. */
   stop() {
+    this.stopped = true;
+    this.cancelMediaRecovery();
+    this.reconnectGeneration++;
+    this.reconnecting = false;
+    this.resumeSocket?.close();
+    this.resumeSocket = null;
     this.sig?.close();
     this.sig = null;
+    this.unwatchStreamTracks();
     this.localStream?.getTracks().forEach((t) => t.stop());
     this.localStream = null;
     this.pc?.close();
@@ -146,6 +165,7 @@ var Publisher = class {
     this.hasAnswer = false;
     this.pendingRemoteCandidates = [];
     this.readToken = null;
+    this.selectedGatewayURL = null;
   }
   /** Returns the current RTCPeerConnection, or null if not started. */
   get peerConnection() {
@@ -200,7 +220,7 @@ var Publisher = class {
             } else if (accepted && msg.type === "ready") {
               settled = true;
               closeAll(ws);
-              resolve({ ws, readyInfo: msg });
+              resolve({ ws, readyInfo: msg, gatewayURL });
             }
           } catch {
           }
@@ -210,6 +230,113 @@ var Publisher = class {
       }
     });
   }
+  installSignaling(ws) {
+    const channel = SignalingChannel.wrap(ws);
+    this.sig = channel;
+    channel.onMessage = (msg) => this.handleSignal(msg);
+    channel.onClose = () => {
+      if (this.sig !== channel || this.stopped) return;
+      this.sig = null;
+      void this.resumeSignaling();
+    };
+    channel.onError = () => {
+    };
+    return channel;
+  }
+  async resumeSignaling() {
+    if (this.reconnecting || this.stopped) return;
+    if (!this.selectedGatewayURL || !this.readToken) {
+      this.terminateWithError(new Error("signaling closed and cannot be resumed"));
+      return;
+    }
+    this.reconnecting = true;
+    const generation = ++this.reconnectGeneration;
+    const timeout = this.opts.signalingReconnectTimeoutMs ?? defaultSignalingReconnectTimeoutMs;
+    const deadline = Date.now() + Math.max(0, timeout);
+    let backoffMs = 0;
+    while (!this.stopped && generation === this.reconnectGeneration && Date.now() <= deadline) {
+      if (backoffMs > 0) {
+        const waitMs = Math.min(backoffMs, Math.max(0, deadline - Date.now()));
+        if (waitMs === 0) break;
+        await this.wait(waitMs);
+        if (this.stopped || generation !== this.reconnectGeneration) return;
+      }
+      const remaining = deadline - Date.now();
+      if (remaining < 0) break;
+      try {
+        const ws = await this.openResumeSocket(Math.min(signalingResumeAttemptTimeoutMs, Math.max(1, remaining)));
+        if (this.stopped || generation !== this.reconnectGeneration) {
+          ws.close();
+          return;
+        }
+        this.resumeSocket = null;
+        this.reconnecting = false;
+        this.installSignaling(ws);
+        return;
+      } catch {
+        backoffMs = backoffMs === 0 ? 250 : Math.min(backoffMs * 2, signalingResumeMaxBackoffMs);
+      }
+    }
+    if (!this.stopped && generation === this.reconnectGeneration) {
+      this.reconnecting = false;
+      this.terminateWithError(new Error("unable to resume signaling with the selected gateway"));
+    }
+  }
+  openResumeSocket(timeoutMs) {
+    return new Promise((resolve, reject) => {
+      const u = new URL(this.selectedGatewayURL);
+      u.searchParams.set("token", this.readToken);
+      const ws = new WebSocket(u.toString());
+      this.resumeSocket = ws;
+      let settled = false;
+      const timer = setTimeout(() => fail(), timeoutMs);
+      const fail = () => {
+        if (settled) return;
+        settled = true;
+        clearTimeout(timer);
+        if (this.resumeSocket === ws) this.resumeSocket = null;
+        ws.onmessage = null;
+        ws.onerror = null;
+        ws.onclose = null;
+        ws.close();
+        reject(new Error("signaling resume attempt failed"));
+      };
+      ws.onmessage = (ev) => {
+        try {
+          const msg = JSON.parse(ev.data);
+          if (msg.type !== "resumed" || settled) return;
+          settled = true;
+          clearTimeout(timer);
+          resolve(ws);
+        } catch {
+        }
+      };
+      ws.onerror = fail;
+      ws.onclose = fail;
+    });
+  }
+  wait(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+  }
+  terminateWithError(err) {
+    this.stopped = true;
+    this.cancelMediaRecovery();
+    this.reconnectGeneration++;
+    this.resumeSocket?.close();
+    this.resumeSocket = null;
+    this.sig?.close();
+    this.sig = null;
+    this.pc?.close();
+    this.pc = null;
+    this.unwatchStreamTracks();
+    this.localStream?.getTracks().forEach((track) => track.stop());
+    this.localStream = null;
+    this.hasAnswer = false;
+    this.pendingRemoteCandidates = [];
+    this.readToken = null;
+    this.selectedGatewayURL = null;
+    this.opts.callbacks?.onError?.(err);
+  }
   handleSignal(msg) {
     switch (msg.type) {
       case "answer": {
@@ -249,11 +376,123 @@ var Publisher = class {
       case "connection_state": {
         break;
       }
+      case "media_stall":
+      case "media_track_ended": {
+        void this.beginMediaRecovery(msg.track);
+        break;
+      }
+      case "media_resumed": {
+        this.completeMediaRecovery(msg.track);
+        break;
+      }
       case "error": {
         this.opts.callbacks?.onError?.(new Error(msg.error));
         break;
       }
+      case "resumed":
+        break;
+    }
+  }
+  async beginMediaRecovery(trackType) {
+    if (this.stopped || this.recoveringMedia || this.recoveryRequired) return;
+    const tracks = this.localStream?.getVideoTracks() ?? [];
+    const liveTracks = tracks.filter((track) => track.readyState !== "ended");
+    if (liveTracks.length === 0) {
+      this.failMediaRecovery(trackType, "capture_ended");
+      return;
+    }
+    this.recoveringMedia = true;
+    const generation = ++this.recoveryGeneration;
+    this.recoveryAction = "sender_restart";
+    this.emitRecoveryTransition({ state: "recovering", track: trackType, action: "sender_restart" });
+    this.sendRecoveryDiagnostic("recovery_started", trackType, "sender_restart");
+    await this.restartSenders(liveTracks, generation);
+    if (!this.isCurrentRecovery(generation)) return;
+    await this.wait(senderRecoveryWaitMs);
+    if (!this.isCurrentRecovery(generation)) return;
+    this.recoveryAction = "ice_restart";
+    this.emitRecoveryTransition({ state: "recovering", track: trackType, action: "ice_restart" });
+    this.sendRecoveryDiagnostic("recovery_retry", trackType, "ice_restart");
+    try {
+      await this.renegotiate(true);
+    } catch {
+    }
+    await this.wait(iceRecoveryWaitMs);
+    if (!this.isCurrentRecovery(generation)) return;
+    this.failMediaRecovery(trackType, "automatic_recovery_failed");
+  }
+  async restartSenders(tracks, generation) {
+    const live = new Set(tracks);
+    const senders = this.pc?.getSenders().filter(
+      (sender) => sender.track && live.has(sender.track)
+    ) ?? [];
+    if (senders.length === 0) return;
+    const originals = senders.map((sender) => ({ sender, track: sender.track }));
+    try {
+      await Promise.all(originals.map(({ sender }) => sender.replaceTrack(null)));
+      await this.wait(senderRestartPauseMs);
+      if (!this.isCurrentRecovery(generation)) return;
+      await Promise.all(originals.map(({ sender, track }) => sender.replaceTrack(track)));
+      await this.renegotiate(false);
+    } catch {
+    }
+  }
+  async renegotiate(iceRestart) {
+    const pc = this.pc;
+    const signaling = this.sig;
+    if (!pc || !signaling) throw new Error("publisher signaling is unavailable");
+    if (iceRestart) pc.restartIce?.();
+    const offer = await pc.createOffer(iceRestart ? { iceRestart: true } : void 0);
+    await pc.setLocalDescription(offer);
+    await this.gatherComplete();
+    const local = pc.localDescription;
+    if (!local) throw new Error("local description missing");
+    this.hasAnswer = false;
+    this.pendingRemoteCandidates = [];
+    signaling.send({ type: "offer", sdp: local.sdp, sdp_type: "offer" });
+  }
+  completeMediaRecovery(trackType) {
+    if (!this.recoveringMedia) return;
+    const action = this.recoveryAction ?? void 0;
+    this.cancelMediaRecovery();
+    this.emitRecoveryTransition({ state: "recovered", track: trackType, action });
+  }
+  failMediaRecovery(trackType, reason) {
+    if (this.stopped || this.recoveryRequired) return;
+    this.recoveryRequired = true;
+    const action = this.recoveryAction ?? void 0;
+    this.cancelMediaRecovery();
+    const event = { state: "failed", track: trackType, action, reason };
+    this.emitRecoveryTransition(event);
+    this.opts.callbacks?.onRecoveryRequired?.(event);
+    this.sendRecoveryDiagnostic("recovery_failed", trackType, action, reason);
+  }
+  cancelMediaRecovery() {
+    this.recoveryGeneration++;
+    this.recoveringMedia = false;
+    this.recoveryAction = null;
+  }
+  isCurrentRecovery(generation) {
+    return !this.stopped && this.recoveringMedia && generation === this.recoveryGeneration;
+  }
+  emitRecoveryTransition(event) {
+    this.opts.callbacks?.onRecoveryStateChange?.(event);
+  }
+  sendRecoveryDiagnostic(event, track, action, reason) {
+    this.sig?.send({ type: "recovery_event", event, track, action, reason });
+  }
+  watchStreamTracks(stream) {
+    for (const track of stream.getVideoTracks()) {
+      const handler = () => this.failMediaRecovery("screen", "capture_ended");
+      track.addEventListener("ended", handler);
+      this.trackEndHandlers.set(track, handler);
+    }
+  }
+  unwatchStreamTracks() {
+    for (const [track, handler] of this.trackEndHandlers) {
+      track.removeEventListener("ended", handler);
     }
+    this.trackEndHandlers.clear();
   }
   /** Waits for ICE gathering to reach the "complete" state. */
   gatherComplete() {