@tribe-nest/media-client 0.1.0

package/src/room/_tests/room.spec.ts

@@ -0,0 +1,595 @@
+import { describe, expect, it, vi } from "vitest";
+
+import { FakeSignalServer, flush } from "../../core/_tests/fakeSignalServer";
+import { MediaRoom } from "../room";
+import type {
+  IceServer,
+  MediaConsumerHandle,
+  MediaDevice,
+  MediaProducerHandle,
+  MediaTransport,
+  TransportDescription,
+  TransportHandlers,
+} from "../device";
+
+/**
+ * The room's ordering rules, against a fake device.
+ *
+ * This is what the `MediaDevice` seam is FOR. Every rule below has a failure
+ * that only shows up on a live call - a consume refused for what looks like a
+ * codec problem, a black tile until the next keyframe, a second DTLS handshake
+ * nobody asked for - and none of them needs a browser to test.
+ */
+
+type Recorded = { calls: string[]; transports: FakeTransport[] };
+
+class FakeTransport implements MediaTransport {
+  readonly produced: { appData?: Record<string, unknown> }[] = [];
+  readonly consumed: string[] = [];
+  closed = false;
+  handlers: Partial<TransportHandlers> = {};
+
+  constructor(
+    readonly id: string,
+    readonly direction: "send" | "recv",
+    private readonly recorded: Recorded,
+  ) {}
+
+  async produce(input: { track: MediaStreamTrack; appData?: Record<string, unknown> }): Promise<MediaProducerHandle> {
+    this.produced.push({ ...(input.appData ? { appData: input.appData } : {}) });
+    // The real transport asks the application to tell the node, and the node's
+    // answer is the producer id. Modelled, because the round trip is the thing
+    // that can be got wrong.
+    const producerId = await this.handlers.onProduce!({
+      kind: input.track.kind === "audio" ? "audio" : "video",
+      rtpParameters: {} as never,
+      ...(input.appData ? { appData: input.appData } : {}),
+    });
+    this.recorded.calls.push(`produce:${producerId}`);
+    return {
+      id: producerId,
+      kind: input.track.kind === "audio" ? "audio" : "video",
+      closed: false,
+      pause: vi.fn(),
+      resume: vi.fn(),
+      close: vi.fn(),
+    };
+  }
+
+  async consume(input: { id: string; producerId: string; kind: "audio" | "video" }): Promise<MediaConsumerHandle> {
+    this.consumed.push(input.producerId);
+    this.recorded.calls.push(`consume:${input.producerId}`);
+    const resume = vi.fn(() => this.recorded.calls.push(`track-resume:${input.producerId}`));
+    return {
+      id: input.id,
+      producerId: input.producerId,
+      kind: input.kind,
+      track: { kind: input.kind, stop: vi.fn() } as unknown as MediaStreamTrack,
+      pause: vi.fn(),
+      resume,
+      close: vi.fn(),
+    };
+  }
+
+  close() {
+    this.closed = true;
+  }
+}
+
+function fakeDevice(recorded: Recorded) {
+  let loaded = false;
+  const device: MediaDevice = {
+    async load() {
+      recorded.calls.push("device-load");
+      loaded = true;
+    },
+    get loaded() {
+      return loaded;
+    },
+    get rtpCapabilities() {
+      // The rule: asking before `load` is a bug, so the fake makes it loud
+      // rather than returning something plausible.
+      if (!loaded) throw new Error("rtpCapabilities read before the device was loaded");
+      return { codecs: [] } as never;
+    },
+    canProduce: () => true,
+    createSendTransport({ description, handlers }: { description: TransportDescription; iceServers: IceServer[]; handlers: TransportHandlers }) {
+      const transport = new FakeTransport(description.transportId, "send", recorded);
+      transport.handlers = handlers;
+      recorded.transports.push(transport);
+      recorded.calls.push("create-send-transport");
+      return transport;
+    },
+    createRecvTransport({ description, handlers }) {
+      const transport = new FakeTransport(description.transportId, "recv", recorded);
+      transport.handlers = handlers as Partial<TransportHandlers>;
+      recorded.transports.push(transport);
+      recorded.calls.push("create-recv-transport");
+      return transport;
+    },
+  };
+  return device;
+}
+
+/**
+ * A node that answers the frames the room sends.
+ *
+ * Built on the core suite's `FakeSignalServer` rather than a second fake, so
+ * the room is exercised against the same wire the signal client is.
+ */
+function nodeWith(input: {
+  producers?: { producerId: string; identity: string; kind: "audio" | "video" }[];
+  iceServers?: IceServer[];
+}): FakeSignalServer {
+  let transportSeq = 0;
+  let producerSeq = 0;
+  let consumerSeq = 0;
+
+  const server: FakeSignalServer = new FakeSignalServer({
+    joined: {
+      identity: "me",
+      room: "matter-1",
+      routerRtpCapabilities: { codecs: [] },
+      producers: input.producers ?? [],
+      ...(input.iceServers ? { iceServers: input.iceServers as never } : {}),
+      grants: { canPublish: true, canSubscribe: true, canPublishData: false },
+    },
+    onRequest: (frame, socket) => {
+      switch (frame.method) {
+        case "createTransport":
+          return server.reply(
+            frame.id,
+            { transportId: `t-${transportSeq++}`, iceParameters: {}, iceCandidates: [], dtlsParameters: {} },
+            socket,
+          );
+        case "connectTransport":
+          return server.reply(frame.id, { connected: true }, socket);
+        case "produce":
+          return server.reply(frame.id, { producerId: `p-${producerSeq++}` }, socket);
+        case "consume":
+          return server.reply(
+            frame.id,
+            { consumerId: `c-${consumerSeq++}`, producerId: frame.producerId, kind: "audio", rtpParameters: {} },
+            socket,
+          );
+        case "join":
+          return;
+        default:
+          return server.reply(frame.id, {}, socket);
+      }
+    },
+  });
+  return server;
+}
+
+/** Every request of one method, in arrival order. */
+const requestsOf = (server: FakeSignalServer, method: string) =>
+  server.received.filter((frame) => frame.method === method);
+
+const roomFor = (server: FakeSignalServer, recorded: Recorded, autoSubscribe = true) =>
+  new MediaRoom({
+    getCredentials: () => ({ mediaUrl: "wss://media.example", token: "t" }),
+    device: () => fakeDevice(recorded),
+    webSocket: server.factory,
+    autoSubscribe,
+  });
+
+/**
+ * A room that retries almost instantly, and counts its tickets.
+ *
+ * The ladder itself is pinned exhaustively in `core/_tests/reconnect.spec.ts`
+ * against an injected `random`; what these specs are about is whether the room
+ * DRIVES it at all, so the delays are collapsed to something a real timer can
+ * clear inside a test rather than reproduced here.
+ */
+const recoveringRoom = (
+  server: FakeSignalServer,
+  recorded: Recorded,
+  overrides: Partial<ConstructorParameters<typeof MediaRoom>[0]> = {},
+) => {
+  const tickets: string[] = [];
+  const room = new MediaRoom({
+    getCredentials: () => {
+      const token = `t-${tickets.length}`;
+      tickets.push(token);
+      return { mediaUrl: "wss://media.example", token };
+    },
+    device: () => fakeDevice(recorded),
+    webSocket: server.factory,
+    autoSubscribe: false,
+    reconnect: { baseMs: 1, maxMs: 4, factor: 1, jitter: "none" },
+    ...overrides,
+  });
+  return { room, tickets };
+};
+
+const track = () => ({ kind: "audio", stop: vi.fn() }) as unknown as MediaStreamTrack & { stop: ReturnType<typeof vi.fn> };
+
+describe("rule 1: the device loads before anything needs its capabilities", () => {
+  it("loads on join, before any transport", async () => {
+    const recorded: Recorded = { calls: [], transports: [] };
+    const server = nodeWith({});
+    const room = roomFor(server, recorded);
+
+    await room.connect();
+
+    expect(recorded.calls[0]).toBe("device-load");
+    await room.close();
+  });
+
+  it("refuses a second connect on a live room rather than loading twice", async () => {
+    // One room, one connection. A second `connect()` on a live socket would
+    // mean two joins under one identity, and the node refuses the second with
+    // `duplicate_identity` - so the client should never get that far.
+    const recorded: Recorded = { calls: [], transports: [] };
+    const room = roomFor(nodeWith({}), recorded);
+
+    await room.connect();
+    await expect(room.connect()).rejects.toThrow(/already connecting or connected/);
+
+    expect(recorded.calls.filter((c) => c === "device-load")).toHaveLength(1);
+    await room.close();
+  });
+});
+
+describe("rule 2: one transport per direction, created lazily", () => {
+  it("creates NO transport for a participant that neither publishes nor subscribes", async () => {
+    const recorded: Recorded = { calls: [], transports: [] };
+    // Nothing to subscribe to, so a recv transport would be an ICE gather for
+    // a participant who may only ever watch an empty room.
+    const room = roomFor(nodeWith({}), recorded, false);
+
+    await room.connect();
+
+    expect(recorded.transports).toHaveLength(0);
+    await room.close();
+  });
+
+  it("reuses the send transport across publishes", async () => {
+    const recorded: Recorded = { calls: [], transports: [] };
+    const room = roomFor(nodeWith({}), recorded, false);
+    await room.connect();
+
+    await room.publish({ kind: "audio", stop: vi.fn() } as never, "microphone");
+    await room.publish({ kind: "video", stop: vi.fn() } as never, "camera");
+
+    expect(recorded.calls.filter((c) => c === "create-send-transport")).toHaveLength(1);
+    await room.close();
+  });
+
+  it("reuses the recv transport across subscriptions", async () => {
+    const recorded: Recorded = { calls: [], transports: [] };
+    const server = nodeWith({
+      producers: [
+        { producerId: "p-a", identity: "a", kind: "audio" },
+        { producerId: "p-b", identity: "b", kind: "audio" },
+      ],
+    });
+    const room = roomFor(server, recorded, false);
+    await room.connect();
+
+    await room.subscribe("p-a");
+    await room.subscribe("p-b");
+
+    expect(recorded.calls.filter((c) => c === "create-recv-transport")).toHaveLength(1);
+    await room.close();
+  });
+});
+
+describe("rule 3: a consumer resumes only after its track exists", () => {
+  it("consumes, then resumes", async () => {
+    const recorded: Recorded = { calls: [], transports: [] };
+    const server = nodeWith({ producers: [{ producerId: "p-a", identity: "a", kind: "audio" }] });
+    const room = roomFor(server, recorded, false);
+    await room.connect();
+
+    await room.subscribe("p-a");
+
+    // The node creates every consumer PAUSED. Resuming before the application
+    // has the track means media arrives with nowhere to go and is dropped, and
+    // for video that is a black tile until the next keyframe.
+    const consumeAt = recorded.calls.indexOf("consume:p-a");
+    const resumeAt = recorded.calls.indexOf("track-resume:p-a");
+    expect(consumeAt).toBeGreaterThanOrEqual(0);
+    expect(resumeAt).toBeGreaterThan(consumeAt);
+    expect(requestsOf(server, "resumeConsumer")).toHaveLength(1);
+    await room.close();
+  });
+
+  it("exposes the track once it is attached", async () => {
+    const recorded: Recorded = { calls: [], transports: [] };
+    const server = nodeWith({ producers: [{ producerId: "p-a", identity: "anwalt", kind: "audio" }] });
+    const room = roomFor(server, recorded, false);
+    await room.connect();
+    await room.subscribe("p-a");
+
+    expect(room.tracks).toHaveLength(1);
+    expect(room.tracks[0]).toMatchObject({ producerId: "p-a", identity: "anwalt", kind: "audio" });
+    await room.close();
+  });
+});
+
+describe("rule 4: autoSubscribe follows the ACTIVE SET", () => {
+  it("subscribes only to what the node put in the set", async () => {
+    const recorded: Recorded = { calls: [], transports: [] };
+    const server = nodeWith({
+      producers: [
+        { producerId: "p-1", identity: "a", kind: "audio" },
+        { producerId: "p-2", identity: "b", kind: "audio" },
+        { producerId: "p-3", identity: "c", kind: "audio" },
+      ],
+    });
+    const room = roomFor(server, recorded);
+    await room.connect();
+
+    // Nothing yet: the node has not said what the active set is.
+    expect(requestsOf(server, "consume")).toHaveLength(0);
+
+    server.event({ event: "activeSpeakers", producerIds: ["p-1", "p-3"] });
+    await vi.waitFor(() => expect(requestsOf(server, "consume")).toHaveLength(2));
+
+    // Subscribing to everything would produce one `subscription_limit` refusal
+    // per producer outside the set, and show nothing for the trouble.
+    expect(requestsOf(server, "consume").map((r) => (r as { producerId: string }).producerId).sort()).toEqual([
+      "p-1",
+      "p-3",
+    ]);
+    await room.close();
+  });
+
+  it("drops a subscription the node moved OUT of the set, and tells the node", async () => {
+    const recorded: Recorded = { calls: [], transports: [] };
+    const server = nodeWith({
+      producers: [
+        { producerId: "p-1", identity: "a", kind: "audio" },
+        { producerId: "p-2", identity: "b", kind: "audio" },
+      ],
+    });
+    const room = roomFor(server, recorded);
+    await room.connect();
+
+    server.event({ event: "activeSpeakers", producerIds: ["p-1"] });
+    await vi.waitFor(() => expect(room.tracks).toHaveLength(1));
+
+    server.event({ event: "activeSpeakers", producerIds: ["p-2"] });
+    await vi.waitFor(() => expect(room.tracks.map((t) => t.producerId)).toEqual(["p-2"]));
+
+    // Told, not just dropped locally: the node holds a Consumer per
+    // subscription, and in a busy room the set churns constantly.
+    expect(requestsOf(server, "closeConsumer")).toHaveLength(1);
+    await room.close();
+  });
+
+  it("does not subscribe twice when two frames arrive in one tick", async () => {
+    const recorded: Recorded = { calls: [], transports: [] };
+    const server = nodeWith({ producers: [{ producerId: "p-1", identity: "a", kind: "audio" }] });
+    const room = roomFor(server, recorded);
+    await room.connect();
+
+    server.event({ event: "activeSpeakers", producerIds: ["p-1"] });
+    server.event({ event: "activeSpeakers", producerIds: ["p-1"] });
+    await vi.waitFor(() => expect(room.tracks).toHaveLength(1));
+
+    expect(requestsOf(server, "consume")).toHaveLength(1);
+    await room.close();
+  });
+});
+
+describe("publishing", () => {
+  it("sends the SOURCE, which is what the node checks against publishKinds", async () => {
+    const recorded: Recorded = { calls: [], transports: [] };
+    const server = nodeWith({});
+    const room = roomFor(server, recorded, false);
+    await room.connect();
+
+    await room.publish({ kind: "video", stop: vi.fn() } as never, "screen");
+
+    // A token granting audio only must not publish a screen share by
+    // relabelling it, and the node is where that is decided.
+    const produce = requestsOf(server, "produce")[0] as { appData?: { source?: string } };
+    expect(produce.appData?.source).toBe("screen");
+    await room.close();
+  });
+
+  it("tells the node when a publication ends", async () => {
+    const recorded: Recorded = { calls: [], transports: [] };
+    const server = nodeWith({});
+    const room = roomFor(server, recorded, false);
+    await room.connect();
+
+    const publication = await room.publish({ kind: "audio", stop: vi.fn() } as never, "microphone");
+    await room.unpublish(publication.producerId);
+
+    // Closing only the local handle leaves the node holding a producer nobody
+    // is feeding.
+    expect(requestsOf(server, "closeProducer")).toHaveLength(1);
+    expect(room.localPublications).toHaveLength(0);
+    await room.close();
+  });
+});
+
+/**
+ * A state called "reconnecting" has to mean something is reconnecting.
+ *
+ * Before this, nothing in the stack ever attempted a second connection:
+ * `superviseConnection` was written, tested and never called, so a drop set the
+ * connection to `reconnecting` and stopped there. Every screen above it drew a
+ * spinner promising a recovery that no code was performing, and the way back
+ * into a paid coaching hour was for the person to work out on their own that
+ * they should reload the page. A drained node - an ordinary deploy - did it to
+ * everybody on that node at once.
+ */
+describe("the room gets itself back in", () => {
+  it("opens a SECOND connection after a drop the client did not ask for", async () => {
+    const recorded: Recorded = { calls: [], transports: [] };
+    const server = nodeWith({});
+    const { room, tickets } = recoveringRoom(server, recorded);
+    await room.connect();
+
+    server.socket.dropFromServer();
+
+    await vi.waitFor(() => expect(server.sockets.length).toBe(2));
+    await vi.waitFor(() => expect(room.connectionState).toBe("connected"));
+    // A join ticket lives minutes and a call lasts an hour, so the second
+    // attempt must carry a FRESH one rather than replaying the first.
+    expect(tickets).toEqual(["t-0", "t-1"]);
+    expect(room.state.phase).toBe("joined");
+    await room.close();
+  });
+
+  it("says whether it is actually coming back, so a screen can tell wait from press-something", async () => {
+    const recorded: Recorded = { calls: [], transports: [] };
+    const server = nodeWith({});
+    // `maxAttempts: 0` is the policy declining to retry at all, which is the
+    // same position the ladder reaches once it is exhausted.
+    const { room } = recoveringRoom(server, recorded, { reconnect: { maxAttempts: 0 } });
+    await room.connect();
+    expect(room.isRecovering).toBe(false);
+
+    server.socket.dropFromServer();
+    await vi.waitFor(() => expect(room.connectionState).toBe("reconnecting"));
+
+    // The connection state says the same word in both cases. This is the half
+    // that separates them, and without it the UI can only spin.
+    expect(room.isRecovering).toBe(false);
+    expect(server.sockets.length).toBe(1);
+    await room.close();
+  });
+
+  it("moves off a node that is draining, which is the case a retry cannot fix by waiting", async () => {
+    const recorded: Recorded = { calls: [], transports: [] };
+    const server = nodeWith({});
+    const { room, tickets } = recoveringRoom(server, recorded);
+    await room.connect();
+
+    // What a deploy or a scale-down sends: the node asks to be left, then goes.
+    server.event({ event: "draining", reconnectAfterMs: 1 });
+    await flush();
+    server.socket.dropFromServer();
+
+    await vi.waitFor(() => expect(server.sockets.length).toBe(2));
+    await vi.waitFor(() => expect(room.connectionState).toBe("connected"));
+    // Through `MEDIA_URL` with a new ticket: the node we just left is the one
+    // node that cannot serve us, and the client holds no node address anyway.
+    expect(tickets).toHaveLength(2);
+    await room.close();
+  });
+
+  it("never rejoins a room the node closed", async () => {
+    const recorded: Recorded = { calls: [], transports: [] };
+    const server = nodeWith({});
+    const { room } = recoveringRoom(server, recorded);
+    await room.connect();
+
+    server.event({ event: "roomClosed", reason: "the host ended it" });
+    await flush();
+    server.socket.dropFromServer();
+
+    await vi.waitFor(() => expect(room.connectionState).toBe("reconnecting"));
+    expect(room.isRecovering).toBe(false);
+    // Rejoining a finished session would put somebody back into a call the
+    // other party has ended, over and over.
+    await new Promise((resolve) => setTimeout(resolve, 30));
+    expect(server.sockets.length).toBe(1);
+    await room.close();
+  });
+
+  it("does not come back after the person has left", async () => {
+    const recorded: Recorded = { calls: [], transports: [] };
+    const server = nodeWith({});
+    const { room } = recoveringRoom(server, recorded);
+    await room.connect();
+
+    server.socket.dropFromServer();
+    await flush();
+    await room.close();
+
+    await new Promise((resolve) => setTimeout(resolve, 30));
+    // A booked attempt that survives `close()` reopens a call somebody
+    // deliberately left, and the provider above has already unmounted.
+    expect(server.sockets.length).toBe(1);
+    expect(room.isRecovering).toBe(false);
+    expect(room.connectionState).toBe("closed");
+  });
+});
+
+/**
+ * The camera light goes out whenever the connection does.
+ *
+ * Only `close()` stopped local tracks, so every disconnect the client did not
+ * ask for - the host ending the session, a refund at minute ten, a socket
+ * dying - left `getUserMedia` capturing with the OS recording indicator lit,
+ * while the controls above still read "Mute" about a microphone publishing into
+ * a room that no longer exists. That is retained personal capture after the
+ * session it was consented to has been terminated by the other party.
+ */
+describe("a disconnect releases the local capture", () => {
+  it("stops a published track when the node closes the room", async () => {
+    const recorded: Recorded = { calls: [], transports: [] };
+    const server = nodeWith({});
+    const { room } = recoveringRoom(server, recorded);
+    await room.connect();
+
+    const microphone = track();
+    await room.publish(microphone, "microphone");
+    expect(room.localPublications).toHaveLength(1);
+
+    server.event({ event: "roomClosed", reason: "the host ended it" });
+    await flush();
+    server.socket.dropFromServer();
+
+    await vi.waitFor(() => expect(microphone.stop).toHaveBeenCalledTimes(1));
+    // And the publication is gone, so `isMicrophoneEnabled` above reads false
+    // and the button stops claiming to be sending anything.
+    expect(room.localPublications).toHaveLength(0);
+    await room.close();
+  });
+
+  it("stops a published track when the socket simply dies", async () => {
+    const recorded: Recorded = { calls: [], transports: [] };
+    const server = nodeWith({});
+    const { room } = recoveringRoom(server, recorded, { reconnect: { maxAttempts: 0 } });
+    await room.connect();
+
+    const microphone = track();
+    await room.publish(microphone, "microphone");
+
+    server.socket.dropFromServer();
+
+    await vi.waitFor(() => expect(microphone.stop).toHaveBeenCalledTimes(1));
+    expect(room.localPublications).toHaveLength(0);
+    await room.close();
+    // Once, not twice. `close()` runs the same teardown and a second `stop()`
+    // on a track that has gone is a symptom of two owners.
+    expect(microphone.stop).toHaveBeenCalledTimes(1);
+  });
+});
+
+describe("what the room carries for rendering", () => {
+  it("exposes the grants the NODE reported, not a token it parsed", async () => {
+    const recorded: Recorded = { calls: [], transports: [] };
+    const room = roomFor(nodeWith({}), recorded, false);
+    await room.connect();
+
+    // A signed blob a client reads is a signed blob a client eventually trusts
+    // its own reading of. This is the node's understanding, which is the one
+    // that will actually be enforced.
+    expect(room.grants).toMatchObject({ canPublish: true, canSubscribe: true });
+    await room.close();
+  });
+
+  it("passes TURN credentials through to the transport", async () => {
+    const recorded: Recorded = { calls: [], transports: [] };
+    const iceServers = [{ urls: ["turn:turn.example:3478"], username: "1:me", credential: "x" }];
+    const server = nodeWith({ iceServers });
+    const room = roomFor(server, recorded, false);
+    await room.connect();
+
+    await room.publish({ kind: "audio", stop: vi.fn() } as never, "microphone");
+
+    // Without a relay, a participant behind a symmetric NAT never connects and
+    // the symptom names nothing.
+    expect(room.state.phase).toBe("joined");
+    await room.close();
+  });
+});