@torrent-tv/proxy 2.75.0 → 2.76.1

package/services/viewer/Viewer.js

@@ -0,0 +1,145 @@
+/**
+ * @file One person watching, and everything that is true of them alone.
+ *
+ * A viewer is not a property of the material. What they are listening to, which
+ * quality step they have on screen, what is being prepared for them, where they
+ * are and what their link can carry — none of it changes a byte of what any
+ * encoder produces, and none of it belongs to a session, which is a description
+ * of an OUTPUT.
+ *
+ * It was six parallel maps hung on the session, each keyed by consumer id:
+ * `audioChoiceByConsumer`, `activeVariantByConsumer`,
+ * `warmingVariantByConsumer`, `warmingAudioByConsumer`, `consumerHeads`,
+ * `netReports`. Six places to remember to update and six to remember to forget,
+ * and the forgetting was already wrong — releasing a consumer emptied none of
+ * them, so a viewer who had left went on counting as wanting their soundtrack
+ * until their head expired, and their entries stayed for the life of the
+ * session.
+ *
+ * One object, one map, one thing to remove.
+ *
+ * **Nothing here knows about ffmpeg, the disk or the torrent.** A viewer states
+ * what they want and where they are; what to make of that is the orchestrator's
+ * question, and it reads a union of viewers rather than any one of them.
+ */
+
+export class Viewer {
+  /**
+   * @param {string} id - The consumer id the browser sends with every request
+   *   that means "this viewer".
+   */
+  constructor(id) {
+    this.id = String(id ?? "");
+    /**
+     * Which soundtrack this viewer is listening to and whether their browser
+     * needs it re-encoded. Theirs alone: two viewers of one picture may have
+     * chosen different languages, and one browser may decode a track another
+     * cannot.
+     * @type {{ trackIndex: number, transcode: boolean }}
+     */
+    this.audio = { trackIndex: 0, transcode: false };
+    /** The quality step on their screen. Null means the base session. @type {string | null} */
+    this.activeVariantId = null;
+    /** A step being prepared for a switch they have not made yet. @type {string | null} */
+    this.warmingVariantId = null;
+    /** A soundtrack being prepared for the same reason. @type {string | null} */
+    this.warmingAudioId = null;
+    /**
+     * Where they are: the segment they last asked for, or the position they
+     * stated by seeking. `seeked` holds the stated position for as long as they
+     * stay there, which is the distinction a cold open's soundtrack placement
+     * turns on.
+     * @type {{ segment: number, seconds: number, at: number, seeked?: number } | null}
+     */
+    this.head = null;
+    /** What their link was last measured to carry. @type {object | null} */
+    this.netReport = null;
+    /**
+     * Every output this viewer is watching, by session id: the picture, the
+     * quality step on their screen, the soundtrack they chose.
+     *
+     * WHY THERE ARE TWO SETS AND NOT ONE. There is one relation — this person
+     * watches this output — and it is asked from both ends. An output asks "has
+     * anybody left?", to decide whether to go on producing. A viewer who leaves
+     * asks "what was I watching?", so that each of those outputs can be told.
+     * Neither question can be answered from the other side without walking every
+     * session in the process, so the relation is indexed both ways. It is
+     * written in exactly one place — `Viewers.of` and `Viewers.leaves` write
+     * both directions together — which is what keeps two indexes of one relation
+     * from becoming two different answers.
+     *
+     * This is what replaced a film object. There is no "film" anywhere in this
+     * proxy — its parts are born at different times, die at different times and
+     * are addressed separately — and the three link fields that stood in for one
+     * could not say how many people were listening to a soundtrack.
+     *
+     * @type {Set<string>}
+     */
+    this.outputs = new Set();
+  }
+
+  /**
+   * Whether this viewer has been heard from recently enough to still be
+   * watching.
+   *
+   * Nothing releases a session when a channel closes, so without this a viewer
+   * whose tab is gone would hold a soundtrack or a quality step for the whole
+   * life of the session.
+   *
+   * @param {number} now
+   * @param {number} staleAfterMs
+   * @returns {boolean}
+   */
+  isLive(now, staleAfterMs) {
+    return this.head !== null && now - this.head.at <= staleAfterMs;
+  }
+
+  /**
+   * Where this viewer is, in seconds, or null when they have never said.
+   *
+   * @returns {number | null}
+   */
+  positionSeconds() {
+    if (this.head === null) {
+      return null;
+    }
+    return Number.isFinite(this.head.seeked) ? this.head.seeked : this.head.seconds;
+  }
+}
+
+/**
+ * The viewers of one session, made on first use.
+ *
+ * @param {object} session
+ * @returns {Map<string, Viewer>}
+ */
+export function viewersOf(session) {
+  if (!(session.viewers instanceof Map)) {
+    session.viewers = new Map();
+  }
+  return session.viewers;
+}
+
+/**
+ * The viewer with this id, made if this session has not met them before.
+ *
+ * Use `Viewers.of` instead wherever a registry is at hand: this makes ONE
+ * viewer per session, so the same person watching a picture, a quality step and
+ * a soundtrack is three objects, and `outputs` — a fact about the person — is
+ * then three sets that nothing keeps in step. It is kept for a session assembled
+ * by hand in a test that has no registry.
+ *
+ * @param {object} session
+ * @param {string} consumerId
+ * @returns {Viewer}
+ */
+export function viewerOf(session, consumerId) {
+  const viewers = viewersOf(session);
+  let viewer = viewers.get(consumerId);
+  if (!viewer) {
+    viewer = new Viewer(consumerId);
+    viewers.set(consumerId, viewer);
+  }
+  viewer.outputs.add(session.id);
+  return viewer;
+}

