@tribe-nest/forge 3.34.0 → 3.36.0

package/src/ui/headless/film/useFilmPlayback.ts

@@ -0,0 +1,497 @@
+import { useCallback, useEffect, useMemo, useRef, useState } from "react";
+import { usePublicAuth } from "../../../contexts/PublicAuthContext";
+import { useForge } from "../../../provider/ForgeProvider";
+import { safeRedirectPath } from "../../../utils/safeRedirect";
+import {
+  FILM_SESSION_EXPIRED,
+  FILM_SESSION_TAKEN_OVER,
+  absolutizeFilmUrl,
+  filmErrorCode,
+  filmErrorMessage,
+  filmErrorStatus,
+  useCreateFilmPlaybackSession,
+  useFilmPlaybackHeartbeat,
+  useRecordFilmProgress,
+  withFilmSessionToken,
+  type FilmPlaybackSession,
+  type FilmSubtitleTrack,
+  type FilmWatermarkPayload,
+} from "../../../data/queries/useFilmPlaybackSession";
+
+/** A `<track>` ready to render: the session's track with a fetchable `src`. */
+export interface FilmPlaybackSubtitle extends FilmSubtitleTrack {
+  /** Absolute and token-bearing, built exactly the way `src` is. */
+  src: string;
+}
+
+/**
+ * Headless episode playback: open the session, keep it alive, hand a player one
+ * URL, count the window down, and report where the fan got to.
+ *
+ * ## What this hook is not
+ *
+ * It is not the protection. Every layer that actually holds is on the server and
+ * is re-derived per request: the key endpoint re-checks the rental, the session
+ * holder and the token's episode binding on every fetch; the manifest is
+ * session-bound and single-episode-bound; the segment URLs are short-lived
+ * presigns; the platform watermark is burned into the pixels. A custom player
+ * built on this hook loses exactly ONE layer, the dynamic viewer overlay, and
+ * that layer deters rather than prevents. Drop `<FilmWatermark>` and a leaked
+ * recording is still traceable to the film but no longer to the renter. That is
+ * a real loss and it is stated here rather than discovered later.
+ *
+ * ## Why the src is deliberately stable
+ *
+ * The heartbeat mints a FRESH token every minute, but `src` is not rebuilt from
+ * it. Changing a `<video>` source mid-film restarts the film, which is a worse
+ * failure than the one it would prevent. The stored playlist is fetched once for
+ * VOD, so the original token is all a normal watch needs. The exception is an
+ * ABR switch after the token's ~10 minutes are up, which 401s inside the engine;
+ * that is what `recoverPlayback()` is for, and why a player should wire its own
+ * fatal-error handler to it rather than reloading the page.
+ */
+
+/** What the watch surface should draw INSTEAD of the player. */
+export type FilmPlaybackGateKind =
+  /** Nobody is signed in, and this episode is not a free preview. Needs a way IN. */
+  | "sign_in_required"
+  /**
+   * Signed in as somebody else. Needs a way OUT of the current session, never
+   * the word "sign in", which they have already done.
+   *
+   * The API does not currently emit 403 here - rentals are account-bound and a
+   * miss is a 404 so the endpoint is not an id oracle - but the arm is kept
+   * because it is the one state whose copy is actively harmful if merged into
+   * `sign_in_required`, and because the money path can start emitting it without
+   * a Forge change.
+   */
+  | "wrong_account"
+  /** No live rental covers this episode. Also what an unreleased or archived episode looks like. */
+  | "no_rental"
+  /** There WAS a rental and its window has run out. Offer a re-rent, not a sign-in. */
+  | "expired"
+  /** Something else went wrong: offline, 500, a slug that resolves to nothing. */
+  | "unavailable";
+
+export interface FilmPlaybackGate {
+  kind: FilmPlaybackGateKind;
+  /** The API's sentence when it sent one; the caller supplies its own copy otherwise. */
+  message: string | null;
+  status: number | null;
+}
+
+export interface UseFilmPlaybackOptions {
+  filmId?: string;
+  episodeId?: string;
+  /** Sign-in path (default `/login`; the site-starter passes `/i/login`). */
+  loginPath?: string;
+  /**
+   * Is this episode a free preview? Optional, and only an optimisation: it lets
+   * the hook attempt a session for an anonymous caller instead of gating first.
+   * Getting it wrong costs one refused request, never access.
+   */
+  isFreePreview?: boolean;
+  /** Don't open a session yet (the caller is still resolving the film). */
+  enabled?: boolean;
+  /** Seconds between position writes. The write is an upsert, so this can be lazy. */
+  progressIntervalSec?: number;
+}
+
+const DEFAULT_LOGIN_PATH = "/login";
+const DEFAULT_HEARTBEAT_SEC = 60;
+const DEFAULT_PROGRESS_INTERVAL_SEC = 10;
+/** Past this fraction of the runtime the episode counts as watched, which drives "next episode". */
+const COMPLETION_THRESHOLD = 0.95;
+
+const currentPath = (): string =>
+  typeof window === "undefined" ? "" : `${window.location.pathname}${window.location.search}`;
+
+/** `loginPath?redirect=<here>` - a sign-in that lands back on the player, never on a generic home. */
+export const filmSignInHref = (loginPath: string, path: string): string => {
+  const target = safeRedirectPath(path, "");
+  return target ? `${loginPath}?redirect=${encodeURIComponent(target)}` : loginPath;
+};
+
+/**
+ * Map a failed session/heartbeat call to what the screen should say.
+ *
+ * Pure and total so both 4xx arms can be exercised without a DOM, a client or a
+ * session. `isAuthenticated` is what separates the two 401 readings: signed out
+ * means "sign in", and signed in with a 401 means the SESSION lapsed rather than
+ * the person being unknown, which is recoverable rather than a gate.
+ */
+export function buildFilmPlaybackGate(input: {
+  error: unknown;
+  isAuthenticated: boolean;
+  /** The viewer's own rental, when one is known. Turns a bare 404 into "expired". */
+  hadRental?: boolean;
+}): FilmPlaybackGate | null {
+  const { error } = input;
+  if (error == null) return null;
+  const status = filmErrorStatus(error);
+  const message = filmErrorMessage(error);
+
+  if (status === 401) {
+    return { kind: input.isAuthenticated ? "unavailable" : "sign_in_required", message, status };
+  }
+  if (status === 403) return { kind: "wrong_account", message, status };
+  if (status === 410) return { kind: "expired", message, status };
+  if (status === 404) return { kind: input.hadRental ? "expired" : "no_rental", message, status };
+  return { kind: "unavailable", message, status };
+}
+
+/**
+ * Milliseconds left on a window, or null when there is no window (a free
+ * preview) or the timestamp is unreadable. Never negative: zero IS the answer
+ * once it has run out, and a negative number renders as a countdown running
+ * backwards.
+ */
+export function msUntil(expiresAt: string | null | undefined, now: Date = new Date()): number | null {
+  if (!expiresAt) return null;
+  const at = new Date(expiresAt).getTime();
+  if (!Number.isFinite(at)) return null;
+  return Math.max(0, at - now.getTime());
+}
+
+export function useFilmPlayback(opts: UseFilmPlaybackOptions) {
+  const { filmId, episodeId, isFreePreview, enabled = true } = opts;
+  const { apiUrl } = useForge();
+  const { isAuthenticated, isInitialized, user, logout } = usePublicAuth();
+
+  const createSession = useCreateFilmPlaybackSession(filmId, episodeId);
+  const heartbeat = useFilmPlaybackHeartbeat(filmId, episodeId);
+  const recordProgress = useRecordFilmProgress(filmId, episodeId);
+
+  const [session, setSession] = useState<FilmPlaybackSession | null>(null);
+  const [gate, setGate] = useState<FilmPlaybackGate | null>(null);
+  const [takenOver, setTakenOver] = useState(false);
+  const [now, setNow] = useState(() => Date.now());
+  /**
+   * Bumped only by `recoverPlayback()`. It is what makes `src` change, and it is
+   * deliberately NOT bumped by the heartbeat - see the hook docblock.
+   */
+  const [srcNonce, setSrcNonce] = useState(0);
+
+  /** The freshest token. Read through a ref so the heartbeat timer never re-arms on it. */
+  const tokenRef = useRef<string | null>(null);
+  /** One session per (film, episode) mount. Without this, StrictMode opens two and one takes the other over. */
+  const openedForRef = useRef<string | null>(null);
+  const lastProgressSentRef = useRef(0);
+  const completedRef = useRef(false);
+  /**
+   * Read by `reportProgress`, which is memoized and would otherwise close over a
+   * stale `takenOver`. A displaced tab whose player keeps firing time updates
+   * would post positions the server 409s, and the swallowed failures would
+   * quietly discard this rental's resume point for the rest of the film.
+   */
+  const stoppedRef = useRef(false);
+
+  const canAttempt =
+    enabled &&
+    !!filmId &&
+    !!episodeId &&
+    isInitialized &&
+    // An anonymous caller can only ever start a preview. Attempting anything
+    // else just to read the 401 back is a wasted round trip on every page view.
+    (isAuthenticated || isFreePreview !== false);
+
+  const open = useCallback(async () => {
+    if (!filmId || !episodeId) return;
+    setGate(null);
+    setTakenOver(false);
+    try {
+      const result = await createSession.mutateAsync();
+      tokenRef.current = result.sessionToken;
+      completedRef.current = false;
+      setSession(result);
+    } catch (error) {
+      tokenRef.current = null;
+      setSession(null);
+      setGate(buildFilmPlaybackGate({ error, isAuthenticated }));
+    }
+    // `createSession` is a stable react-query mutation object.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [filmId, episodeId, isAuthenticated]);
+
+  // Open exactly once per (film, episode). The key includes the account so a
+  // sign-in on the gate re-attempts rather than sitting on the anonymous refusal.
+  useEffect(() => {
+    if (!canAttempt) return;
+    const key = `${filmId}:${episodeId}:${user?.id ?? "anon"}`;
+    if (openedForRef.current === key) return;
+    openedForRef.current = key;
+    void open();
+  }, [canAttempt, filmId, episodeId, user?.id, open]);
+
+  /**
+   * The one refusal we make without asking the server.
+   *
+   * An anonymous caller on an episode we KNOW is not a free preview would get a
+   * 401 and nothing else, so the round trip buys nothing. What it would cost, if
+   * this arm were missing, is worse than a wasted request: with no gate and no
+   * session the surface has nothing to draw, and the person who simply needs to
+   * sign in gets "this cannot be played" instead of a way in.
+   */
+  useEffect(() => {
+    if (!enabled || !filmId || !episodeId || !isInitialized) return;
+    if (isAuthenticated || isFreePreview !== false) return;
+    setGate({ kind: "sign_in_required", message: null, status: 401 });
+  }, [enabled, filmId, episodeId, isInitialized, isAuthenticated, isFreePreview]);
+
+  // ── Heartbeat ──────────────────────────────────────────────────────────────
+  //
+  // Armed on the session id, not on the token: the token is replaced every beat
+  // and depending on it would tear the timer down and rebuild it each minute.
+  const sessionId = session?.sessionId ?? null;
+  const heartbeatSec = session?.heartbeatIntervalSec || DEFAULT_HEARTBEAT_SEC;
+
+  useEffect(() => {
+    if (!sessionId || takenOver || gate) return;
+    let cancelled = false;
+
+    const beat = async () => {
+      const token = tokenRef.current;
+      if (!token || cancelled) return;
+      try {
+        const result = await heartbeat.mutateAsync({ sessionToken: token });
+        if (cancelled) return;
+        tokenRef.current = result.sessionToken;
+        setSession((prev) => (prev ? { ...prev, expiresAt: result.expiresAt } : prev));
+      } catch (error) {
+        if (cancelled) return;
+        const code = filmErrorCode(error);
+        if (code === FILM_SESSION_TAKEN_OVER || filmErrorStatus(error) === 409) {
+          // Somebody else is watching on this rental. Stop, and say so plainly.
+          setTakenOver(true);
+          return;
+        }
+        if (code === FILM_SESSION_EXPIRED) {
+          // Nobody took over; this tab merely stopped beating. Re-open rather
+          // than gating - telling this person they are watching elsewhere would
+          // be a lie they would act on.
+          openedForRef.current = null;
+          void open();
+          return;
+        }
+        setGate(buildFilmPlaybackGate({ error, isAuthenticated, hadRental: !!session?.rental }));
+      }
+    };
+
+    const timer = setInterval(() => void beat(), heartbeatSec * 1000);
+    return () => {
+      cancelled = true;
+      clearInterval(timer);
+    };
+    // `heartbeat` is a stable react-query mutation object.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [sessionId, heartbeatSec, takenOver, gate, isAuthenticated, open]);
+
+  // ── The countdown ──────────────────────────────────────────────────────────
+  //
+  // Ticks only while there is something to count. A free preview has no window,
+  // so it never arms a timer.
+  const expiresAt = session?.expiresAt ?? null;
+  useEffect(() => {
+    if (!expiresAt) return;
+    setNow(Date.now());
+    const timer = setInterval(() => setNow(Date.now()), 1000);
+    return () => clearInterval(timer);
+  }, [expiresAt]);
+
+  const msRemaining = useMemo(() => msUntil(expiresAt, new Date(now)), [expiresAt, now]);
+
+  const stopped = !!gate || takenOver;
+  stoppedRef.current = stopped;
+
+  // The window running out mid-film is the one expiry a fan actually watches
+  // happen. Gate on it locally rather than waiting for the next request to fail,
+  // so the player stops with an explanation instead of stalling.
+  useEffect(() => {
+    if (msRemaining === 0 && !gate) setGate({ kind: "expired", message: null, status: null });
+  }, [msRemaining, gate]);
+
+  const src = useMemo(() => {
+    if (!session) return undefined;
+    void srcNonce;
+    const token = tokenRef.current ?? session.sessionToken;
+    return withFilmSessionToken(absolutizeFilmUrl(session.masterUrl, apiUrl), token);
+    // `srcNonce` is the whole point of this memo - see the hook docblock.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [session?.sessionId, session?.masterUrl, apiUrl, srcNonce]);
+
+  const keyUrl = useMemo(() => {
+    if (!session) return undefined;
+    const token = tokenRef.current ?? session.sessionToken;
+    return withFilmSessionToken(absolutizeFilmUrl(session.keyUrl, apiUrl), token);
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [session?.sessionId, session?.keyUrl, apiUrl, srcNonce]);
+
+  /**
+   * The `<track>` list, each with a fetchable `src`.
+   *
+   * Built the same way and on the same schedule as `src`: absolutized against
+   * the API, given the freshest token, and re-derived only on a recovery. A
+   * subtitle URL is credentialed exactly like the manifest, because it IS the
+   * script of a paid episode - the delivery route runs the same rental, session
+   * and episode-binding checks the key does.
+   *
+   * Stable across heartbeats for the same reason `src` is: swapping a track's
+   * `src` mid-film makes the browser drop and re-fetch the cues, which blanks
+   * the subtitles the viewer is reading.
+   *
+   * ⚠️ The token in these URLs lives ten minutes, and a `<track>` is fetched
+   * LAZILY - when the viewer picks that language. A player that renders them and
+   * leaves it there gives a fan who turns subtitles on half an hour in a 401 and
+   * an empty track, silently. A renderer must pull the cues down while the token
+   * is fresh by setting each track's `mode` to `"hidden"` once mounted; the
+   * starter's `FilmHlsPlayer` shows the four lines.
+   */
+  const subtitles = useMemo<FilmPlaybackSubtitle[]>(() => {
+    if (!session) return [];
+    const token = tokenRef.current ?? session.sessionToken;
+    return (session.subtitles ?? []).map((track) => ({
+      ...track,
+      src: withFilmSessionToken(absolutizeFilmUrl(track.url, apiUrl), token),
+    }));
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [session?.sessionId, session?.subtitles, apiUrl, srcNonce]);
+
+  /**
+   * Debounced position write.
+   *
+   * Call it from the player's time-update event as often as that fires; it
+   * writes at most once per `progressIntervalSec`, plus one immediate write the
+   * first time the episode crosses the completion threshold, because that write
+   * is what turns the next-episode prompt on and a fan who stops watching right
+   * there would otherwise never send it.
+   */
+  const reportProgress = useCallback(
+    (positionSec: number, durationSec?: number) => {
+      const token = tokenRef.current;
+      if (stoppedRef.current) return;
+      if (!token || !Number.isFinite(positionSec) || positionSec < 0) return;
+
+      const runtime = durationSec ?? session?.episode.durationSec ?? 0;
+      const completed = runtime > 0 && positionSec / runtime >= COMPLETION_THRESHOLD;
+      const justCompleted = completed && !completedRef.current;
+
+      const interval = (opts.progressIntervalSec ?? DEFAULT_PROGRESS_INTERVAL_SEC) * 1000;
+      const nowMs = Date.now();
+      if (!justCompleted && nowMs - lastProgressSentRef.current < interval) return;
+      lastProgressSentRef.current = nowMs;
+      if (justCompleted) completedRef.current = true;
+
+      // Fire and forget: this is resume state, never entitlement, so a failed
+      // write must not interrupt the film or surface an error to the viewer.
+      recordProgress
+        .mutateAsync({ sessionToken: token, positionSec: Math.floor(positionSec), completed })
+        .catch(() => undefined);
+    },
+    // `recordProgress` is a stable react-query mutation object.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [session?.episode.durationSec, opts.progressIntervalSec],
+  );
+
+  /**
+   * Re-derive the playback URL from the freshest token.
+   *
+   * The recovery path for the one thing a stable `src` cannot survive: an ABR
+   * switch after the original token's ten minutes are up. A player should call
+   * this from its own fatal-network-error handler and restore its position,
+   * rather than reloading the page and losing it.
+   */
+  const recoverPlayback = useCallback(async () => {
+    const token = tokenRef.current;
+    if (token) {
+      try {
+        const result = await heartbeat.mutateAsync({ sessionToken: token });
+        tokenRef.current = result.sessionToken;
+        setSrcNonce((n) => n + 1);
+        return;
+      } catch {
+        // Fall through to a full re-open: whatever the heartbeat refused, a new
+        // session is the only other move, and it is the one that also re-checks
+        // the rental.
+      }
+    }
+    openedForRef.current = null;
+    await open();
+    setSrcNonce((n) => n + 1);
+    // `heartbeat` is a stable react-query mutation object.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [open]);
+
+  /** Take the rental BACK from whoever displaced this tab. Opens a fresh session. */
+  const resumeHere = useCallback(async () => {
+    openedForRef.current = null;
+    await open();
+  }, [open]);
+
+  /** The `wrong_account` exit: clear the session and re-ask. */
+  const signOutAndRetry = useCallback(async () => {
+    await logout();
+    openedForRef.current = null;
+    await open();
+  }, [logout, open]);
+
+  return {
+    /** Held open until auth restores, so a bound rental never flashes "sign in" at its owner. */
+    isLoading: !isInitialized || (canAttempt && !session && !gate),
+    /** Non-null when the player must NOT be drawn. */
+    gate,
+    /** Another tab or device took this rental. Not a gate: `resumeHere()` takes it back. */
+    takenOver,
+    /**
+     * ⚠️ The player must not be on screen. UNMOUNT it, do not merely cover it.
+     *
+     * True while a gate is showing and true once this tab has been displaced.
+     * The second case is the one that is easy to get wrong: decision 7 caps a
+     * rental at one stream, and by the time the 409 arrives the engine has
+     * already fetched the AES key once and holds up to six hours of presigned
+     * segment URLs. Nothing server-side can pull those back, and after the 409
+     * this tab makes no further requests to refuse - so an overlay drawn over a
+     * still-playing video means both devices watch the film to the end, which is
+     * exactly the leak the cap exists to stop.
+     *
+     * A custom player built on this hook is on the honour system for the viewer
+     * overlay (decision 16) but NOT for this: honouring `stopped` is what keeps
+     * the one-stream cap true on a custom surface.
+     */
+    stopped,
+    session,
+    /** The master playlist for this session, absolute and token-bearing. */
+    src,
+    /** The AES-128 key endpoint for this session. Players fetch it via the playlist; exposed for diagnostics. */
+    keyUrl,
+    /**
+     * Sidecar WebVTT tracks for this episode, ready to render as `<track>`.
+     *
+     * ⚠️ A cross-origin `<track>` is only loaded when the `<video>` carries
+     * `crossOrigin="anonymous"`. These URLs are on the API's origin, not the
+     * site's, so a player that renders them without that attribute gets silence
+     * and no error.
+     */
+    subtitles,
+    watermark: (session?.watermark ?? null) as FilmWatermarkPayload | null,
+    episode: session?.episode ?? null,
+    rental: session?.rental ?? null,
+    /** True only for the visit that started the window. Say it out loud: it is the whole-title clock. */
+    clockStartedNow: !!session?.clockStartedNow,
+    resumeAtSec: session?.resumeAtSec ?? 0,
+    expiresAt,
+    /** Null for a free preview and until the clock starts; 0 once the window has run out. */
+    msRemaining,
+    isFreePreview: !!session?.episode.isFreePreview,
+    signedInEmail: user?.email ?? null,
+    isAuthenticated,
+    signInHref: filmSignInHref(opts.loginPath ?? DEFAULT_LOGIN_PATH, currentPath()),
+    reportProgress,
+    recoverPlayback,
+    resumeHere,
+    signOutAndRetry,
+    /** Try the whole thing again, from the session create. */
+    retry: resumeHere,
+  };
+}
+
+export type FilmPlaybackState = ReturnType<typeof useFilmPlayback>;