@tribe-nest/media-client 0.1.0

package/src/core/state.ts

@@ -0,0 +1,251 @@
+import { maySubscribe, type EventFrame, type MediaGrants, type Peer, type SubscribeRule } from "@tribe-nest/media-protocol";
+
+/**
+ * The room as the event frames describe it, as a pure reducer.
+ *
+ * Pure because this is the part that is worth testing exhaustively and the part
+ * a socket makes untestable. Every ordering that matters (a peer leaving before
+ * its producers close, an active-speaker set naming a producer that has just
+ * gone, a rule narrowing mid-call) is a two-line test here and a flaky
+ * integration run anywhere else.
+ *
+ * It holds no tracks, no consumers and no mediasoup objects. Those belong to
+ * P3b's room API, keyed by the `producerId` this state carries.
+ */
+
+export type ProducerEntry = {
+  producerId: string;
+  identity: string;
+  kind: "audio" | "video";
+  paused: boolean;
+};
+
+export type RoomState = {
+  phase: "idle" | "joined" | "closed";
+  /** Our own identity, as the node reported it. */
+  identity: string | null;
+  room: string | null;
+  /** In arrival order, which is the only order the wire gives. */
+  peers: readonly Peer[];
+  /**
+   * EVERY producer the node has announced, whether or not the current
+   * subscribe rule permits it. Visibility is derived by `visibleProducers`;
+   * see the note on `subscribeRuleChanged` for why this is not pruned.
+   */
+  producers: readonly ProducerEntry[];
+  /** The set the NODE decided we should consume, in its order. */
+  activeSpeakers: readonly string[];
+  /** True while any `kind: "egress"` participant is present. A consent flag. */
+  recording: boolean;
+  /** The latest rule pushed for us, if one ever was. */
+  subscribeRule: SubscribeRule | null;
+  /** Set by `draining`, cleared by the next `joined`. */
+  draining: { reconnectAfterMs: number } | null;
+  closedReason: string | null;
+};
+
+export const initialRoomState: RoomState = {
+  phase: "idle",
+  identity: null,
+  room: null,
+  peers: [],
+  producers: [],
+  activeSpeakers: [],
+  recording: false,
+  subscribeRule: null,
+  draining: null,
+  closedReason: null,
+};
+
+/**
+ * Apply one event frame.
+ *
+ * Never throws and never mutates. An event it does not recognise returns the
+ * SAME reference, so a caller can use identity to skip a re-render.
+ */
+export function reduceRoomState(state: RoomState, frame: EventFrame): RoomState {
+  switch (frame.event) {
+    case "joined":
+      // A wholesale replace, not a merge. `joined` also arrives after a
+      // reconnect, and merging would leave peers who left while we were away
+      // on screen for the rest of the call.
+      return {
+        phase: "joined",
+        identity: frame.identity,
+        room: frame.room,
+        peers: frame.peers,
+        producers: frame.producers.map((p) => ({ ...p, paused: false })),
+        activeSpeakers: [],
+        recording: frame.recording,
+        subscribeRule: null,
+        draining: null,
+        closedReason: null,
+      };
+
+    case "peerJoined": {
+      const without = state.peers.filter((p) => p.identity !== frame.peer.identity);
+      return { ...state, peers: [...without, frame.peer] };
+    }
+
+    case "peerLeft": {
+      if (
+        !state.peers.some((p) => p.identity === frame.identity) &&
+        !state.producers.some((p) => p.identity === frame.identity)
+      ) {
+        return state;
+      }
+      // Their producers go with them. A `producerClosed` for each is NOT
+      // guaranteed when a peer's socket simply dies, and a producer left behind
+      // is a tile that never clears.
+      const producers = state.producers.filter((p) => p.identity !== frame.identity);
+      return {
+        ...state,
+        peers: state.peers.filter((p) => p.identity !== frame.identity),
+        producers,
+        activeSpeakers: pruneSpeakers(state.activeSpeakers, producers),
+      };
+    }
+
+    case "producerAppeared": {
+      if (state.producers.some((p) => p.producerId === frame.producerId)) return state;
+      return {
+        ...state,
+        producers: [
+          ...state.producers,
+          { producerId: frame.producerId, identity: frame.identity, kind: frame.kind, paused: false },
+        ],
+      };
+    }
+
+    case "producerClosed": {
+      if (!state.producers.some((p) => p.producerId === frame.producerId)) return state;
+      const producers = state.producers.filter((p) => p.producerId !== frame.producerId);
+      return { ...state, producers, activeSpeakers: pruneSpeakers(state.activeSpeakers, producers) };
+    }
+
+    case "producerPaused": {
+      let changed = false;
+      const producers = state.producers.map((p) => {
+        if (p.producerId !== frame.producerId || p.paused === frame.paused) return p;
+        changed = true;
+        return { ...p, paused: frame.paused };
+      });
+      return changed ? { ...state, producers } : state;
+    }
+
+    case "activeSpeakers":
+      // Stored as sent, INCLUDING ids we have not seen a `producerAppeared` for
+      // yet. The node decides the active set; dropping an id because our view
+      // is a frame behind would silently discard a stream we were told to take.
+      return { ...state, activeSpeakers: frame.producerIds };
+
+    case "recordingChanged":
+      return state.recording === frame.recording ? state : { ...state, recording: frame.recording };
+
+    case "draining":
+      return { ...state, draining: { reconnectAfterMs: frame.reconnectAfterMs } };
+
+    case "roomClosed":
+      // Producers and speakers are gone for good; peers are kept so a caller can
+      // still say who was in the room on the "call ended" screen.
+      return { ...state, phase: "closed", closedReason: frame.reason, producers: [], activeSpeakers: [] };
+
+    case "subscribeRuleChanged":
+      /**
+       * A rule that only applied at join would not apply to anyone already in
+       * the room, which is why the node pushes it.
+       *
+       * The rule is STORED and visibility is DERIVED, never pruned. Filtering
+       * `producers` here loses them permanently: the wire carries any
+       * `SubscribeRule`, `{ mode: "all" }` included, so a node WIDENING a
+       * barrier mid-call could never restore what a narrowing had deleted -
+       * there is no `producerAppeared` replay to bring them back.
+       *
+       * Active speakers are still pruned, because that set is the node's
+       * instruction about what to consume RIGHT NOW rather than a record of
+       * what exists.
+       */
+      return {
+        ...state,
+        subscribeRule: frame.subscribe,
+        activeSpeakers: pruneSpeakers(
+          state.activeSpeakers,
+          visibleUnder(frame.subscribe, state.identity, state.producers),
+        ),
+      };
+
+    default:
+      return state;
+  }
+}
+
+/** Convenience for a caller feeding a stream of frames, e.g. `signal.onAny`. */
+export function reduceRoomStateAll(state: RoomState, frames: readonly EventFrame[]): RoomState {
+  return frames.reduce(reduceRoomState, state);
+}
+
+export function producerById(state: RoomState, producerId: string): ProducerEntry | undefined {
+  return state.producers.find((p) => p.producerId === producerId);
+}
+
+export function producersOf(state: RoomState, identity: string): readonly ProducerEntry[] {
+  return state.producers.filter((p) => p.identity === identity);
+}
+
+/** The active set intersected with what we actually know about, in the node's order. */
+export function activeProducers(state: RoomState): readonly ProducerEntry[] {
+  const entries: ProducerEntry[] = [];
+  for (const id of state.activeSpeakers) {
+    const found = producerById(state, id);
+    if (found) entries.push(found);
+  }
+  return entries;
+}
+
+/** Producers permitted under `rule`. Pure. */
+function visibleUnder(
+  rule: SubscribeRule | null,
+  self: string | null,
+  producers: readonly ProducerEntry[],
+): readonly ProducerEntry[] {
+  if (self === null || rule === null) return producers;
+  return producers.filter((p) => permits(rule, self, p.identity));
+}
+
+/**
+ * What this participant may actually receive.
+ *
+ * Derived rather than stored, so a barrier that narrows and later widens is
+ * reversible. The reducer keeps every producer it has been told about; this is
+ * what a UI should render and what a client should consume from.
+ */
+export function visibleProducers(state: RoomState): readonly ProducerEntry[] {
+  return visibleUnder(state.subscribeRule, state.identity, state.producers);
+}
+
+function pruneSpeakers(speakers: readonly string[], producers: readonly ProducerEntry[]): readonly string[] {
+  const live = new Set(producers.map((p) => p.producerId));
+  const kept = speakers.filter((id) => live.has(id));
+  return kept.length === speakers.length ? speakers : kept;
+}
+
+/**
+ * Asks the CONTRACT's decision function rather than reading the rule here.
+ *
+ * Re-implementing "deny wins, an absent rule means everyone" locally is how the
+ * client and the node end up disagreeing about who is visible, and the client's
+ * version is the one a user sees. The producer half (`visibleTo`) is enforced by
+ * the node from the owner's stored grants and is not knowable here, so this
+ * applies our half only.
+ */
+function permits(rule: SubscribeRule, selfIdentity: string, producerIdentity: string): boolean {
+  if (selfIdentity === producerIdentity) return true;
+  const consumerGrants: MediaGrants = {
+    canPublish: false,
+    canSubscribe: true,
+    canPublishData: false,
+    subscribe: rule,
+  };
+  const ownerGrants: MediaGrants = { canPublish: true, canSubscribe: false, canPublishData: false };
+  return maySubscribe({ consumerIdentity: selfIdentity, consumerGrants, producerIdentity, ownerGrants });
+}

