@tribe-nest/forge 3.38.0 → 3.39.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tribe-nest/forge",
-  "version": "3.38.0",
+  "version": "3.39.0",
   "publishConfig": {
     "access": "public"
   },

package/src/data/queries/useBroadcasts.ts

@@ -38,14 +38,24 @@ export function useValidateBroadcastPass() {
  * page (the "broadcast ended, keep this tab open" screen). Reading the detail
  * endpoint is what makes that page survive the end of the stream.
  */
-export function useLiveBroadcast(broadcastId?: string) {
+/**
+ * The viewer's validated pass, sent on every read that can return playback
+ * credentials.
+ *
+ * A gated broadcast withholds `liveUrl` and `realtimeConfig` from a caller who
+ * cannot show one, because the paywall used to be drawn in the browser only:
+ * the public read handed the manifest and the realtime session to anybody who
+ * asked, and the ticket box in front of it was decoration. Passing it here is
+ * what keeps a paying viewer playing.
+ */
+export function useLiveBroadcast(broadcastId?: string, passId?: string) {
   const { client, profileId } = useForge();
 
   return useQuery<ILiveBroadcast>({
-    queryKey: ["live-broadcast", profileId, broadcastId],
+    queryKey: ["live-broadcast", profileId, broadcastId, passId ?? null],
     queryFn: async () => {
       const res = await client.get(`/public/broadcasts/${broadcastId}`, {
-        params: { profileId },
+        params: { profileId, ...(passId ? { passId } : {}) },
       });
       return res.data;
     },
@@ -61,14 +71,14 @@ export function useLiveBroadcast(broadcastId?: string) {
  * poll, so a mid-stream edit to the title or the thumbnail cannot swap the
  * player out from under someone who is watching.
  */
-export function useLiveBroadcastPoll(broadcastId?: string, intervalMs = 5000) {
+export function useLiveBroadcastPoll(broadcastId?: string, intervalMs = 5000, passId?: string) {
   const { client, profileId } = useForge();
 
   return useQuery<ILiveBroadcast>({
-    queryKey: ["live-broadcast-poll", profileId, broadcastId],
+    queryKey: ["live-broadcast-poll", profileId, broadcastId, passId ?? null],
     queryFn: async () => {
       const res = await client.get(`/public/broadcasts/${broadcastId}`, {
-        params: { profileId },
+        params: { profileId, ...(passId ? { passId } : {}) },
       });
       return res.data;
     },
@@ -138,6 +148,30 @@ export type BroadcastSubscribeAnswer = {
   sessionDescription: { sdp: string; type: string };
 };
 
+/**
+ * A join ticket for a broadcast's live room on the platform's media plane.
+ *
+ * A superset of what the media SDK reads (`mediaUrl` and `token` are the only
+ * two it touches). The rest is what the server says about the ticket it just
+ * minted, useful to a site that wants to show it and ignored by the room.
+ *
+ * Written out here rather than imported from `@tribe-nest/media-client` on
+ * purpose: this module is loaded by every page of every site, and the media
+ * SDK is browser-only. A type import would be erased, but the next person to
+ * reach for a value from that package would not notice they had crossed the
+ * line.
+ */
+export type BroadcastViewerCredentials = {
+  /** The signalling entrypoint. A load balancer, never a node the client picked. */
+  mediaUrl: string;
+  token: string;
+  /** ISO. When THIS ticket dies, not when the broadcast does. */
+  expiresAt?: string;
+  /** This viewer's identity in the live room. Minted per viewer, never reused. */
+  identity?: string;
+  roomId?: string;
+};
+
 /**
  * The imperative half of watching a broadcast: the calls that are made in
  * response to something happening (a pass validated, a heartbeat, a viewer
@@ -164,18 +198,39 @@ export function useBroadcastSessionApi() {
     leave: async (broadcastId: string, sessionId?: string): Promise<void> => {
       await client.post(`/public/broadcasts/${broadcastId}/leave`, { sessionId });
     },
+    /**
+     * Mint a viewer credential for the broadcast's live room on the media plane.
+     *
+     * The PASS is the credential here: the endpoint is public and takes no
+     * bearer token, and it validates the pass exactly as `validate-session`
+     * does before minting anything for a gated broadcast.
+     *
+     * It answers 409 when the room is full, when realtime is switched off, or
+     * when nothing is live. That is a designed answer rather than a fault, and
+     * the caller's whole response to it is to watch the HLS stream instead.
+     */
+    viewerToken: async (payload: { broadcastId: string; passId?: string }): Promise<BroadcastViewerCredentials> => {
+      const res = await client.post(`/streams/v2/public/viewer-token`, payload);
+      return res.data;
+    },
     /** Subscribe to the WebRTC tracks of a realtime broadcast. */
     subscribe: async (payload: {
       sdp?: string;
       type?: string;
       trackIds?: string[];
       sessionId?: string;
+      /** The validated pass. A gated broadcast refuses a subscribe without it. */
+      passId?: string;
     }): Promise<BroadcastSubscribeAnswer> => {
       const res = await client.post(`/public/broadcasts/subscribe`, payload);
       return res.data;
     },
     /** Pin the viewer to one simulcast layer, or back to auto. */
-    switchQuality: async (payload: { track: Record<string, unknown>; sessionId?: string }): Promise<void> => {
+    switchQuality: async (payload: {
+      track: Record<string, unknown>;
+      sessionId?: string;
+      passId?: string;
+    }): Promise<void> => {
       await client.post(`/public/broadcasts/switch-quality`, payload);
     },
   };

package/src/i18n/de.json

@@ -159,6 +159,9 @@
   "forge.broadcast_pass_validation.validating": "Wird geprüft…",
   "forge.broadcast_player.anonymous": "Anonym",
   "forge.broadcast_player.chat": "Chat",
+  "forge.broadcast_player.fallback_help": "Der Stream mit geringer Verzögerung hat nur begrenzt Plätze und ist gerade entweder voll oder nicht aktiv. Der Standard-Stream zeigt dieselbe Übertragung einige Sekunden später. Sonst ändert sich nichts an der Seite.",
+  "forge.broadcast_player.fallback_help_label": "Warum ist das nicht der Stream mit geringer Verzögerung?",
+  "forge.broadcast_player.fallback_notice": "Du siehst den Standard-Stream",
   "forge.broadcast_player.fullscreen": "Vollbild",
   "forge.broadcast_player.message_label": "Nachricht",
   "forge.broadcast_player.pinned": "Angepinnt",
@@ -168,6 +171,8 @@
   "forge.broadcast_player.quality_low": "Niedrig",
   "forge.broadcast_player.quality_medium": "Mittel",
   "forge.broadcast_player.send": "Senden",
+  "forge.broadcast_player.sound_off": "Ton ausschalten",
+  "forge.broadcast_player.sound_on": "Ton einschalten",
   "forge.broadcast_player.started": "Vor {duration} gestartet",
   "forge.broadcast_player.watching_now": "{count} schauen gerade zu",
   "forge.broadcast_ticket_purchase.buy_tickets": "Tickets kaufen",

package/src/i18n/en.json

@@ -159,6 +159,9 @@
   "forge.broadcast_pass_validation.validating": "Validating…",
   "forge.broadcast_player.anonymous": "Anonymous",
   "forge.broadcast_player.chat": "Chat",
+  "forge.broadcast_player.fallback_help": "The low-latency stream holds a limited number of viewers, and right now it is either full or not running. The standard stream carries the same broadcast a few seconds behind. Nothing else about the page changes.",
+  "forge.broadcast_player.fallback_help_label": "Why is this not the low-latency stream?",
+  "forge.broadcast_player.fallback_notice": "Watching the standard stream",
   "forge.broadcast_player.fullscreen": "Fullscreen",
   "forge.broadcast_player.message_label": "Message",
   "forge.broadcast_player.pinned": "Pinned",
@@ -168,6 +171,8 @@
   "forge.broadcast_player.quality_low": "Low",
   "forge.broadcast_player.quality_medium": "Medium",
   "forge.broadcast_player.send": "Send",
+  "forge.broadcast_player.sound_off": "Turn sound off",
+  "forge.broadcast_player.sound_on": "Turn sound on",
   "forge.broadcast_player.started": "Started {duration} ago",
   "forge.broadcast_player.watching_now": "{count} watching now",
   "forge.broadcast_ticket_purchase.buy_tickets": "Buy tickets",

package/src/types/models.ts

@@ -1709,6 +1709,11 @@ export type ILiveEvent = {
 
 export type ILiveBroadcast = {
   id: string;
+  /**
+   * The v1 realtime path, over Cloudflare Calls. Kept exactly as it is until v1
+   * itself is retired. Not the same thing as `realtime` below, and a broadcast
+   * carries one or the other, never both.
+   */
   realtimeConfig?: {
     sessionId: string;
     tracks: {
@@ -1716,6 +1721,19 @@ export type ILiveBroadcast = {
       trackName: string;
     }[];
   };
+  /**
+   * Can this broadcast be watched over the platform's own media plane?
+   *
+   * `available` says the live room exists and the feature is on, and it says
+   * nothing about whether THIS viewer will get in: the room has a hard cap and
+   * the token endpoint is the only thing that knows how full it is. So it is a
+   * flag to ATTEMPT the plane on, never a promise, and a player that treats it
+   * as one leaves the hundred-and-first viewer on a black rectangle.
+   *
+   * It deliberately carries no room id and no token. The read that returns it
+   * is unauthenticated, so everything in it is public.
+   */
+  realtime?: { available: boolean };
   events: {
     eventId: string;
     eventTitle: string;

package/src/ui/headless/broadcast/useBroadcastWatch.ts

@@ -38,8 +38,12 @@ const readSessionId = (broadcastId?: string): string | null => {
  * be checked without a browser.
  */
 export function useBroadcastWatch(broadcastId?: string) {
-  const broadcastQuery = useLiveBroadcast(broadcastId);
-  const pollQuery = useLiveBroadcastPoll(broadcastId);
+  // The stored pass rides along on both reads: a gated broadcast withholds its
+  // playback credentials from a caller who cannot show one, so a read without
+  // it comes back playable-looking and empty.
+  const storedSessionId = readSessionId(broadcastId) ?? undefined;
+  const broadcastQuery = useLiveBroadcast(broadcastId, storedSessionId);
+  const pollQuery = useLiveBroadcastPoll(broadcastId, 5000, storedSessionId);
   const validatePass = useValidateBroadcastPass();
   const sessionApi = useBroadcastSessionApi();
 

package/src/ui/media/_tests/CallStage.spec.tsx

@@ -73,6 +73,7 @@ const fakeTransport = (): MediaTransport => ({
       id: `p-local-${produced.length}`,
       kind: "audio",
       closed: false,
+      replaceTrack: vi.fn(async () => undefined),
       pause: vi.fn(),
       resume: vi.fn(),
       close: vi.fn(),

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);
+  });
+});