@tribe-nest/media-client 0.1.0 → 0.1.1

package/src/room/room.ts

@@ -2,6 +2,7 @@ import type { EventFrame, MediaGrants } from "@tribe-nest/media-protocol";
 
 import {
   MediaSignal,
+  causeFromError,
   decideReconnect,
   initialRoomState,
   reduceRoomState,
@@ -82,12 +83,20 @@ export type MediaTrack = {
   paused: boolean;
 };
 
+/** What a local track is, in the vocabulary the node checks against `publishKinds`. */
+export type LocalPublicationSource = "camera" | "microphone" | "screen";
+
 export type LocalPublication = {
   producerId: string;
   kind: "audio" | "video";
-  source: string;
+  source: LocalPublicationSource;
   track: MediaStreamTrack;
   handle: MediaProducerHandle;
+  /**
+   * Paused at the source by `setPaused`. The capture is still open and the
+   * producer still exists; nothing is being sent. This is what a mute is.
+   */
+  paused: boolean;
 };
 
 export type MediaRoomOptions = {
@@ -122,17 +131,27 @@ export type MediaRoomOptions = {
 
 type Listener = () => void;
 
+type TransportSlot = {
+  ready: MediaTransport | undefined;
+  creating: Promise<MediaTransport> | undefined;
+};
+
 export class MediaRoom {
   private readonly signal: MediaSignal;
   private readonly device: MediaDevice;
-  private sendTransport: MediaTransport | undefined;
-  private recvTransport: MediaTransport | undefined;
+  /** One slot per direction: the finished transport, or the creation in flight. */
+  private readonly transports: Record<"send" | "recv", TransportSlot> = {
+    send: { ready: undefined, creating: undefined },
+    recv: { ready: undefined, creating: undefined },
+  };
   private iceServers: IceServer[] = [];
   private grantsValue: MediaGrants | undefined;
 
   private readonly consumers = new Map<string, MediaConsumerHandle>();
   private readonly tracksByProducer = new Map<string, MediaTrack>();
   private readonly publications = new Map<string, LocalPublication>();
+  /** Per publication: stop listening for the track ending on its own. */
+  private readonly trackEndWatchers = new Map<string, () => void>();
   private readonly listeners = new Set<Listener>();
   /** One in-flight subscribe per producer, so a burst of activeSpeakers frames
    * does not race itself into two consumers for one producer. */
@@ -158,23 +177,42 @@ export class MediaRoom {
     });
 
     this.signal.onAny((frame) => this.onFrame(frame));
-    this.signal.onClose((cause) => {
-      this.lastError = cause;
-      // Before the decision, and unconditionally. The transports are dead
-      // whatever happens next, and so is every capture that was feeding them.
-      this.teardownMedia();
-
-      if (cause.type === "closed_by_client") {
-        this.connection = "closed";
-        this.recovering = false;
-        this.emit();
-        return;
-      }
+    this.signal.onClose((cause) => this.onDisconnect(cause));
+  }
 
-      this.connection = "reconnecting";
-      this.recovering = this.scheduleReconnect(cause);
+  /**
+   * The one place that decides what happens after a connection ends, whether
+   * it ended after an hour or before a socket was ever opened.
+   */
+  private onDisconnect(cause: DisconnectCause): void {
+    this.lastError = cause;
+    // What the person was sending, before it is torn down. Recorded so the
+    // screen can say so once the room is back (see `lostPublicationSources`).
+    const wasPublishing = [...new Set([...this.publications.values()].map((p) => p.source))];
+    // Before the decision, and unconditionally. The transports are dead
+    // whatever happens next, and so is every capture that was feeding them.
+    this.teardownMedia();
+    // The active set was an instruction about consumers on THIS connection,
+    // and those are gone. Left standing, it would be mistaken by the next
+    // `joined` for a set the new node had sent ahead of the snapshot.
+    if (this.stateValue.activeSpeakers.length > 0) {
+      this.stateValue = { ...this.stateValue, activeSpeakers: [] };
+    }
+
+    // `disposed` as well as the cause: `close()` is a client close whatever the
+    // socket's own account of it, and a room that has been closed must never
+    // report itself as coming back.
+    if (cause.type === "closed_by_client" || this.disposed) {
+      this.connection = "closed";
+      this.recovering = false;
       this.emit();
-    });
+      return;
+    }
+
+    if (wasPublishing.length > 0) this.lostSources = wasPublishing;
+    this.connection = "reconnecting";
+    this.recovering = this.scheduleReconnect(cause);
+    this.emit();
   }
 
   get state(): RoomState {
@@ -219,6 +257,7 @@ export class MediaRoom {
    */
   private trackSnapshot: MediaTrack[] = [];
   private publicationSnapshot: LocalPublication[] = [];
+  private lostSources: readonly LocalPublicationSource[] = NO_SOURCES;
 
   get tracks(): MediaTrack[] {
     return this.trackSnapshot;
@@ -228,6 +267,26 @@ export class MediaRoom {
     return this.publicationSnapshot;
   }
 
+  /**
+   * What the person was sending when the connection dropped, and is not now.
+   *
+   * A drop tears down every local publication and STOPS its capture (see
+   * `teardownMedia`): the camera light goes out, which is the right thing for a
+   * capture whose session has ended and the wrong thing to do silently to a
+   * capture whose session is about to resume. The room does not republish on
+   * its own. Capture is a browser permission with a UI consequence, and turning
+   * a person's camera back on without a press, possibly minutes later, is not a
+   * decision this layer gets to make. So instead it says what was lost, and the
+   * screen tells the person, who presses the button.
+   *
+   * Cleared per source when that source is published again, and wholesale by
+   * `close()`. A stable reference while unchanged, like every other snapshot
+   * here, because `useSyncExternalStore` reads it.
+   */
+  get lostPublicationSources(): readonly LocalPublicationSource[] {
+    return this.lostSources;
+  }
+
   /** Subscribe to changes. Returns an unsubscribe. */
   onChange(listener: Listener): () => void {
     this.listeners.add(listener);
@@ -235,6 +294,14 @@ export class MediaRoom {
   }
 
   async connect(): Promise<void> {
+    // Refused BEFORE touching any state. The signal refuses this too, but by
+    // then `connection` would already read "connecting" over a socket that is
+    // joined, and nothing would ever put it back.
+    const phase = this.signal.phase;
+    if (phase === "connecting" || phase === "joining" || phase === "joined") {
+      throw new Error("connect() called on a room that is already connecting or connected");
+    }
+
     this.cancelReconnect();
     // A retry is not a first connection, and saying "Connecting to the call"
     // over a call somebody is already in reads as though they had been thrown
@@ -242,7 +309,26 @@ export class MediaRoom {
     this.connection = this.reconnectAttempt > 0 ? "reconnecting" : "connecting";
     this.emit();
 
-    const joined = await this.signal.connect();
+    // A failed attempt normally reports itself through `signal.onClose`, which
+    // routes to `onDisconnect`. This watches for that report so a rejection
+    // that arrives WITHOUT one (nothing in the signal does that today; this is
+    // the belt to its braces) is still counted as a failed attempt rather than
+    // leaving `connection` on "connecting" with no retry booked and no error
+    // to show.
+    let disconnectReported = false;
+    const stopWatching = this.signal.onClose(() => {
+      disconnectReported = true;
+    });
+
+    let joined: Awaited<ReturnType<MediaSignal["connect"]>>;
+    try {
+      joined = await this.signal.connect();
+    } catch (error) {
+      if (!disconnectReported) this.onDisconnect(causeFromError(error));
+      throw error;
+    } finally {
+      stopWatching();
+    }
 
     // RULE 1: the device loads first. Everything below needs its capabilities.
     if (!this.device.loaded) {
@@ -268,6 +354,7 @@ export class MediaRoom {
     this.cancelReconnect();
     this.recovering = false;
     this.connection = "closed";
+    this.lostSources = NO_SOURCES;
     await this.signal.leave().catch(() => undefined);
     this.teardownMedia();
     this.emit();
@@ -308,8 +395,10 @@ export class MediaRoom {
       this.reconnectTimer = undefined;
       if (this.disposed) return;
       this.reconnectAttempt += 1;
-      // A failed attempt comes back through `signal.onClose`, which is the only
-      // place that decides. Swallowed here so a retry does not surface as an
+      // A failed attempt comes back through `onDisconnect`, which is the only
+      // place that decides, and that holds for an attempt that fails BEFORE it
+      // has a socket (the ticket endpoint refusing) as much as for one that
+      // drops after an hour. Swallowed here so a retry does not surface as an
       // unhandled rejection in the host application's console.
       void this.connect().catch(() => undefined);
     }, decision.delayMs);
@@ -333,7 +422,7 @@ export class MediaRoom {
    * `publishKinds`: a token granting audio only must not be able to publish a
    * screen share by relabelling it, and the node is where that is decided.
    */
-  async publish(track: MediaStreamTrack, source: "camera" | "microphone" | "screen"): Promise<LocalPublication> {
+  async publish(track: MediaStreamTrack, source: LocalPublicationSource): Promise<LocalPublication> {
     const kind = track.kind === "audio" ? "audio" : "video";
     if (!this.device.canProduce(kind)) {
       throw new Error(`this browser cannot produce ${kind}`);
@@ -348,8 +437,23 @@ export class MediaRoom {
       source,
       track,
       handle,
+      paused: false,
     };
     this.publications.set(handle.id, publication);
+    // A track can end WITHOUT us: the browser's own "Stop sharing" bar, a
+    // camera unplugged, a device revoked from the OS. Nothing about that reaches
+    // `unpublish`, so the node kept a producer nobody was feeding and the
+    // control above still read "Stop sharing" about a share that had ended.
+    this.trackEndWatchers.set(
+      handle.id,
+      whenTrackEnds(track, () => {
+        void this.unpublish(handle.id);
+      }),
+    );
+    if (this.lostSources.includes(source)) {
+      this.lostSources = this.lostSources.filter((s) => s !== source);
+      if (this.lostSources.length === 0) this.lostSources = NO_SOURCES;
+    }
     this.emit();
     return publication;
   }
@@ -358,6 +462,8 @@ export class MediaRoom {
     const publication = this.publications.get(producerId);
     if (!publication) return;
 
+    this.trackEndWatchers.get(producerId)?.();
+    this.trackEndWatchers.delete(producerId);
     publication.handle.close();
     publication.track.stop();
     this.publications.delete(producerId);
@@ -367,16 +473,30 @@ export class MediaRoom {
     this.emit();
   }
 
+  /**
+   * Mute or unmute at the source, keeping the capture and the producer.
+   *
+   * This is what a Mute button does, and it is deliberately NOT unpublish plus
+   * publish. Every publish begins with `getUserMedia`, and Safari asks
+   * permission on every call to it, so a toggle built on republishing put a
+   * permission prompt in front of the person on every unmute. The producer is
+   * paused (mediasoup disables the track, so nothing is sent), the node is told
+   * so the other side sees `producerPaused`, and resuming is instant and asks
+   * nobody anything.
+   */
   async setPaused(producerId: string, paused: boolean): Promise<void> {
     const publication = this.publications.get(producerId);
-    if (!publication) return;
+    if (!publication || publication.paused === paused) return;
 
     if (paused) publication.handle.pause();
     else publication.handle.resume();
+    // A new object, so the snapshot moves and a screen reading `paused` follows.
+    // Emitted before the round trip: the local effect is already true.
+    this.publications.set(producerId, { ...publication, paused });
+    this.emit();
     await this.signal
       .request({ method: paused ? "pauseProducer" : "resumeProducer", producerId })
       .catch(() => undefined);
-    this.emit();
   }
 
   // -------------------------------------------------------------------------
@@ -463,22 +583,73 @@ export class MediaRoom {
   // transports
   // -------------------------------------------------------------------------
 
-  /** RULE 2: lazily, and once. */
-  private async ensureSendTransport(): Promise<MediaTransport> {
-    if (this.sendTransport) return this.sendTransport;
+  /**
+   * RULE 2: lazily, and once.
+   *
+   * "Once" has to hold under CONCURRENCY, not just in sequence. `createTransport`
+   * is a round trip to the node, and `syncSubscriptions` fans out with
+   * `Promise.all`, so one `activeSpeakers` frame naming four producers puts
+   * four callers through here in the same tick. A check of the finished
+   * transport followed by an await let all four pass the check and send four
+   * `createTransport(recv)`: the node caps transports per session, so the
+   * fourth was the last one this session would ever get and the person's own
+   * Unmute was refused with `capacity` for the rest of the call. So the thing
+   * memoised is the in-flight PROMISE, and it is memoised before anything is
+   * awaited.
+   *
+   * A creation that fails is forgotten, so the next caller tries again rather
+   * than inheriting a rejection for ever; and `teardownMedia` forgets both,
+   * because a transport created against a connection that has since died
+   * belongs to that connection, not to the one that replaces it.
+   */
+  private ensureSendTransport(): Promise<MediaTransport> {
+    return this.ensureTransport("send");
+  }
 
-    const description = (await this.signal.request({
-      method: "createTransport",
-      direction: "send",
-    })) as TransportDescription;
+  private ensureRecvTransport(): Promise<MediaTransport> {
+    return this.ensureTransport("recv");
+  }
 
-    this.sendTransport = this.device.createSendTransport({
+  private ensureTransport(direction: "send" | "recv"): Promise<MediaTransport> {
+    const slot = this.transports[direction];
+    if (slot.ready) return Promise.resolve(slot.ready);
+    if (slot.creating) return slot.creating;
+
+    const creating = this.createTransport(direction);
+    slot.creating = creating;
+    creating.then(
+      (transport) => {
+        if (slot.creating !== creating) {
+          // Torn down while the round trip was in flight. The connection this
+          // transport was created for is gone, so it is closed rather than kept
+          // for the next one.
+          transport.close();
+          return;
+        }
+        slot.ready = transport;
+        slot.creating = undefined;
+      },
+      () => {
+        if (slot.creating === creating) slot.creating = undefined;
+      },
+    );
+    return creating;
+  }
+
+  private async createTransport(direction: "send" | "recv"): Promise<MediaTransport> {
+    const description = (await this.signal.request({ method: "createTransport", direction })) as TransportDescription;
+    const onConnect = async (dtlsParameters: unknown) => {
+      await this.signal.request({ method: "connectTransport", transportId: description.transportId, dtlsParameters });
+    };
+
+    if (direction === "recv") {
+      return this.device.createRecvTransport({ description, iceServers: this.iceServers, handlers: { onConnect } });
+    }
+    return this.device.createSendTransport({
       description,
       iceServers: this.iceServers,
       handlers: {
-        onConnect: async (dtlsParameters) => {
-          await this.signal.request({ method: "connectTransport", transportId: description.transportId, dtlsParameters });
-        },
+        onConnect,
         onProduce: async ({ kind, rtpParameters, appData }) => {
           const produced = (await this.signal.request({
             method: "produce",
@@ -491,27 +662,6 @@ export class MediaRoom {
         },
       },
     });
-    return this.sendTransport;
-  }
-
-  private async ensureRecvTransport(): Promise<MediaTransport> {
-    if (this.recvTransport) return this.recvTransport;
-
-    const description = (await this.signal.request({
-      method: "createTransport",
-      direction: "recv",
-    })) as TransportDescription;
-
-    this.recvTransport = this.device.createRecvTransport({
-      description,
-      iceServers: this.iceServers,
-      handlers: {
-        onConnect: async (dtlsParameters) => {
-          await this.signal.request({ method: "connectTransport", transportId: description.transportId, dtlsParameters });
-        },
-      },
-    });
-    return this.recvTransport;
   }
 
   // -------------------------------------------------------------------------
@@ -564,16 +714,22 @@ export class MediaRoom {
     this.consumers.clear();
     this.tracksByProducer.clear();
 
+    for (const detach of this.trackEndWatchers.values()) detach();
+    this.trackEndWatchers.clear();
     for (const publication of this.publications.values()) {
       publication.handle.close();
       publication.track.stop();
     }
     this.publications.clear();
 
-    this.sendTransport?.close();
-    this.recvTransport?.close();
-    this.sendTransport = undefined;
-    this.recvTransport = undefined;
+    for (const slot of Object.values(this.transports)) {
+      slot.ready?.close();
+      slot.ready = undefined;
+      // A creation still in flight belongs to the connection that just died.
+      // Forgetting it here is what makes `ensureTransport` close the result
+      // when it lands, and what lets the next connection create its own.
+      slot.creating = undefined;
+    }
   }
 
   private emit(): void {
@@ -593,6 +749,26 @@ export class MediaRoom {
   }
 }
 
+const NO_SOURCES: readonly LocalPublicationSource[] = [];
+
+/**
+ * Call `onEnded` when a track ends on its own, and return the detach.
+ *
+ * `ended` fires when the SOURCE goes away (the browser's share bar, a device
+ * unplugged), and not for our own `track.stop()`, which is what lets
+ * `unpublish` stop the track without re-entering itself. Guarded because a
+ * track outside a browser (this package's specs hand the room bare objects) is
+ * not an `EventTarget`; in every browser it is.
+ */
+function whenTrackEnds(track: MediaStreamTrack, onEnded: () => void): () => void {
+  const target = track as Partial<Pick<EventTarget, "addEventListener" | "removeEventListener">>;
+  if (typeof target.addEventListener !== "function" || typeof target.removeEventListener !== "function") {
+    return () => undefined;
+  }
+  target.addEventListener("ended", onEnded);
+  return () => target.removeEventListener?.("ended", onEnded);
+}
+
 export async function connectToRoom(options: MediaRoomOptions): Promise<MediaRoom> {
   const room = new MediaRoom(options);
   await room.connect();