package/src/index.ts

@@ -0,0 +1,54 @@
+import { createBrowserDevice } from "./room/browserDevice";
+import { MediaRoom, type MediaRoomOptions } from "./room/room";
+
+/**
+ * `@tribe-nest/media-client` - the browser SDK.
+ *
+ * This is the entry point that KNOWS about the browser, and the only one that
+ * pulls in `mediasoup-client`. Importing it from a Node process works right up
+ * until a transport is created, which is why the harness, the egress client and
+ * the SIP gateway import `./core` instead.
+ *
+ * Three subpaths, three audiences:
+ *
+ *   `.`          browsers. Room, publish, subscribe, tracks.
+ *   `./react`    the same, as hooks.
+ *   `./core`     anything that is not a browser. No DOM, no mediasoup-client.
+ *   `./protocol` the wire types, for whoever only needs to speak it.
+ */
+
+export * from "./room/room";
+export {
+  type IceServer,
+  type MediaConsumerHandle,
+  type MediaDevice,
+  type MediaDeviceFactory,
+  type MediaProducerHandle,
+  type MediaTransport,
+  type TransportDescription,
+  type TransportHandlers,
+} from "./room/device";
+export { createBrowserDevice } from "./room/browserDevice";
+
+export {
+  type DisconnectCause,
+  type MediaCoreCredentials,
+  type ProducerEntry,
+  type RoomState,
+  type SignalLogLevel,
+} from "./core";
+
+/**
+ * Connect to a room in a browser.
+ *
+ * The device is defaulted HERE rather than inside `room.ts`, so that the room
+ * logic never imports `mediasoup-client` and stays testable without a browser.
+ * Pass `device` explicitly to substitute one.
+ */
+export async function connectToRoom(
+  options: Omit<MediaRoomOptions, "device"> & Partial<Pick<MediaRoomOptions, "device">>,
+): Promise<MediaRoom> {
+  const room = new MediaRoom({ ...options, device: options.device ?? createBrowserDevice });
+  await room.connect();
+  return room;
+}

package/src/protocol.ts

@@ -0,0 +1,9 @@
+/**
+ * `@tribe-nest/media-client/protocol` is a re-export of the frozen contract and
+ * nothing else.
+ *
+ * It exists so an SDK consumer needs one dependency rather than two, and so
+ * there is a visible place that would have to be edited if anyone ever tried to
+ * "extend" a frame locally. Nothing is added here. Ever.
+ */
+export * from "@tribe-nest/media-protocol";