@torrent-tv/proxy 2.83.7 → 2.84.0

package/services/viewer/Viewer.js

@@ -64,20 +64,30 @@ export class Viewer {
     /** A soundtrack being prepared for the same reason. @type {string | null} */
     this.warmingAudioId = null;
     /**
-     * Where they are.
+     * Where their picture stood when they last said so, and when they said it.
      *
-     * Set when they arrive, from the position their own request named, and
-     * moved by the segments they ask for and by the seeks they report. Never
-     * null for a viewer this process has met: "we do not know where they are"
-     * is not a state a viewer can be in, because a viewer arrives by asking for
+     * ONE FACT WITH ONE WRITER: the viewer. It is set when they arrive — from
+     * the position their own create request named — and moved only by what they
+     * state afterwards, a seek or a report carrying their playhead. Never null
+     * for a viewer this process has met, because a viewer arrives by asking for
      * a position.
      *
-     * `seeked` holds a position they STATED, for as long as they stay there,
-     * which is the distinction a cold open's soundtrack placement turns on: a
-     * request is evidence about where their player is reading, a seek is the
-     * viewer saying where they are.
+     * A REQUEST FOR A SEGMENT IS NOT A POSITION and never writes here. It says
+     * how far their buffer has reached, which is a different quantity and one
+     * nothing in the plan needs: a segment either exists and is served, or does
+     * not and is waited for.
      *
-     * @type {{ segment: number, seconds: number, at: number, seeked?: number | null } | null}
+     * Two writers is what this replaced, and the cost is measured. Until
+     * 2026-09-13 a seek wrote `seeked` while a request wrote `seconds`, and
+     * `positionSeconds` preferred whichever was set — so the two took turns and
+     * the priority map jumped back and forth by one or two segments several
+     * times a second. Field that day, one output over one second:
+     * `p100:#9..#10`, `p100:#18..#20`, `p100:#16..#18`, `p100:#18..#20`, with
+     * the second viewer stopped dead at 1673.6 s throughout. The encoder
+     * placement followed the map, as it must, and the machine spent six minutes
+     * on 77 starts and 141 stops against one normal end.
+     *
+     * @type {{ seconds: number, at: number } | null}
      */
     this.position = null;
     /**
@@ -181,7 +191,7 @@ export class Viewer {
     if (!Number.isFinite(seconds) || seconds < 0) {
       return;
     }
-    this.position = { seconds, at: now, seeked: seconds };
+    this.position = { seconds, at: now };
     this.lastSeenAt = now;
   }
 
@@ -256,21 +266,21 @@ export class Viewer {
   }
 
   /**
-   * Whether this viewer is still watching.
+   * Whether this viewer is here.
    *
-   * Two ways to stop being present, and neither of them is "asked for nothing
-   * recently". Something must have SAID they are gone, or nothing at all must
-   * have been heard from them for longer than any silence a watching viewer can
-   * produce.
+   * PRESENCE IS THE CONNECTION, AND ONLY THE CONNECTION. They are here from the
+   * moment they are known until something SAYS they are gone: the browser
+   * releasing the session, or their connection closing. Nothing else, and in
+   * particular not silence.
    *
-   * The second half exists only because the connection cannot always say: an
-   * `onClosed` on a data channel does not always come, and a transport that is
-   * not a data channel at all may have nothing to say. It is a backstop for a
-   * missing statement, not the ordinary way a viewer leaves.
+   * Silence used to end it, after an interval longer than "any silence a
+   * watching viewer can produce" — and there is no such interval. A viewer who
+   * has paused, whose tab is hidden and whose timers the browser has throttled,
+   * or who holds two minutes of cushion, all say nothing for as long as they
+   * like and are all still watching. Deciding presence from that made it a
+   * guess with a threshold; deciding it from the connection makes it a fact
+   * with an owner.
    *
-   * @param {number} now
-   * @param {number} staleAfterMs - Longer than any silence a watching viewer
-   *   can produce. Derived from the cushion, never chosen here.
    * @returns {boolean}
    */
   /**
@@ -290,11 +300,8 @@ export class Viewer {
     return this.playing !== false && this.onScreen !== false;
   }
 
-  isPresent(now, staleAfterMs) {
-    if (this.gone) {
-      return false;
-    }
-    return now - this.lastSeenAt <= staleAfterMs;
+  isPresent() {
+    return this.gone !== true;
   }
 
   /**
@@ -308,16 +315,36 @@ export class Viewer {
   }
 
   /**
-   * Where this viewer is, in seconds, or null when they have somehow never been
-   * placed — which for a viewer created through `Viewers.of` cannot happen.
+   * Where this viewer is NOW, in seconds of film.
    *
-   * @returns {number | null}
+   * A FUNCTION OF TIME, not a stored number. A viewer whose picture is moving
+   * covers a second of film every second, so between the moments they speak
+   * their position is known exactly — it is where they last were plus the time
+   * since. A viewer whose picture is stopped covers nothing and stays where
+   * they are, which is the same formula with the rate at zero.
+   *
+   *   position(now) = stated + rate * (now - statedAt),   rate = playing ? 1 : 0
+   *
+   * Held as a stored number instead, it was a staircase: flat for the ten
+   * seconds between reports and then a jump, so everything derived from it —
+   * the priority map, and through the map every encoder — changed in steps for
+   * a viewer who was moving smoothly. And because two writers were filling that
+   * number in turn, the steps went backwards as often as forwards.
+   *
+   * There is nothing to tune here and no state to keep: one reading, one clock,
+   * one rate the page itself states.
+   *
+   * @param {number} [now]
+   * @returns {number | null} Null only for a viewer never placed, which for one
+   *   created through `Viewers.of` cannot happen.
    */
-  positionSeconds() {
+  positionSeconds(now = Date.now()) {
     if (this.position === null) {
       return null;
     }
-    return Number.isFinite(this.position.seeked) ? this.position.seeked : this.position.seconds;
+    const rate = this.playing ? 1 : 0;
+    const elapsedSec = Math.max(0, (now - this.position.at) / 1000);
+    return this.position.seconds + rate * elapsedSec;
   }
 }
 

package/services/viewer/positions.js

@@ -1,48 +1,120 @@
-/**
- * @file Where the viewers of one output stand.
- *
- * Asked by whatever has to give disk back: what lies behind every viewer has
- * been played and will not be wanted again unless somebody seeks back, and what
- * lies ahead of the furthest will be wanted eventually. So an answer of "nobody"
- * is the strongest statement there is — everything that output holds is worth
- * less than anything anybody is on their way to.
- *
- * Pure: it is handed the sessions, the clock and a way to turn seconds into a
- * segment number, and it holds none of them.
- */
-
-import { viewersOf } from "./Viewer.js";
-
-/**
- * @param {object} params
- * @param {Iterable<{ outputKey?: string }>} params.sessions - Every live session.
- * @param {string} params.outputKey - The output being asked about.
- * @param {(session: object, seconds: number) => number} params.segmentAt - Which
- *   segment of THAT session's timeline a moment of film falls in.
- * @param {number} params.now
- * @param {number} params.staleAfterMs - Silence longer than any a watching
- *   viewer can produce.
- * @returns {number[]} A segment number per present viewer, unsorted.
- */
-export function viewerSegmentsOn({ sessions, outputKey, segmentAt, now, staleAfterMs }) {
-  const at = [];
-  for (const session of sessions) {
-    if (session.outputKey !== outputKey) {
-      continue;
-    }
-    for (const viewer of viewersOf(session).values()) {
-      if (!viewer.isPresent(now, staleAfterMs)) {
-        continue;
-      }
-      const seconds = viewer.positionSeconds();
-      if (!Number.isFinite(seconds)) {
-        continue;
-      }
-      const index = segmentAt(session, /** @type {number} */ (seconds));
-      if (Number.isInteger(index) && index >= 0) {
-        at.push(index);
-      }
-    }
-  }
-  return at;
-}
+/**
+ * @file Where the viewers of one output stand.
+ *
+ * Asked by whatever has to give disk back: what lies behind every viewer has
+ * been played and will not be wanted again unless somebody seeks back, and what
+ * lies ahead of the furthest will be wanted eventually. So an answer of "nobody"
+ * is the strongest statement there is — everything that output holds is worth
+ * less than anything anybody is on their way to.
+ *
+ * Pure: it is handed the sessions, the clock and a way to turn seconds into a
+ * segment number, and it holds none of them.
+ */
+
+import { viewersOf } from "./Viewer.js";
+
+/**
+ * @param {object} params
+ * @param {Iterable<{ outputKey?: string }>} params.sessions - Every live session.
+ * @param {string} params.outputKey - The output being asked about.
+ * @param {(session: object, seconds: number) => number} params.segmentAt - Which
+ *   segment of THAT session's timeline a moment of film falls in.
+ * @param {number} params.now
+ * @returns {number[]} A segment number per present viewer, unsorted.
+ */
+export function viewerSegmentsOn({ sessions, outputKey, segmentAt, now }) {
+  const at = [];
+  for (const session of sessions) {
+    if (session.outputKey !== outputKey) {
+      continue;
+    }
+    for (const viewer of viewersOf(session).values()) {
+      if (!viewer.isPresent()) {
+        continue;
+      }
+      const seconds = viewer.positionSeconds(now);
+      if (!Number.isFinite(seconds)) {
+        continue;
+      }
+      const index = segmentAt(session, /** @type {number} */ (seconds));
+      if (Number.isInteger(index) && index >= 0) {
+        at.push(index);
+      }
+    }
+  }
+  return at;
+}
+
+/**
+ * Where a viewer of one output is, in seconds of film, NOW.
+ *
+ * One reading with one owner, and a function of time rather than a stored
+ * number: a viewer states where their picture is, and the clock carries it
+ * forward between statements.
+ *
+ * Three readings ranked by priority used to answer this — a seek, the start of
+ * the last segment requested, the position the output was opened at — with a
+ * second function saying which had answered. They were three different
+ * quantities wearing one name, two of them written at different rates, so the
+ * answer alternated between them several times a second and every encoder
+ * followed it.
+ *
+ * Without a name, the FURTHEST viewer: what lies behind them has already been
+ * made, so that is what a reading about no particular person wants. With
+ * nobody present at all, where the output was opened.
+ *
+ * @param {object} session
+ * @param {string} [consumerId] - Whose position.
+ * @param {number} [now]
+ * @returns {number} Seconds, never negative.
+ */
+export function viewerSecondsOn(session, consumerId = "", now = Date.now()) {
+  const named = consumerId ? session?.viewers?.get(consumerId) ?? null : null;
+  if (named) {
+    return Math.max(0, named.positionSeconds(now) ?? 0);
+  }
+  let furthest = null;
+  for (const viewer of viewersOf(session).values()) {
+    if (!viewer.isPresent()) {
+      continue;
+    }
+    const seconds = viewer.positionSeconds(now);
+    if (Number.isFinite(seconds)) {
+      furthest = furthest === null ? seconds : Math.max(furthest, seconds);
+    }
+  }
+  const opened = Number(session?.progress?.startPositionSeconds);
+  return Math.max(0, furthest ?? (Number.isFinite(opened) ? opened : 0));
+}
+
+/**
+ * The earliest film anybody present is standing on, across several outputs.
+ *
+ * WHAT IT IS FOR: a soundtrack is created at a position, and a track begun
+ * where the leader stands has nothing to give the viewer behind them. So the
+ * earliest, and across every rung of the picture, because two viewers of one
+ * film may be on different ones.
+ *
+ * This is a fact about PEOPLE and it decides one parameter of an output. It
+ * does not place encoders: which encoder works where is the priority map's
+ * answer and nothing here is consulted for it.
+ *
+ * @param {Iterable<object>} sessions
+ * @param {number} [now]
+ * @returns {number | null} Seconds, or null when nobody is present.
+ */
+export function earliestViewerSecondsOn(sessions, now = Date.now()) {
+  let earliest = null;
+  for (const session of sessions ?? []) {
+    for (const viewer of viewersOf(session).values()) {
+      if (!viewer.isPresent()) {
+        continue;
+      }
+      const seconds = viewer.positionSeconds(now);
+      if (Number.isFinite(seconds)) {
+        earliest = earliest === null ? seconds : Math.min(earliest, seconds);
+      }
+    }
+  }
+  return earliest;
+}

package/test/client-log-file.test.js

@@ -0,0 +1,110 @@
+/**
+ * @file The browser's log, written beside the proxy's.
+ *
+ * What these hold is the naming, because the name is the whole point: the two
+ * halves of a session have to join without guessing, and a torrent name is
+ * arbitrary bytes chosen by a stranger that is about to become a path.
+ */
+
+import test from "node:test";
+import assert from "node:assert/strict";
+import { mkdtempSync, readdirSync, readFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import { createClientLogFiles } from "../utils/client-log-file.js";
+
+/** A directory with a proxy log in it, which is what the sink is given. */
+function aDirectory() {
+  const dir = mkdtempSync(join(tmpdir(), "ttv-client-log-"));
+  return { dir, proxyLog: join(dir, "proxy.log") };
+}
+
+const aSession = (over = {}) => ({
+  sessionId: "abcd1234",
+  startedAt: "2026-09-13T16:05:24.123Z",
+  torrentName: "Reacher.S04E07.1080p.rus.LostFilm.TV.mkv",
+  infoHash: "94dda59fdf252447d6ca5a8775dab2d11a832da5",
+  ...over
+});
+
+test("the file lands beside the proxy log, named by when it started and what is watched", async () => {
+  const { dir, proxyLog } = aDirectory();
+  const logs = createClientLogFiles(proxyLog);
+  logs.write(aSession(), ["first line"]);
+  await logs.close();
+
+  const [name] = readdirSync(dir).filter((f) => f.startsWith("client-"));
+  assert.ok(name, "a client log file was written");
+  // The stamp is UTC and sorts; the session id joins it to the proxy's lines;
+  // the film says which one it is without opening the file.
+  assert.match(name, /^client-20260913-160524-abcd1234-Reacher\.S04E07\.1080p\.rus\.LostFilm\.TV\.mkv-94dda59f\.log$/);
+  assert.equal(readFileSync(join(dir, name), "utf8"), "first line\n");
+});
+
+test("lines from one session go on appending to the one file", async () => {
+  const { dir, proxyLog } = aDirectory();
+  const logs = createClientLogFiles(proxyLog);
+  logs.write(aSession(), ["one", "two"]);
+  logs.write(aSession(), ["three"]);
+  await logs.close();
+
+  const names = readdirSync(dir).filter((f) => f.startsWith("client-"));
+  assert.equal(names.length, 1);
+  assert.equal(readFileSync(join(dir, names[0]), "utf8"), "one\ntwo\nthree\n");
+});
+
+test("a session that has not chosen a film yet still gets its own file", async () => {
+  // The page opening, a proxy being chosen, a connection failing — all before
+  // any torrent exists, and all worth keeping.
+  const { dir, proxyLog } = aDirectory();
+  const logs = createClientLogFiles(proxyLog);
+  logs.write(aSession({ torrentName: "", infoHash: "" }), ["before any film"]);
+  await logs.close();
+
+  const [name] = readdirSync(dir).filter((f) => f.startsWith("client-"));
+  assert.match(name, /-no-torrent-yet\.log$/);
+});
+
+test("the file keeps its name when the film arrives mid-session", async () => {
+  // Keyed by the session, not by the name: the earlier lines belong to the same
+  // viewing and must not start a second file.
+  const { dir, proxyLog } = aDirectory();
+  const logs = createClientLogFiles(proxyLog);
+  logs.write(aSession({ torrentName: "", infoHash: "" }), ["before"]);
+  logs.write(aSession(), ["after"]);
+  await logs.close();
+
+  const names = readdirSync(dir).filter((f) => f.startsWith("client-"));
+  assert.equal(names.length, 1);
+  assert.match(names[0], /-no-torrent-yet\.log$/);
+  assert.equal(readFileSync(join(dir, names[0]), "utf8"), "before\nafter\n");
+});
+
+test("a hostile torrent name cannot escape the directory", async () => {
+  const { dir, proxyLog } = aDirectory();
+  const logs = createClientLogFiles(proxyLog);
+  logs.write(aSession({ torrentName: "../../etc/passwd" }), ["x"]);
+  await logs.close();
+
+  const names = readdirSync(dir).filter((f) => f.startsWith("client-"));
+  assert.equal(names.length, 1);
+  assert.ok(!names[0].includes(".."), `no traversal in ${names[0]}`);
+  assert.ok(!names[0].includes("/"), `no separator in ${names[0]}`);
+});
+
+test("two sessions of one film are two files", async () => {
+  const { dir, proxyLog } = aDirectory();
+  const logs = createClientLogFiles(proxyLog);
+  logs.write(aSession({ sessionId: "aaaa1111" }), ["one viewer"]);
+  logs.write(aSession({ sessionId: "bbbb2222", startedAt: "2026-09-13T16:07:11.000Z" }), ["another"]);
+  await logs.close();
+
+  assert.equal(readdirSync(dir).filter((f) => f.startsWith("client-")).length, 2);
+});
+
+test("no proxy log path means nothing is written and nothing throws", async () => {
+  const logs = createClientLogFiles("");
+  logs.write(aSession(), ["dropped"]);
+  await logs.close();
+});

package/test/held-request-width.test.js

@@ -17,6 +17,7 @@ import os from "node:os";
 import path from "node:path";
 import { HlsSessionManager } from "../services/hls-session-manager.js";
 import { fmp4Format } from "../services/segment-formats/fmp4.js";
+import { viewerOf } from "../services/viewer/Viewer.js";
 
 const SESSION_ID = "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee";
 const SEGMENT_SECONDS = 4;
@@ -32,7 +33,7 @@ async function managerWithSession() {
     localBindHost: "127.0.0.1",
     localPort: 9090
   });
-  manager.sessionsById.set(SESSION_ID, {
+  const session = {
     id: SESSION_ID,
     dirPath,
     // Where this file is cut, held by the file. A fixture that stated it
@@ -44,10 +45,12 @@ async function managerWithSession() {
     state: "ready",
     segmentFormat: fmp4Format,
     segmentCount: 200,
-    useSyntheticPlaylist: true,
-    // The viewer is at segment #25.
-    furthestViewerSeconds: 100
-  });
+    useSyntheticPlaylist: true
+  };
+  manager.sessionsById.set(SESSION_ID, session);
+  // The viewer is at segment #25, and says so themselves.
+  viewerOf(session, "").moveTo(25 * SEGMENT_SECONDS);
+  viewerOf(session, "").playing = false;
   return { manager, dirPath };
 }
 

package/test/orchestrator-wired.test.js

@@ -109,21 +109,27 @@ test("what a viewer waits for reaches the plan without their name", (t) => {
   assert.ok(wanted.some((zone) => zone.to > 5), "and the cushion in front of them");
 });
 
-test("a viewer nothing has been heard from at all stops being waited for", (t) => {
+test("a viewer who has gone stops being waited for, and silence alone never counts", (t) => {
   const { manager, root, dirPath } = managerWithAnOutput();
   t.after(() => rmSync(root, { recursive: true, force: true }));
 
   const session = sessionOn({ id: "one", dirPath });
   manager.sessionsById.set(session.id, session);
-  const gone = viewerOf(session, "gone");
-  gone.position = { segment: 5, seconds: 20, at: Date.now() - 10 * 60 * 1000 };
-  // What decides it is when they were last HEARD FROM, not when they last
-  // asked for a segment: a viewer holding a full cushion asks for nothing for
-  // as long as it takes to drain, and is no less present for it.
-  gone.seen(Date.now() - 10 * 60 * 1000);
-
+  const person = viewerOf(session, "gone");
+  person.moveTo(20, Date.now() - 10 * 60 * 1000);
+  person.playing = false;
+  person.seen(Date.now() - 10 * 60 * 1000);
+
+  // TEN MINUTES OF SILENCE IS NOT LEAVING. A paused viewer, a hidden tab whose
+  // timers the browser has throttled, and one holding a full cushion are all
+  // silent and all still watching, so what they want is still wanted.
   manager.planEncodersNow();
+  assert.ok(manager.encodeOrchestrator.demand.mapOn(KEY).length > 0, "still watching");
 
+  // Something SAYS they are gone — the browser released the session, or their
+  // connection closed. That is the only way out.
+  manager.viewers.leaves(session, "gone");
+  manager.planEncodersNow();
   assert.equal(manager.encodeOrchestrator.demand.mapOn(KEY).length, 0);
 });