@tribe-nest/forge 3.37.0 → 3.39.0

package/src/ui/styled/_tests/broadcastStage.spec.ts

@@ -0,0 +1,316 @@
+import { describe, expect, it } from "vitest";
+
+import type { ConnectionState, DisconnectCause, ProducerEntry } from "@tribe-nest/media-client";
+
+import {
+  broadcastFellBack,
+  chooseBroadcastStage,
+  programTracks,
+  type BroadcastRoomState,
+  type BroadcastStageInput,
+} from "../broadcast/broadcastStage";
+
+/**
+ * Which stage a live broadcast plays on, and how a viewer gets back to a
+ * picture when the good one is not available.
+ *
+ * Tested as PURE FUNCTIONS rather than by rendering. The realtime stage is a
+ * mediasoup transport over a WebSocket, and standing that up in jsdom tests the
+ * mock rather than the rule: the mock would answer whatever the test wanted, and
+ * the thing worth being sure about here is the RULE, which is four independent
+ * signals arriving at four different times and every combination of them
+ * resolving to a viewer who can see the broadcast.
+ *
+ * The table below is written out combination by combination on purpose. The
+ * failure this guards against is not a wrong answer to one question, it is a
+ * gap: a state nobody thought about that falls through to `realtime` and leaves
+ * somebody looking at a black rectangle while the show goes on without them.
+ */
+
+const HLS_ONLY: BroadcastStageInput = {
+  realtimeAvailable: false,
+  credentialsReady: false,
+  credentialsError: null,
+};
+
+/** A viewer who is on the plane, connected, with a live room. */
+const CONNECTED: BroadcastStageInput = {
+  realtimeAvailable: true,
+  credentialsReady: true,
+  credentialsError: null,
+  roomState: { connectionState: "connected", phase: "joined", recovering: false },
+};
+
+const room = (overrides: Partial<BroadcastRoomState> = {}): BroadcastRoomState => ({
+  connectionState: "connected",
+  phase: "joined",
+  recovering: false,
+  ...overrides,
+});
+
+const on = (roomState: BroadcastRoomState): BroadcastStageInput => ({ ...CONNECTED, roomState });
+
+describe("chooseBroadcastStage: what the broadcast offers", () => {
+  it("plays HLS when the broadcast does not advertise realtime at all", () => {
+    expect(chooseBroadcastStage(HLS_ONLY)).toBe("hls");
+  });
+
+  it("REGRESSION: does not take the plane on the flag alone, before a ticket exists", () => {
+    // `realtime.available` says the room is open, never that THIS viewer got in:
+    // the cap is enforced by the token endpoint and nothing else knows how full
+    // the room is. Mounting on the flag would put the five-hundred-and-first
+    // viewer on a stage that is never going to connect.
+    //
+    // It waits rather than falling to HLS, which is the second half of the
+    // same rule: answering "hls" here mounted an HLS engine for the moment the
+    // ticket was in flight, and that engine starts fetching segments as soon
+    // as it exists, so a realtime viewer downloaded the whole broadcast a
+    // second time for a stage about to be thrown away.
+    expect(chooseBroadcastStage({ realtimeAvailable: true, credentialsReady: false, credentialsError: null })).toBe(
+      "pending",
+    );
+  });
+
+  it("never waits on a broadcast that does not offer realtime", () => {
+    // `pending` is only ever reachable when there is something to wait FOR.
+    // An ordinary broadcast must reach its player on the first render.
+    expect(chooseBroadcastStage({ realtimeAvailable: false, credentialsReady: false, credentialsError: null })).toBe(
+      "hls",
+    );
+  });
+
+  it("takes the plane once the flag and a minted ticket agree", () => {
+    expect(chooseBroadcastStage({ realtimeAvailable: true, credentialsReady: true, credentialsError: null })).toBe(
+      "realtime",
+    );
+  });
+
+  it("stays on HLS when the flag is off even if a ticket somehow exists", () => {
+    expect(chooseBroadcastStage({ realtimeAvailable: false, credentialsReady: true, credentialsError: null })).toBe(
+      "hls",
+    );
+  });
+});
+
+describe("chooseBroadcastStage: the token endpoint said no", () => {
+  /**
+   * 409 is the designed refusal (room full, realtime off, nothing live) and it
+   * is deliberately not privileged over the others. A viewer refused for any
+   * reason watches the same stream, so a rule that treated one status specially
+   * would be a branch with no behaviour behind it and one more place to be
+   * wrong.
+   */
+  const REFUSALS = [
+    { name: "409, the room is full", error: { status: 409, message: "room is full" } },
+    { name: "409, realtime is switched off", error: { status: 409 } },
+    { name: "401, the pass was not accepted", error: { status: 401 } },
+    { name: "404, no live room for this broadcast", error: { status: 404 } },
+    { name: "500, the server fell over", error: { status: 500 } },
+    { name: "a network failure with no status at all", error: {} },
+  ];
+
+  for (const refusal of REFUSALS) {
+    it(`falls back on ${refusal.name}`, () => {
+      const input: BroadcastStageInput = { ...CONNECTED, credentialsError: refusal.error };
+      expect(chooseBroadcastStage(input)).toBe("hls");
+      expect(broadcastFellBack(input)).toBe(true);
+    });
+  }
+
+  it("REGRESSION: a refusal outranks a ticket that was already minted", () => {
+    // This is the RECONNECT case. The probe succeeded, the viewer watched, and
+    // the ticket minted for the next attempt was refused because the room
+    // filled up or ended while they were in it. Reading `credentialsReady`
+    // first would keep them on a room they can no longer enter.
+    const input: BroadcastStageInput = { ...CONNECTED, credentialsError: { status: 409 } };
+    expect(chooseBroadcastStage(input)).toBe("hls");
+  });
+});
+
+describe("chooseBroadcastStage: what the SDK is doing", () => {
+  it("stays on the plane while the first connection is still in flight", () => {
+    expect(chooseBroadcastStage(on(room({ connectionState: "idle", phase: "idle" })))).toBe("realtime");
+    expect(chooseBroadcastStage(on(room({ connectionState: "connecting", phase: "idle" })))).toBe("realtime");
+  });
+
+  it("stays on the plane while the SDK is genuinely coming back", () => {
+    // A blink. Tearing the room down to swap in an HLS player would turn a
+    // second of held frame into a restart, and the SDK reconnects on its own.
+    const input = on(room({ connectionState: "reconnecting", recovering: true }));
+    expect(chooseBroadcastStage(input)).toBe("realtime");
+    expect(broadcastFellBack(input)).toBe(false);
+  });
+
+  it("REGRESSION: falls back once the reconnect policy has given up", () => {
+    // `connectionState` is `reconnecting` both while an attempt is booked and
+    // after the SDK has stopped booking them. Reading it without `recovering`
+    // leaves a viewer on a frozen frame for the rest of the broadcast.
+    const input = on(room({ connectionState: "reconnecting", recovering: false }));
+    expect(chooseBroadcastStage(input)).toBe("hls");
+    expect(broadcastFellBack(input)).toBe(true);
+  });
+
+  it("stays on the plane while the node is moving this viewer to another one", () => {
+    const draining: DisconnectCause = { type: "draining", reconnectAfterMs: 500 };
+    expect(chooseBroadcastStage(on(room({ connectionState: "reconnecting", recovering: true, error: draining })))).toBe(
+      "realtime",
+    );
+  });
+
+  it("falls back when a drain is NOT being recovered from", () => {
+    const draining: DisconnectCause = { type: "draining", reconnectAfterMs: 500 };
+    const input = on(room({ connectionState: "reconnecting", recovering: false, error: draining }));
+    expect(chooseBroadcastStage(input)).toBe("hls");
+    expect(broadcastFellBack(input)).toBe(true);
+  });
+
+  it("falls back when the node refuses the token, however hopeful the SDK is", () => {
+    // A refusal is not a network problem and retrying it changes nothing, so
+    // `recovering` does not rescue it.
+    const refused: DisconnectCause = { type: "refused", code: "capacity", message: "room is full" };
+    const input = on(room({ connectionState: "reconnecting", recovering: true, error: refused }));
+    expect(chooseBroadcastStage(input)).toBe("hls");
+    expect(broadcastFellBack(input)).toBe(true);
+  });
+
+  it("falls back when the room closes under a socket that is still open", () => {
+    // The broadcast ended. `connectionState` is still `connected` for as long
+    // as it takes the node to hang up, so reading only the connection would
+    // hold a viewer on a room that has finished.
+    const input = on(room({ connectionState: "connected", phase: "closed" }));
+    expect(chooseBroadcastStage(input)).toBe("hls");
+    expect(broadcastFellBack(input)).toBe(true);
+  });
+
+  it("falls back when the room close arrives as a disconnect cause", () => {
+    const closed: DisconnectCause = { type: "room_closed", reason: "broadcast ended" };
+    const input = on(room({ connectionState: "reconnecting", recovering: true, error: closed }));
+    expect(chooseBroadcastStage(input)).toBe("hls");
+  });
+
+  it("falls back when the connection is closed for good", () => {
+    const input = on(room({ connectionState: "closed" }));
+    expect(chooseBroadcastStage(input)).toBe("hls");
+    expect(broadcastFellBack(input)).toBe(true);
+  });
+
+  it("covers every connection state the SDK can report", () => {
+    // A state added to the SDK and forgotten here is the gap this guards: the
+    // list is exhaustive by construction, so a new one breaks the type rather
+    // than falling through to `realtime` unnoticed.
+    const expected: Record<ConnectionState, "realtime" | "hls"> = {
+      idle: "realtime",
+      connecting: "realtime",
+      connected: "realtime",
+      // With nothing booked. The recovering half is asserted above.
+      reconnecting: "hls",
+      closed: "hls",
+    };
+
+    for (const [connectionState, stage] of Object.entries(expected)) {
+      expect(chooseBroadcastStage(on(room({ connectionState: connectionState as ConnectionState })))).toBe(stage);
+    }
+  });
+});
+
+describe("broadcastFellBack: what the viewer is told", () => {
+  it("says nothing on a broadcast that never offered realtime", () => {
+    // Most broadcasts. A line saying "watching the standard stream" on every
+    // ordinary stream teaches viewers to ignore the one time it matters.
+    expect(broadcastFellBack(HLS_ONLY)).toBe(false);
+  });
+
+  it("says nothing while the ticket is still in flight", () => {
+    // It resolves in a moment. Announcing a fallback that is about to be
+    // withdrawn is a line that flickers on every single page load.
+    expect(broadcastFellBack({ realtimeAvailable: true, credentialsReady: false, credentialsError: null })).toBe(false);
+  });
+
+  it("says nothing while the viewer is actually on the plane", () => {
+    expect(broadcastFellBack(CONNECTED)).toBe(false);
+  });
+
+  it("never claims a fallback the stage did not actually make", () => {
+    // The two functions have to agree, because the line explains the stage. A
+    // notice over a realtime stage is nonsense, and a silent fallback is a
+    // viewer wondering why the chat is ahead of the picture.
+    const cases: BroadcastStageInput[] = [
+      HLS_ONLY,
+      CONNECTED,
+      { realtimeAvailable: true, credentialsReady: false, credentialsError: null },
+      { ...CONNECTED, credentialsError: { status: 409 } },
+      on(room({ connectionState: "reconnecting", recovering: false })),
+      on(room({ connectionState: "reconnecting", recovering: true })),
+      on(room({ phase: "closed" })),
+      on(room({ connectionState: "closed" })),
+    ];
+
+    for (const input of cases) {
+      if (broadcastFellBack(input)) expect(chooseBroadcastStage(input)).toBe("hls");
+    }
+  });
+});
+
+describe("programTracks", () => {
+  const producer = (overrides: Partial<ProducerEntry> & Pick<ProducerEntry, "producerId" | "kind">): ProducerEntry => ({
+    identity: "program:b1",
+    paused: false,
+    ...overrides,
+  });
+
+  it("finds nothing before the node has announced anything", () => {
+    expect(programTracks([])).toEqual({ videoPaused: false, audioProducerIds: [] });
+  });
+
+  it("pairs the program's video with its audio", () => {
+    const tracks = programTracks([
+      producer({ producerId: "v1", kind: "video" }),
+      producer({ producerId: "a1", kind: "audio" }),
+    ]);
+    expect(tracks.videoProducerId).toBe("v1");
+    expect(tracks.audioProducerIds).toEqual(["a1"]);
+  });
+
+  it("REGRESSION: does not lose the audio when the video arrives second", () => {
+    // `producerAppeared` frames have no ordering guarantee, so a rule that
+    // depended on the video being first would produce a silent broadcast for
+    // whichever half of viewers got the frames the other way round.
+    const tracks = programTracks([
+      producer({ producerId: "a1", kind: "audio" }),
+      producer({ producerId: "v1", kind: "video" }),
+    ]);
+    expect(tracks.videoProducerId).toBe("v1");
+    expect(tracks.audioProducerIds).toEqual(["a1"]);
+  });
+
+  it("keeps the FIRST video when a republish briefly announces two", () => {
+    // Picking the newer one would swap the element's stream under a viewer
+    // mid-sentence, for a producer that is about to disappear again.
+    const tracks = programTracks([
+      producer({ producerId: "v1", kind: "video" }),
+      producer({ producerId: "v2", kind: "video" }),
+    ]);
+    expect(tracks.videoProducerId).toBe("v1");
+  });
+
+  it("reports a video the publisher paused at source rather than hiding it", () => {
+    const tracks = programTracks([producer({ producerId: "v1", kind: "video", paused: true })]);
+    expect(tracks.videoProducerId).toBe("v1");
+    expect(tracks.videoPaused).toBe(true);
+  });
+
+  it("plays ONE soundtrack when the room briefly holds two audio producers", () => {
+    // A guard rather than a fix for anything observed: a republish after a
+    // reconnect can overlap the old producer's teardown, and two soundtracks
+    // is never the right answer, so the newer publication wins.
+    //
+    // The doubled audio that was actually reported came from the player
+    // mounting the HLS stage while the ticket was in flight, which is pinned
+    // by the `pending` cases above.
+    const tracks = programTracks([
+      producer({ producerId: "a1", kind: "audio" }),
+      producer({ producerId: "a2", kind: "audio" }),
+    ]);
+    expect(tracks.audioProducerIds).toEqual(["a2"]);
+  });
+});

