@torrent-tv/proxy 2.61.0 → 2.63.0

package/services/hls-session-manager.js

@@ -400,6 +400,10 @@ const READ_WINDOW_SECONDS = 30;
 const READ_WINDOW_MIN_BYTES = 16 * 1024 * 1024;
 const READ_WINDOW_MAX_BYTES = 96 * 1024 * 1024;
 const LOOKAHEAD_PAUSE_SECONDS = 120;
+// How often each session says what its cushion is. Half a minute: the link
+// reports that feed it arrive every ten seconds, and a line per session per
+// ten seconds would drown the log on a host serving several.
+const CUSHION_REPORT_MS = 30_000;
 // How old a viewer's link report may be and still describe where they are. It
 // is sent every 10 s, and a seek in between moves them somewhere this cannot
 // predict — so anything older is treated as no report at all.
@@ -2214,6 +2218,8 @@ export class HlsSessionManager {
       // buffer from another viewer's read head.
       /** @type {Map<string, { linkMbps: number, bufferedAheadSec: number, positionSeconds: number | null, at: number }>} */
       netReports: new Map(),
+      // When this session last said what its cushion is (see #sayCushion).
+      cushionSaidAt: 0,
       linkSlowSince: 0,
       sourceWidth,
       sourceHeight,
@@ -3339,6 +3345,7 @@ export class HlsSessionManager {
     // reached. Reported on its EDGES, because it is a state and not a stream.
     const claimed = Number(session.progress?.processedSeconds);
     const encodedTo = this.#segmentStartTime(session, viewerSegment) + aheadSeconds;
+    this.#sayCushion(session, encodedTo);
     const disagrees =
       Number.isFinite(claimed) && Math.abs(claimed - encodedTo) > LOOKAHEAD_PAUSE_SECONDS;
     if (disagrees && !session.lookAheadDisagreementSince) {
@@ -3377,6 +3384,57 @@ export class HlsSessionManager {
     }
   }
 
+  /**
+   * What the cushion actually is, said once every half minute per session.
+   *
+   * Three quantities that were never printed together, and could not be
+   * reconstructed afterwards from anything that was:
+   *
+   *   - how far the produced range runs ahead of the EARLIEST viewer's picture,
+   *     which is the protection an interruption would have to exhaust before
+   *     anybody saw it;
+   *   - what that costs the person hosting this proxy, in megabytes of film
+   *     pulled off the swarm ahead of the picture — the read window sits on top
+   *     of it, so this is a floor;
+   *   - what the browsers say they are holding, so the depth asked for on that
+   *     side can be checked against the depth that arrived.
+   *
+   * Every term is measured: the produced range comes from the segments on disk,
+   * the picture from the viewers' own reports, and the byte rate from the
+   * file's length over its duration. Roadmap item 4.
+   *
+   * @param {HlsSession} session
+   * @param {number} encodedTo - Seconds of film produced, contiguously, from
+   *   where the leading viewer is.
+   * @returns {void}
+   */
+  #sayCushion(session, encodedTo) {
+    const now = Date.now();
+    if (now - (session.cushionSaidAt ?? 0) < CUSHION_REPORT_MS) {
+      return;
+    }
+    const { earliestPosition, deepestBuffer, viewers } = this.#reportedPictureOf(session, now);
+    // Nobody has said where they are, so there is no picture to measure
+    // against and the line would be about nothing.
+    if (earliestPosition === null) {
+      return;
+    }
+    session.cushionSaidAt = now;
+    const aheadOfPicture = Math.max(0, encodedTo - earliestPosition);
+    const fileLength = this.#fileLengthByKey.get(`${session.sourceKey}:${session.fileIndex}`);
+    const duration = Number(session.totalDurationSeconds) || Number(session.durationSeconds) || 0;
+    const megabytes =
+      Number.isFinite(fileLength) && fileLength > 0 && duration > 0
+        ? ((aheadOfPicture * fileLength) / duration / 1e6).toFixed(0)
+        : "?";
+    logger.info(
+      `transcode ${session.id.slice(0, 8)} cushion: ${Math.round(aheadOfPicture)}s of film ready ` +
+        `ahead of the picture at ${Math.round(earliestPosition)}s (~${megabytes}MB pulled ahead), ` +
+        `${viewers} viewer(s) holding up to ` +
+        `${deepestBuffer === null ? "?" : deepestBuffer.toFixed(1)}s`
+    );
+  }
+
   /**
    * Seconds of playback ready without a gap, starting at the segment the viewer
    * is on.
@@ -7714,21 +7772,29 @@ export class HlsSessionManager {
    * @param {HlsSession} base
    * @returns {number}
    */
-  #audioStartSecondsFor(base) {
-    const watching = this.#activeVariant(base);
-    const readHead = this.#viewerPositionOf(watching);
-    const now = Date.now();
-    let earliestStated = null;
+  /**
+   * Where the earliest viewer's picture is, and the deepest cushion any of them
+   * reports holding — both read from the link reports, both null when nobody
+   * has said recently.
+   *
+   * @param {HlsSession} session
+   * @param {number} now
+   * @returns {{ earliestPosition: number | null, deepestBuffer: number | null, viewers: number }}
+   */
+  #reportedPictureOf(session, now) {
+    let earliestPosition = null;
     let deepestBuffer = null;
-    for (const report of watching.netReports.values()) {
+    let viewers = 0;
+    for (const report of session.netReports.values()) {
       if (now - report.at > NET_REPORT_FRESH_MS) {
         continue;
       }
+      viewers += 1;
       if (Number.isFinite(report.positionSeconds)) {
-        earliestStated =
-          earliestStated === null
+        earliestPosition =
+          earliestPosition === null
             ? report.positionSeconds
-            : Math.min(earliestStated, report.positionSeconds);
+            : Math.min(earliestPosition, report.positionSeconds);
       }
       if (Number.isFinite(report.bufferedAheadSec)) {
         deepestBuffer =
@@ -7737,6 +7803,14 @@ export class HlsSessionManager {
             : Math.max(deepestBuffer, report.bufferedAheadSec);
       }
     }
+    return { earliestPosition, deepestBuffer, viewers };
+  }
+
+  #audioStartSecondsFor(base) {
+    const watching = this.#activeVariant(base);
+    const readHead = this.#viewerPositionOf(watching);
+    const now = Date.now();
+    const { earliestPosition: earliestStated, deepestBuffer } = this.#reportedPictureOf(watching, now);
     if (earliestStated !== null) {
       // Never ahead of the read head: a position claiming to be past what has
       // been asked for is a report that arrived out of order, and acting on it

package/services/memory-report.js

@@ -19,7 +19,7 @@
  * runtime already maintains.
  */
 
-import { readFile } from "node:fs/promises";
+import { readFile, statfs } from "node:fs/promises";
 import os from "node:os";
 
 /** How often the reading is taken and written. */
@@ -86,6 +86,55 @@ export async function availableMemory() {
   return { bytes: os.freemem(), measured: false };
 }
 
+/**
+ * Anonymous memory this process holds, from the kernel's own rollup.
+ *
+ * `process.memoryUsage()` sees what V8 knows about. It cannot see memory the
+ * allocator has taken and not returned, and on musl — which is what the addon
+ * runs on — a heavy churn of 8 MiB pieces leaves exactly that. The rollup's
+ * `Anonymous` counts every mapping backed by nothing but memory, which is
+ * where both a live `SharedArrayBuffer` and a freed-but-retained span sit, so
+ * the difference between it and what the isolates admit to is the size of what
+ * neither can explain (roadmap item 2, step 4).
+ *
+ * @returns {Promise<number | null>} Bytes, or null off Linux.
+ */
+export async function readAnonymousMemory() {
+  try {
+    const text = await readFile("/proc/self/smaps_rollup", "utf8");
+    const match = /^Anonymous:\s+(\d+)\s+kB$/m.exec(text);
+    if (match) {
+      return Number(match[1]) * 1024;
+    }
+  } catch {
+    // silent-ok: not Linux, or the kernel is too old for the rollup. The line
+    // simply leaves the term out rather than printing a worse one.
+  }
+  return null;
+}
+
+/**
+ * How much room is left where this proxy spills pieces and writes segments.
+ *
+ * A budget for memory alone is half a budget: pieces evicted from memory go to
+ * disk, so a store that is well behaved about RAM can still fill the card an
+ * addon host boots from. Both limits are the machine's, and neither was
+ * measured before (roadmap item 2).
+ *
+ * @param {string} directory
+ * @returns {Promise<number | null>} Bytes free, or null where it cannot be read.
+ */
+export async function readDiskFree(directory) {
+  try {
+    const stats = await statfs(directory);
+    return Number(stats.bavail) * Number(stats.bsize);
+  } catch {
+    // silent-ok: `statfs` is not everywhere, and a missing disk figure must not
+    // cost the memory reading beside it.
+  }
+  return null;
+}
+
 /**
  * Render a size the way a person reads one.
  *
@@ -104,26 +153,61 @@ function megabytes(bytes) {
  * count is meaningless without the piece size, and the piece size differs per
  * torrent — on the film this proxy died under, 63 pieces meant 504 MB.
  *
+ * Two scopes, because two things are being asked and only one of them is
+ * per-thread. `rss` and the kernel's rollup belong to the PROCESS, so they are
+ * read once, on the main thread. The heap, external and arrayBuffer figures
+ * belong to an ISOLATE, and the torrent worker's are the ones that matter —
+ * the piece pool is a `SharedArrayBuffer` allocated there, which the main
+ * isolate cannot see at all. Reporting only the main thread's was half the
+ * reason 650 MB of a 893 MB process had no explanation on 2026-08-28.
+ *
  * @param {Object} reading
+ * @param {"process" | "thread"} [reading.scope]
+ * @param {string} [reading.label] - Which thread the isolate figures are of.
  * @param {{ rss: number, heapUsed: number, heapTotal: number, external: number, arrayBuffers: number }} reading.process
- * @param {number} reading.availableBytes
- * @param {boolean} reading.availableMeasured
- * @param {{ name: string, residentBytes: number, budgetBytes: number }[]} [reading.stores]
+ * @param {number} [reading.availableBytes]
+ * @param {boolean} [reading.availableMeasured]
+ * @param {number | null} [reading.anonymousBytes]
+ * @param {number | null} [reading.diskFreeBytes]
+ * @param {{ name: string, residentBytes: number, committedBytes: number, spilledBytes: number, budgetBytes: number }[]} [reading.stores]
  * @returns {string}
  */
-export function describeMemory({ process: usage, availableBytes, availableMeasured, stores = [] }) {
-  const storeResident = stores.reduce((total, store) => total + (store.residentBytes || 0), 0);
-  const storeBudget = stores.reduce((total, store) => total + (store.budgetBytes || 0), 0);
+export function describeMemory({
+  scope = "process",
+  label = "",
+  process: usage,
+  availableBytes,
+  availableMeasured,
+  anonymousBytes = null,
+  diskFreeBytes = null,
+  stores = []
+}) {
+  const total = (field) => stores.reduce((sum, store) => sum + (store[field] || 0), 0);
+  const storeResident = total("residentBytes");
+  const storeCommitted = total("committedBytes");
+  const storeSpilled = total("spilledBytes");
+  const storeBudget = total("budgetBytes");
+  // Holding and having taken are different quantities, and the gap between
+  // them is the whole of the growth this series exists to find: the pool only
+  // grows, so a spilled piece frees a slot and no memory.
   const storesPart = stores.length === 0
     ? "no torrent stores"
-    : `${stores.length} torrent store(s) holding ${megabytes(storeResident)} ` +
-      `of ${megabytes(storeBudget)} allowed`;
+    : `${stores.length} torrent store(s) holding ${megabytes(storeResident)}, ` +
+      `committed ${megabytes(storeCommitted)} of ${megabytes(storeBudget)} allowed, ` +
+      `${megabytes(storeSpilled)} spilled to disk`;
+  const isolate =
+    `heap=${megabytes(usage.heapUsed)}/${megabytes(usage.heapTotal)} ` +
+    `external=${megabytes(usage.external)} arrayBuffers=${megabytes(usage.arrayBuffers)}`;
+  if (scope === "thread") {
+    return `memory (${label || "thread"}): ${isolate}; ${storesPart}`;
+  }
   return (
-    `memory: rss=${megabytes(usage.rss)} heap=${megabytes(usage.heapUsed)}/${megabytes(usage.heapTotal)} ` +
-    `external=${megabytes(usage.external)} arrayBuffers=${megabytes(usage.arrayBuffers)}; ` +
+    `memory: rss=${megabytes(usage.rss)} ${isolate}` +
+    `${anonymousBytes === null ? "" : ` anon=${megabytes(anonymousBytes)}`}; ` +
     `${storesPart}; ` +
-    `machine has ${megabytes(availableBytes)} available` +
-    `${availableMeasured ? "" : " (estimated — /proc/meminfo could not be read)"}`
+    `machine has ${megabytes(availableBytes ?? 0)} available` +
+    `${availableMeasured ? "" : " (estimated — /proc/meminfo could not be read)"}` +
+    `${diskFreeBytes === null ? "" : `, ${megabytes(diskFreeBytes)} free on disk`}`
   );
 }
 
@@ -133,13 +217,25 @@ export function describeMemory({ process: usage, availableBytes, availableMeasur
  * @param {Object} options
  * @param {(message: string) => void} options.log
  * @param {() => { name: string, residentBytes: number, budgetBytes: number }[]} [options.readStores]
+ * @param {"process" | "thread"} [options.scope] - `thread` leaves out the
+ *   process-wide figures, so the torrent worker can report its own isolate
+ *   without reading /proc twice.
+ * @param {string} [options.label] - Which thread the isolate figures are of.
+ * @param {string} [options.diskPath] - Where pieces spill, for the free-space
+ *   reading. Omitted, the disk term is left out rather than guessed.
  * @param {number} [options.intervalMs]
  * @returns {{ stop: () => void }}
  */
-export function startMemoryReport({ log, readStores, intervalMs = MEMORY_REPORT_INTERVAL_MS }) {
+export function startMemoryReport({
+  log,
+  readStores,
+  scope = "process",
+  label = "",
+  diskPath = "",
+  intervalMs = MEMORY_REPORT_INTERVAL_MS
+}) {
   const tick = async () => {
     try {
-      const { bytes, measured } = await availableMemory();
       let stores = [];
       try {
         stores = typeof readStores === "function" ? readStores() ?? [] : [];
@@ -147,10 +243,19 @@ export function startMemoryReport({ log, readStores, intervalMs = MEMORY_REPORT_
         // silent-ok: a store list that cannot be read must not stop the reading
         // that matters, which is the process's own.
       }
+      if (scope === "thread") {
+        log(describeMemory({ scope, label, process: readProcessMemory(), stores }));
+        return;
+      }
+      const { bytes, measured } = await availableMemory();
       log(describeMemory({
+        scope,
+        label,
         process: readProcessMemory(),
         availableBytes: bytes,
         availableMeasured: measured,
+        anonymousBytes: await readAnonymousMemory(),
+        diskFreeBytes: diskPath ? await readDiskFree(diskPath) : null,
         stores
       }));
     } catch {