@tribe-nest/media-client 0.1.0

package/src/room/browserDevice.ts

@@ -0,0 +1,114 @@
+import { Device } from "mediasoup-client";
+import type { Transport } from "mediasoup-client/types";
+
+import type {
+  IceServer,
+  MediaConsumerHandle,
+  MediaDevice,
+  MediaProducerHandle,
+  MediaTransport,
+  RtpCapabilities,
+  RtpParameters,
+  TransportDescription,
+  TransportHandlers,
+} from "./device";
+
+/**
+ * The only file in this package that imports `mediasoup-client`.
+ *
+ * Everything above it is written against `MediaDevice`, so the room logic can
+ * be tested without a browser. Keeping that true is what `clientBoundary.spec`
+ * checks, and the reason it matters is that the interesting bugs are in the
+ * ORDER of operations rather than in the library calls: consume before the
+ * device is loaded, resume before the track is attached, rebuild on a reconnect
+ * without tearing the old transport down.
+ *
+ * This file is deliberately dull. If it grows logic, that logic is in the wrong
+ * place.
+ */
+
+const adapt = (transport: Transport): MediaTransport => ({
+  id: transport.id,
+
+  async produce({ track, appData, encodings }) {
+    const producer = await transport.produce({
+      track,
+      ...(encodings ? { encodings: encodings as never } : {}),
+      ...(appData ? { appData } : {}),
+    });
+    return producer as unknown as MediaProducerHandle;
+  },
+
+  async consume({ id, producerId, kind, rtpParameters }) {
+    const consumer = await transport.consume({ id, producerId, kind, rtpParameters });
+    return consumer as unknown as MediaConsumerHandle;
+  },
+
+  close() {
+    transport.close();
+  },
+});
+
+export function createBrowserDevice(): MediaDevice {
+  const device = new Device();
+
+  const common = (description: TransportDescription, iceServers: IceServer[]) => ({
+    // The node calls it `transportId`; mediasoup-client calls it `id`. The
+    // rename happens here and nowhere else.
+    id: description.transportId,
+    iceParameters: description.iceParameters as never,
+    iceCandidates: description.iceCandidates as never,
+    dtlsParameters: description.dtlsParameters as never,
+    ...(description.sctpParameters ? { sctpParameters: description.sctpParameters as never } : {}),
+    // Relay credentials, minted per join. Without these a participant behind a
+    // symmetric NAT never connects, and the symptom is "connecting..." for ever
+    // with nothing naming TURN.
+    ...(iceServers.length ? { iceServers: iceServers as never } : {}),
+  });
+
+  const wire = (transport: Transport, handlers: Partial<TransportHandlers>) => {
+    // `connect` fires once, when the DTLS handshake needs its parameters
+    // delivered to the node. `errback` is not optional: without it a failed
+    // connect leaves the transport waiting rather than failing.
+    transport.on("connect", ({ dtlsParameters }, callback, errback) => {
+      handlers.onConnect?.(dtlsParameters).then(callback, errback);
+    });
+
+    if (handlers.onProduce) {
+      transport.on("produce", ({ kind, rtpParameters, appData }, callback, errback) => {
+        handlers
+          .onProduce?.({ kind, rtpParameters: rtpParameters as RtpParameters, appData: appData as Record<string, unknown> })
+          .then((id) => callback({ id }), errback);
+      });
+    }
+
+    if (handlers.onConnectionStateChange) {
+      transport.on("connectionstatechange", (state) => handlers.onConnectionStateChange?.(state));
+    }
+  };
+
+  return {
+    async load(routerRtpCapabilities: RtpCapabilities) {
+      await device.load({ routerRtpCapabilities: routerRtpCapabilities as never });
+    },
+    get loaded() {
+      return device.loaded;
+    },
+    get rtpCapabilities() {
+      return device.rtpCapabilities as RtpCapabilities;
+    },
+    canProduce(kind) {
+      return device.canProduce(kind);
+    },
+    createSendTransport({ description, iceServers, handlers }) {
+      const transport = device.createSendTransport(common(description, iceServers));
+      wire(transport, handlers);
+      return adapt(transport);
+    },
+    createRecvTransport({ description, iceServers, handlers }) {
+      const transport = device.createRecvTransport(common(description, iceServers));
+      wire(transport, handlers);
+      return adapt(transport);
+    },
+  };
+}