package/src/ui/styled/_tests/uiEntryServerSafety.spec.ts

@@ -0,0 +1,127 @@
+import { describe, expect, it } from "vitest";
+import { existsSync, readFileSync, statSync } from "fs";
+import { dirname, join, relative } from "path";
+
+/**
+ * Nothing on the `./ui` entry's module graph may pull in the media SDK.
+ *
+ * Forge renders inside TanStack Start on Cloudflare Workers, and `./ui` is the
+ * entry EVERY site loads on EVERY page, server side included.
+ * `@tribe-nest/media-client` (through `mediasoup-client`) touches
+ * `RTCPeerConnection` at module scope and does not exist on a server, so one
+ * static import anywhere in this graph takes down the server render of every
+ * page of every site, including the sites that have never held a broadcast.
+ *
+ * That is not a hypothetical shape. The graph already dodges it once on
+ * purpose: `AccountDashboard` decides whether to draw a Join button by
+ * importing `media/bookingWindow`, a module whose own docblock says it imports
+ * nothing from the SDK for exactly this reason, rather than the neighbouring
+ * `media/index.ts` that does. `BroadcastPlayer` now dodges it a second time, by
+ * reaching its realtime stage through a dynamic `import()` fired from an
+ * effect. Both are one careless auto-import away from being undone, and neither
+ * fails a type check, a lint or any other spec when it is.
+ *
+ * `./media` is the separate entry that a site opts into (`BookingCallProvider`,
+ * `CallStage`), and it may import the SDK freely. This walk never enters it
+ * except through the files `./ui` actually names.
+ *
+ * A dynamic `import()` is deliberately NOT followed. It is the mechanism this
+ * guards, and following it would report the very thing that makes the player
+ * safe as the defect.
+ */
+
+/** `src`, three levels up from `src/ui/styled/_tests`. */
+const SRC = join(__dirname, "..", "..", "..");
+
+/** Packages that cannot be loaded on a server, whatever the bundler does. */
+const BROWSER_ONLY = ["@tribe-nest/media-client", "mediasoup-client"];
+
+/**
+ * Static imports only, and whether the compiler erases them.
+ *
+ * `import type ...` is gone before a bundler ever sees it, so it is free: the
+ * whole realtime path is typed against the SDK and none of that types reaches a
+ * server. Only the leading `import type` form counts as erased here. The
+ * per-specifier `import { type X }` form is erased too, but reading it
+ * correctly means parsing the clause, and being wrong in THAT direction is a
+ * guard that waves a real edge through. So it is treated as a value edge, which
+ * costs a walk of a few more files and nothing else.
+ */
+const STATIC_IMPORT = /(?:^|\n)[ \t]*(?:import|export)\s+(type\s+)?[^;]*?\bfrom\s*["']([^"']+)["']/g;
+const SIDE_EFFECT_IMPORT = /(?:^|\n)[ \t]*import\s*["']([^"']+)["']/g;
+
+type Edge = { specifier: string; typeOnly: boolean };
+
+function edgesIn(contents: string): Edge[] {
+  const edges: Edge[] = [];
+  for (const match of contents.matchAll(STATIC_IMPORT)) {
+    edges.push({ specifier: match[2]!, typeOnly: !!match[1] });
+  }
+  for (const match of contents.matchAll(SIDE_EFFECT_IMPORT)) {
+    edges.push({ specifier: match[1]!, typeOnly: false });
+  }
+  return edges;
+}
+
+/** `./x` to a real file, trying the extensions a bundler would try. */
+function resolveRelative(fromFile: string, specifier: string): string | null {
+  const base = join(dirname(fromFile), specifier);
+  for (const candidate of [base, `${base}.ts`, `${base}.tsx`, join(base, "index.ts"), join(base, "index.tsx")]) {
+    if (existsSync(candidate) && statSync(candidate).isFile()) return candidate;
+  }
+  return null;
+}
+
+/** Every file reachable from an entry by STATIC value imports, and how. */
+function valueGraph(entry: string): Map<string, string[]> {
+  const paths = new Map<string, string[]>([[entry, [relative(SRC, entry)]]]);
+  const queue = [entry];
+
+  while (queue.length > 0) {
+    const file = queue.shift()!;
+    const trail = paths.get(file)!;
+    for (const edge of edgesIn(readFileSync(file, "utf-8"))) {
+      if (edge.typeOnly) continue;
+      if (!edge.specifier.startsWith(".")) continue;
+      const resolved = resolveRelative(file, edge.specifier);
+      if (!resolved || paths.has(resolved)) continue;
+      paths.set(resolved, [...trail, relative(SRC, resolved)]);
+      queue.push(resolved);
+    }
+  }
+  return paths;
+}
+
+describe("the ./ui entry stays loadable on a server", () => {
+  const graph = valueGraph(join(SRC, "ui", "index.ts"));
+
+  it("reaches a real graph, so a pass here is not vacuous", () => {
+    expect(graph.size).toBeGreaterThan(50);
+    expect([...graph.keys()].some((file) => file.endsWith("BroadcastPlayer.tsx"))).toBe(true);
+  });
+
+  it("REGRESSION: imports no browser-only package anywhere on it", () => {
+    const offences: string[] = [];
+
+    for (const [file, trail] of graph) {
+      for (const edge of edgesIn(readFileSync(file, "utf-8"))) {
+        if (edge.typeOnly) continue;
+        if (!BROWSER_ONLY.some((name) => edge.specifier === name || edge.specifier.startsWith(`${name}/`))) continue;
+        offences.push(`${edge.specifier} via ${trail.join(" -> ")}`);
+      }
+    }
+
+    expect(offences).toEqual([]);
+  });
+
+  it("REGRESSION: keeps the realtime stage behind a dynamic import", () => {
+    // The player must never name this module in a static value import. It is
+    // the one file under `styled/` that loads the SDK, and the `import()` in
+    // the effect is what keeps it off every server render.
+    const player = readFileSync(join(SRC, "ui", "styled", "broadcast", "BroadcastPlayer.tsx"), "utf-8");
+    expect(player).toContain('import("./BroadcastRealtimeStage")');
+
+    const staticEdges = edgesIn(player).filter((edge) => edge.specifier.includes("BroadcastRealtimeStage"));
+    expect(staticEdges.every((edge) => edge.typeOnly)).toBe(true);
+  });
+});