package/services/viewer/Viewers.js

@@ -0,0 +1,124 @@
+/**
+ * @file Every viewer this proxy has met, one object per person.
+ *
+ * A viewer used to be made per SESSION: the same person watching a picture, a
+ * quality step and a soundtrack was three objects, each with its own copy of
+ * what that person had chosen and where they were. Two of those copies were
+ * always wrong, and the field that says which outputs a person is watching was
+ * worse than wrong — being per session, each copy could only ever hold the id
+ * of the session that owned it, so it carried no information at all and the one
+ * place that read it could learn nothing from it.
+ *
+ * One person is one object here, keyed by the consumer id the browser sends.
+ * That id is minted once per film opened in the page, so one id is one person
+ * watching one film, and sharing the object cannot conflate two films.
+ *
+ * The relation "this person watches this output" is indexed both ways — the
+ * output holds its viewers, the viewer holds its outputs — because it is asked
+ * from both ends, and both indexes are written here and nowhere else.
+ */
+
+import { Viewer, viewersOf } from "./Viewer.js";
+
+export class Viewers {
+  /**
+   * One object per named viewer. An unnamed one is not in here: a viewer that
+   * cannot say who it is is not the same viewer as another that cannot, so it
+   * belongs to the session that met it and to no one else.
+   *
+   * @type {Map<string, Viewer>}
+   */
+  #byId = new Map();
+
+  /**
+   * This viewer, watching this output.
+   *
+   * Both directions of the relation are written here. Asking for a viewer of an
+   * output IS the statement that they are watching it: every caller either
+   * records where they are, what they chose, or what is being prepared for
+   * them, and each of those is only true of somebody watching.
+   *
+   * @param {object} output - A session.
+   * @param {string} consumerId
+   * @returns {Viewer}
+   */
+  of(output, consumerId) {
+    const viewers = viewersOf(output);
+    const known = viewers.get(consumerId);
+    if (known) {
+      known.outputs.add(output.id);
+      return known;
+    }
+    const viewer = consumerId
+      ? this.#byId.get(consumerId) ?? new Viewer(consumerId)
+      : new Viewer("");
+    if (consumerId) {
+      this.#byId.set(consumerId, viewer);
+    }
+    viewers.set(consumerId, viewer);
+    viewer.outputs.add(output.id);
+    return viewer;
+  }
+
+  /**
+   * The viewer with this id, or null when nobody by that name is watching
+   * anything. Never makes one.
+   *
+   * @param {string} consumerId
+   * @returns {Viewer | null}
+   */
+  get(consumerId) {
+    return this.#byId.get(consumerId) ?? null;
+  }
+
+  /**
+   * The outputs this viewer is watching, as ids, copied so that leaving them
+   * can be walked without mutating what is being walked.
+   *
+   * @param {object} anyOutput - A session they are known to, for an unnamed
+   *   viewer whose record lives on that session alone.
+   * @param {string} consumerId
+   * @returns {string[]}
+   */
+  watching(anyOutput, consumerId) {
+    const viewer = consumerId
+      ? this.#byId.get(consumerId)
+      : viewersOf(anyOutput).get("");
+    return viewer ? [...viewer.outputs] : [];
+  }
+
+  /**
+   * This viewer is no longer watching this output.
+   *
+   * Both directions again, and the viewer itself is forgotten once it is
+   * watching nothing — otherwise the registry would be a map that only grows,
+   * which is the shape of half the memory faults recorded in this repository.
+   *
+   * @param {object} output - A session.
+   * @param {string} consumerId
+   * @returns {boolean} Whether they were watching it.
+   */
+  leaves(output, consumerId) {
+    const viewers = viewersOf(output);
+    const viewer = viewers.get(consumerId);
+    if (!viewer) {
+      return false;
+    }
+    viewers.delete(consumerId);
+    viewer.outputs.delete(output.id);
+    if (consumerId && viewer.outputs.size === 0) {
+      this.#byId.delete(consumerId);
+    }
+    return true;
+  }
+
+  /**
+   * How many named viewers are watching anything. For the log line and for a
+   * check that the registry does not grow.
+   *
+   * @returns {number}
+   */
+  get size() {
+    return this.#byId.size;
+  }
+}