package/src/room/device.ts

@@ -0,0 +1,119 @@
+import type { RtpCapabilities, RtpParameters } from "mediasoup-client/types";
+
+/**
+ * The `mediasoup-client` seam.
+ *
+ * ## Why the room talks to an interface instead of to `mediasoup-client`
+ *
+ * Everything interesting about the room layer - when to create a transport,
+ * what to do when a producer appears, whether a consume is permitted, how a
+ * reconnect rebuilds - is logic, and none of it needs a `RTCPeerConnection`.
+ * `mediasoup-client` needs a browser, so a room that imported it directly could
+ * only ever be tested in one.
+ *
+ * That is not a hypothetical cost. It is the difference between a reducer bug
+ * being caught by `npm test` and being caught by a person on a call.
+ *
+ * So the browser half is this interface, `room.ts` is written against it, and
+ * `browserDevice.ts` is the ~60 lines that actually import the library. The
+ * specs supply a fake; production supplies the real one.
+ *
+ * ## What deliberately is NOT abstracted
+ *
+ * The RTP parameter shapes. Those are `mediasoup-client`'s types re-exported,
+ * because inventing a parallel vocabulary for them would mean translating in
+ * both directions and the translation is where the bugs would live.
+ */
+
+export type { RtpCapabilities, RtpParameters };
+
+/** What the node said when it created a WebRTC transport for us. */
+export type TransportDescription = {
+  transportId: string;
+  iceParameters: unknown;
+  iceCandidates: unknown;
+  dtlsParameters: unknown;
+  sctpParameters?: unknown;
+};
+
+export type IceServer = {
+  urls: string | string[];
+  username?: string;
+  credential?: string;
+};
+
+/**
+ * One direction of media. `send` publishes, `recv` subscribes.
+ *
+ * `onConnect` and `onProduce` are how mediasoup-client asks the application to
+ * talk to the server: the DTLS parameters and the RTP parameters are produced
+ * by the library and have to reach the node over OUR signalling channel.
+ */
+export type TransportHandlers = {
+  onConnect(dtlsParameters: unknown): Promise<void>;
+  /** Must resolve to the node's producer id. */
+  onProduce(input: { kind: "audio" | "video"; rtpParameters: RtpParameters; appData?: Record<string, unknown> }): Promise<string>;
+  onConnectionStateChange?(state: string): void;
+};
+
+export interface MediaTransport {
+  readonly id: string;
+  produce(input: {
+    track: MediaStreamTrack;
+    appData?: Record<string, unknown>;
+    encodings?: unknown[];
+  }): Promise<MediaProducerHandle>;
+  consume(input: {
+    id: string;
+    producerId: string;
+    kind: "audio" | "video";
+    rtpParameters: RtpParameters;
+  }): Promise<MediaConsumerHandle>;
+  close(): void;
+}
+
+export type MediaProducerHandle = {
+  readonly id: string;
+  readonly kind: "audio" | "video";
+  pause(): void;
+  resume(): void;
+  close(): void;
+  readonly closed: boolean;
+};
+
+export type MediaConsumerHandle = {
+  readonly id: string;
+  readonly producerId: string;
+  readonly kind: "audio" | "video";
+  readonly track: MediaStreamTrack;
+  pause(): void;
+  resume(): void;
+  close(): void;
+};
+
+/**
+ * The device: capability negotiation plus transport construction.
+ *
+ * `rtpCapabilities` is what the node needs in order to answer `consume`, and it
+ * is only meaningful AFTER `load`, which is why `load` is separate from
+ * construction rather than folded into it.
+ */
+export interface MediaDevice {
+  load(routerRtpCapabilities: RtpCapabilities): Promise<void>;
+  readonly loaded: boolean;
+  readonly rtpCapabilities: RtpCapabilities;
+  /** False when the browser cannot receive this kind at all. */
+  canProduce(kind: "audio" | "video"): boolean;
+  createSendTransport(input: {
+    description: TransportDescription;
+    iceServers: IceServer[];
+    handlers: TransportHandlers;
+  }): MediaTransport;
+  createRecvTransport(input: {
+    description: TransportDescription;
+    iceServers: IceServer[];
+    handlers: Omit<TransportHandlers, "onProduce">;
+  }): MediaTransport;
+}
+
+export type MediaDeviceFactory = () => MediaDevice;