@tribe-nest/media-client 0.1.0

package/src/room/room.ts

@@ -0,0 +1,600 @@
+import type { EventFrame, MediaGrants } from "@tribe-nest/media-protocol";
+
+import {
+  MediaSignal,
+  decideReconnect,
+  initialRoomState,
+  reduceRoomState,
+  type DisconnectCause,
+  type MediaCoreCredentials,
+  type MediaWebSocketFactory,
+  type ReconnectOptions,
+  type RoomState,
+  type SignalLogLevel,
+} from "../core";
+import type {
+  IceServer,
+  MediaConsumerHandle,
+  MediaDevice,
+  MediaDeviceFactory,
+  MediaProducerHandle,
+  MediaTransport,
+  RtpParameters,
+  TransportDescription,
+} from "./device";
+
+/**
+ * The room: a live call, as an application sees it.
+ *
+ * ## The ordering rules, which are the whole content of this file
+ *
+ * Four of them, each with a failure that is invisible until somebody is on a
+ * call:
+ *
+ * 1. **The device loads before anything else.** `consume` on the node needs our
+ *    `rtpCapabilities`, and those do not exist until the device has been loaded
+ *    with the router's. Getting this wrong produces a `consume` that is refused
+ *    for a reason that reads like a codec problem.
+ * 2. **A transport is created lazily and ONCE per direction.** Creating one
+ *    eagerly costs an ICE gather for a participant who may only ever watch.
+ *    Creating two costs a second DTLS handshake and splits the media across
+ *    transports for no reason.
+ * 3. **A consumer is resumed only after its track is attached.** The node
+ *    creates every consumer paused, deliberately: media arriving before there
+ *    is anywhere to put it is dropped, and for video that means waiting for the
+ *    next keyframe to see anything. So the resume belongs after the application
+ *    has the track, not at consume time.
+ * 4. **`autoSubscribe` follows the ACTIVE SET, not the producer list.** The
+ *    node refuses a consume outside it, so a client that subscribed to
+ *    everything would generate a refusal per producer in any room over the
+ *    threshold and show nothing for its trouble.
+ *
+ * ## Coming back is part of the room, not part of the application
+ *
+ * A socket that dies mid-call leaves the room in `reconnecting`, and a state
+ * called "reconnecting" that nothing reconnects is worse than one called
+ * "closed": the screen above it draws a spinner and promises a recovery no code
+ * is performing, so the person waits instead of reloading. So the room itself
+ * drives `core/reconnect.ts`'s policy - fresh credentials through `MEDIA_URL`
+ * every attempt, the node's own drain window honoured, a closed room never
+ * rejoined - and publishes whether an attempt is actually booked
+ * (`isRecovering`) so a UI can tell "wait" from "press something".
+ *
+ * ## What this deliberately does not do
+ *
+ * Decide whether it is allowed to see somebody. `grants` are carried for
+ * RENDERING - so a UI does not offer a control the node is about to refuse -
+ * and the node enforces independently. A client copy of an authorization
+ * decision is a UI hint; treating it as the decision is how a barrier ends up
+ * enforced in the one place an attacker controls.
+ */
+
+export type MediaRoomCredentials = MediaCoreCredentials;
+
+export type ConnectionState = "idle" | "connecting" | "connected" | "reconnecting" | "closed";
+
+export type MediaTrack = {
+  producerId: string;
+  identity: string;
+  kind: "audio" | "video";
+  track: MediaStreamTrack;
+  /** Paused at the SOURCE, as the publisher left it. */
+  paused: boolean;
+};
+
+export type LocalPublication = {
+  producerId: string;
+  kind: "audio" | "video";
+  source: string;
+  track: MediaStreamTrack;
+  handle: MediaProducerHandle;
+};
+
+export type MediaRoomOptions = {
+  /**
+   * Called before EVERY attempt. A join ticket expires in minutes and a call
+   * lasts an hour, so `{ url, token }` passed once is a defect rather than a
+   * naming choice: the first reconnect would present an expired token.
+   */
+  getCredentials: () => Promise<MediaRoomCredentials> | MediaRoomCredentials;
+  /** Follow the node's active set automatically. On by default: a client that
+   * does not follow it shows black tiles in any room over the threshold. */
+  autoSubscribe?: boolean;
+  /**
+   * Required, and supplied by the entry point rather than defaulted here.
+   *
+   * `room.ts` importing the browser device - even lazily - would make this file
+   * un-loadable outside a browser and drag `mediasoup-client` into any bundle
+   * that wanted the room TYPES. The root barrel is the browser entry and is
+   * where `createBrowserDevice` is wired in.
+   */
+  device: MediaDeviceFactory;
+  webSocket?: MediaWebSocketFactory;
+  /**
+   * How hard to try to get back in after a drop. Defaults to
+   * `DEFAULT_RECONNECT_OPTIONS`; `{ maxAttempts: 0 }` turns automatic recovery
+   * off, which leaves `isRecovering` false and is what tells a UI to offer a
+   * control instead of a spinner.
+   */
+  reconnect?: Partial<ReconnectOptions>;
+  onLog?: (level: SignalLogLevel, message: string, detail?: unknown) => void;
+};
+
+type Listener = () => void;
+
+export class MediaRoom {
+  private readonly signal: MediaSignal;
+  private readonly device: MediaDevice;
+  private sendTransport: MediaTransport | undefined;
+  private recvTransport: MediaTransport | 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>();
+  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. */
+  private readonly subscribing = new Map<string, Promise<void>>();
+
+  private stateValue: RoomState = initialRoomState;
+  private connection: ConnectionState = "idle";
+  private lastError: DisconnectCause | undefined;
+
+  /** Consecutive failed attempts since the last successful join. */
+  private reconnectAttempt = 0;
+  private reconnectTimer: ReturnType<typeof setTimeout> | undefined;
+  private recovering = false;
+  /** `close()` has been called. Nothing may open a socket after that. */
+  private disposed = false;
+
+  constructor(private readonly options: MediaRoomOptions) {
+    this.device = options.device();
+    this.signal = new MediaSignal({
+      getCredentials: options.getCredentials,
+      ...(options.webSocket ? { webSocket: options.webSocket } : {}),
+      ...(options.onLog ? { onLog: options.onLog } : {}),
+    });
+
+    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.connection = "reconnecting";
+      this.recovering = this.scheduleReconnect(cause);
+      this.emit();
+    });
+  }
+
+  get state(): RoomState {
+    return this.stateValue;
+  }
+
+  get connectionState(): ConnectionState {
+    return this.connection;
+  }
+
+  get error(): DisconnectCause | undefined {
+    return this.lastError;
+  }
+
+  /**
+   * Is another attempt booked?
+   *
+   * The difference between "wait" and "press something", and the room is the
+   * only side that knows: `connectionState` is `reconnecting` both while a
+   * retry is in flight and after the policy has given up, and a screen that
+   * cannot tell them apart spins forever over a call that is over.
+   */
+  get isRecovering(): boolean {
+    return this.recovering;
+  }
+
+  /** What the NODE says this token may do. For rendering only. */
+  get grants(): MediaGrants | undefined {
+    return this.grantsValue;
+  }
+
+  /**
+   * Snapshots, rebuilt only when something changed.
+   *
+   * These are read by `useSyncExternalStore`, which compares with `Object.is`.
+   * A getter that spread the map on every call would hand it a NEW array every
+   * check, so React would see a change every time and re-render for ever -
+   * "The result of getSnapshot should be cached to avoid an infinite loop".
+   *
+   * The reducer in `core/state.ts` returns the same object when nothing changed
+   * for exactly this reason; these getters have to hold the same property.
+   */
+  private trackSnapshot: MediaTrack[] = [];
+  private publicationSnapshot: LocalPublication[] = [];
+
+  get tracks(): MediaTrack[] {
+    return this.trackSnapshot;
+  }
+
+  get localPublications(): LocalPublication[] {
+    return this.publicationSnapshot;
+  }
+
+  /** Subscribe to changes. Returns an unsubscribe. */
+  onChange(listener: Listener): () => void {
+    this.listeners.add(listener);
+    return () => this.listeners.delete(listener);
+  }
+
+  async connect(): Promise<void> {
+    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
+    // out of it.
+    this.connection = this.reconnectAttempt > 0 ? "reconnecting" : "connecting";
+    this.emit();
+
+    const joined = await this.signal.connect();
+
+    // RULE 1: the device loads first. Everything below needs its capabilities.
+    if (!this.device.loaded) {
+      await this.device.load(joined.routerRtpCapabilities as never);
+    }
+
+    this.iceServers = (joined.iceServers ?? []) as IceServer[];
+    this.grantsValue = joined.grants;
+    this.stateValue = reduceRoomState(this.stateValue, joined);
+    this.connection = "connected";
+    this.lastError = undefined;
+    // A successful join resets the ladder: an hour-long call that drops once
+    // should not start at a 30-second delay because of a blip at minute two.
+    this.reconnectAttempt = 0;
+    this.recovering = false;
+    this.emit();
+
+    if (this.options.autoSubscribe !== false) await this.syncSubscriptions();
+  }
+
+  async close(): Promise<void> {
+    this.disposed = true;
+    this.cancelReconnect();
+    this.recovering = false;
+    this.connection = "closed";
+    await this.signal.leave().catch(() => undefined);
+    this.teardownMedia();
+    this.emit();
+  }
+
+  // -------------------------------------------------------------------------
+  // getting back in
+  // -------------------------------------------------------------------------
+
+  /**
+   * Decide whether to come back, and book the attempt. Returns whether one was.
+   *
+   * The policy is `core/reconnect.ts`'s rather than a second copy of it here:
+   * "a drained node is left alone for the window it named", "a closed room is
+   * never rejoined", "a terminal refusal is not retried" and "jitter or the
+   * whole fleet lands on one replacement node together" each have an outage
+   * behind them, and a restatement is a restatement that drifts.
+   *
+   * The attempt goes through `connect()`, which fetches CREDENTIALS afresh: a
+   * join ticket lives minutes, so the one that opened this call is already
+   * stale, and the node placement has to be resolved again anyway because the
+   * node we just lost is the one node that cannot serve us.
+   */
+  private scheduleReconnect(cause: DisconnectCause): boolean {
+    if (this.disposed) return false;
+
+    const decision = decideReconnect({
+      cause,
+      attempt: this.reconnectAttempt,
+      ...(this.options.reconnect ? { options: this.options.reconnect } : {}),
+    });
+    if (decision.action === "stop") {
+      this.options.onLog?.("warn", `not reconnecting: ${decision.reason}`, cause);
+      return false;
+    }
+
+    this.reconnectTimer = setTimeout(() => {
+      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
+      // unhandled rejection in the host application's console.
+      void this.connect().catch(() => undefined);
+    }, decision.delayMs);
+    return true;
+  }
+
+  private cancelReconnect(): void {
+    if (this.reconnectTimer === undefined) return;
+    clearTimeout(this.reconnectTimer);
+    this.reconnectTimer = undefined;
+  }
+
+  // -------------------------------------------------------------------------
+  // publishing
+  // -------------------------------------------------------------------------
+
+  /**
+   * Publish a track.
+   *
+   * `source` travels in `appData` and is what the node checks against
+   * `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> {
+    const kind = track.kind === "audio" ? "audio" : "video";
+    if (!this.device.canProduce(kind)) {
+      throw new Error(`this browser cannot produce ${kind}`);
+    }
+
+    const transport = await this.ensureSendTransport();
+    const handle = await transport.produce({ track, appData: { source } });
+
+    const publication: LocalPublication = {
+      producerId: handle.id,
+      kind,
+      source,
+      track,
+      handle,
+    };
+    this.publications.set(handle.id, publication);
+    this.emit();
+    return publication;
+  }
+
+  async unpublish(producerId: string): Promise<void> {
+    const publication = this.publications.get(producerId);
+    if (!publication) return;
+
+    publication.handle.close();
+    publication.track.stop();
+    this.publications.delete(producerId);
+    // Told to the node, because closing a local handle stops OUR sending and
+    // leaves the node holding a producer nobody is feeding.
+    await this.signal.request({ method: "closeProducer", producerId }).catch(() => undefined);
+    this.emit();
+  }
+
+  async setPaused(producerId: string, paused: boolean): Promise<void> {
+    const publication = this.publications.get(producerId);
+    if (!publication) return;
+
+    if (paused) publication.handle.pause();
+    else publication.handle.resume();
+    await this.signal
+      .request({ method: paused ? "pauseProducer" : "resumeProducer", producerId })
+      .catch(() => undefined);
+    this.emit();
+  }
+
+  // -------------------------------------------------------------------------
+  // subscribing
+  // -------------------------------------------------------------------------
+
+  /**
+   * Bring subscriptions in line with what the node says we should be receiving.
+   *
+   * RULE 4. The target is the ACTIVE SET, not the producer list: the node
+   * refuses anything outside it, so subscribing to every producer in a large
+   * room produces one refusal per producer and nothing to show.
+   *
+   * Below the threshold the node reports every producer as active, so the two
+   * are the same thing and this needs no special case.
+   */
+  async syncSubscriptions(): Promise<void> {
+    const wanted = new Set(this.stateValue.activeSpeakers);
+
+    for (const [producerId, consumer] of this.consumers) {
+      if (wanted.has(producerId)) continue;
+      // Dropped rather than paused. A consumer the node has moved out of the
+      // active set is one it may refuse to keep feeding, and holding it costs
+      // the node a consumer object for a tile nobody is looking at.
+      consumer.close();
+      this.consumers.delete(producerId);
+      this.tracksByProducer.delete(producerId);
+      await this.signal.request({ method: "closeConsumer", consumerId: consumer.id }).catch(() => undefined);
+    }
+
+    await Promise.all([...wanted].map((producerId) => this.subscribe(producerId)));
+    this.emit();
+  }
+
+  async subscribe(producerId: string): Promise<void> {
+    if (this.consumers.has(producerId)) return;
+    const inFlight = this.subscribing.get(producerId);
+    // Two `activeSpeakers` frames in the same tick would otherwise both pass the
+    // check above and build two consumers for one producer.
+    if (inFlight) return inFlight;
+
+    const work = this.doSubscribe(producerId).finally(() => this.subscribing.delete(producerId));
+    this.subscribing.set(producerId, work);
+    return work;
+  }
+
+  private async doSubscribe(producerId: string): Promise<void> {
+    const entry = this.stateValue.producers.find((p) => p.producerId === producerId);
+    if (!entry) return;
+
+    const transport = await this.ensureRecvTransport();
+    const response = (await this.signal.request({
+      method: "consume",
+      transportId: transport.id,
+      producerId,
+      rtpCapabilities: this.device.rtpCapabilities,
+    })) as { consumerId: string; producerId: string; kind: "audio" | "video"; rtpParameters: RtpParameters };
+
+    const consumer = await transport.consume({
+      id: response.consumerId,
+      producerId: response.producerId,
+      kind: response.kind,
+      rtpParameters: response.rtpParameters,
+    });
+
+    this.consumers.set(producerId, consumer);
+    this.tracksByProducer.set(producerId, {
+      producerId,
+      identity: entry.identity,
+      kind: response.kind,
+      track: consumer.track,
+      paused: entry.paused,
+    });
+
+    // RULE 3: resume LAST. The node creates every consumer paused, so media
+    // arriving before the application has the track is dropped - and for video
+    // that means a black tile until the next keyframe.
+    await this.signal.request({ method: "resumeConsumer", consumerId: consumer.id });
+    consumer.resume();
+    this.emit();
+  }
+
+  // -------------------------------------------------------------------------
+  // transports
+  // -------------------------------------------------------------------------
+
+  /** RULE 2: lazily, and once. */
+  private async ensureSendTransport(): Promise<MediaTransport> {
+    if (this.sendTransport) return this.sendTransport;
+
+    const description = (await this.signal.request({
+      method: "createTransport",
+      direction: "send",
+    })) as TransportDescription;
+
+    this.sendTransport = this.device.createSendTransport({
+      description,
+      iceServers: this.iceServers,
+      handlers: {
+        onConnect: async (dtlsParameters) => {
+          await this.signal.request({ method: "connectTransport", transportId: description.transportId, dtlsParameters });
+        },
+        onProduce: async ({ kind, rtpParameters, appData }) => {
+          const produced = (await this.signal.request({
+            method: "produce",
+            transportId: description.transportId,
+            kind,
+            rtpParameters,
+            ...(appData ? { appData } : {}),
+          })) as { producerId: string };
+          return produced.producerId;
+        },
+      },
+    });
+    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;
+  }
+
+  // -------------------------------------------------------------------------
+  // events
+  // -------------------------------------------------------------------------
+
+  private onFrame(frame: EventFrame): void {
+    const next = reduceRoomState(this.stateValue, frame);
+    const changed = next !== this.stateValue;
+    this.stateValue = next;
+
+    if (frame.event === "joined") this.grantsValue = frame.grants ?? this.grantsValue;
+
+    if (frame.event === "producerClosed") {
+      const consumer = this.consumers.get(frame.producerId);
+      consumer?.close();
+      this.consumers.delete(frame.producerId);
+      this.tracksByProducer.delete(frame.producerId);
+    }
+
+    // The node has changed what we should be receiving. Following it is the
+    // client's whole job in a large room.
+    const followsSet = frame.event === "activeSpeakers" || frame.event === "producerAppeared";
+    if (followsSet && this.options.autoSubscribe !== false && this.connection === "connected") {
+      void this.syncSubscriptions().catch((err) => this.options.onLog?.("warn", "subscription sync failed", err));
+    }
+
+    if (changed) this.emit();
+  }
+
+  /**
+   * Everything the connection was carrying, released.
+   *
+   * The local CAPTURES go with it, and that is the part worth stating. A
+   * publication whose transport has closed sends nothing, but the
+   * `getUserMedia` track behind it is still capturing: the recording indicator
+   * stays lit on the machine and the controls above still read "Mute", claiming
+   * a microphone is publishing into a room that has ended. Leaving them running
+   * is retained personal capture after the session it was consented to was
+   * terminated by the other party, so the room stops them wherever the
+   * connection goes - a leave, a drop, a drain, or the host closing the room -
+   * rather than only on the one path a person happens to take deliberately.
+   *
+   * The node is not told: this runs when the socket is already gone, and the
+   * node tears the session down on close anyway. Ending one publication on a
+   * LIVE connection is `unpublish`, which does tell it.
+   */
+  private teardownMedia(): void {
+    for (const consumer of this.consumers.values()) consumer.close();
+    this.consumers.clear();
+    this.tracksByProducer.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;
+  }
+
+  private emit(): void {
+    // Rebuilt HERE, once per change, rather than per read. Every mutation
+    // already funnels through this, so nothing can change without the snapshot
+    // following it.
+    this.trackSnapshot = [...this.tracksByProducer.values()];
+    this.publicationSnapshot = [...this.publications.values()];
+
+    for (const listener of this.listeners) {
+      try {
+        listener();
+      } catch {
+        // One subscriber throwing must not stop the others from being told.
+      }
+    }
+  }
+}
+
+export async function connectToRoom(options: MediaRoomOptions): Promise<MediaRoom> {
+  const room = new MediaRoom(options);
+  await room.connect();
+  return room;
+}