@torrent-tv/proxy 2.87.21 → 2.88.0

package/services/storage/files/piece-from-whole-file.js

@@ -1,118 +1,118 @@
-/**
- * @file Reading one piece of a torrent out of the files it has already been
- * assembled into.
- *
- * THE KEYSTONE OF KEEPING WHOLE FILES AT ALL. Without it a whole file is a
- * second copy of bytes the piece store is also holding, and neither copy can be
- * dropped: the store cannot drop its own because it is what every piece read
- * goes to, and the file cannot be dropped because it is what a torrent-free read
- * goes to. With it the store has a place to fall back to, so
- *
- *   1. the spilled copy of a whole file is redundant and can go — the film stops
- *      being on the disk twice, which on the field host of 2026-09-11 was
- *      1417 MB of segments plus 1424 MB of spilled pieces for one episode;
- *   2. the torrent can be destroyed with its store and added again later
- *      without fetching a byte: what it verifies, it reads from here.
- *
- * A piece is a byte range of the torrent, and the torrent's files are laid end
- * to end in that same space — so a piece belongs to one file, or straddles the
- * boundary between two. Both cases are the same walk.
- */
-
-import fs from "node:fs/promises";
-
-/**
- * Read one piece out of whole files, or answer null.
- *
- * Null when any part of the piece is in a file this proxy does not hold whole:
- * a piece half read is worse than a piece not read, because the layer above
- * would hash it and mark the piece bad.
- *
- * @param {object} params
- * @param {number} params.index - The piece.
- * @param {number} params.pieceLength - Every piece but the last is this long.
- * @param {number} params.length - What the whole torrent weighs.
- * @param {Array<{ offset: number, length: number }>} params.files - The
- *   torrent's files in order, as it lays them out.
- * @param {(fileIndex: number) => { path: string, length: number } | null} params.wholeFileAt
- * @returns {Promise<Buffer | null>}
- */
-export async function pieceFromWholeFiles({ index, pieceLength, length, files, wholeFileAt }) {
-  if (!Array.isArray(files) || files.length === 0 || !(pieceLength > 0)) {
-    return null;
-  }
-  const pieceStart = index * pieceLength;
-  const pieceEnd = Math.min(pieceStart + pieceLength, length) - 1;
-  if (pieceStart > pieceEnd) {
-    return null;
-  }
-  const piece = Buffer.allocUnsafe(pieceEnd - pieceStart + 1);
-  let filled = 0;
-  for (const [fileIndex, file] of files.entries()) {
-    const fileStart = Number(file?.offset ?? 0);
-    const fileEnd = fileStart + Number(file?.length ?? 0) - 1;
-    const from = Math.max(pieceStart, fileStart);
-    const to = Math.min(pieceEnd, fileEnd);
-    if (from > to) {
-      continue;
-    }
-    const whole = wholeFileAt(fileIndex);
-    if (!whole) {
-      // Part of this piece is in a file this proxy does not hold whole.
-      return null;
-    }
-    let handle = null;
-    try {
-      handle = await fs.open(whole.path, "r");
-      const { bytesRead } = await handle.read(piece, from - pieceStart, to - from + 1, from - fileStart);
-      if (bytesRead !== to - from + 1) {
-        return null;
-      }
-      filled += bytesRead;
-    } catch {
-      return null;
-    } finally {
-      await handle?.close().catch(() => undefined);
-    }
-  }
-  return filled === piece.length ? piece : null;
-}
-
-/**
- * Whether every byte of one piece is in files this proxy holds whole.
- *
- * Asked before dropping a spilled copy, and answered without reading anything.
- *
- * @param {object} params
- * @param {number} params.index
- * @param {number} params.pieceLength
- * @param {number} params.length
- * @param {Array<{ offset: number, length: number }>} params.files
- * @param {(fileIndex: number) => { path: string, length: number } | null} params.wholeFileAt
- * @returns {boolean}
- */
-export function pieceIsInWholeFiles({ index, pieceLength, length, files, wholeFileAt }) {
-  if (!Array.isArray(files) || files.length === 0 || !(pieceLength > 0)) {
-    return false;
-  }
-  const pieceStart = index * pieceLength;
-  const pieceEnd = Math.min(pieceStart + pieceLength, length) - 1;
-  if (pieceStart > pieceEnd) {
-    return false;
-  }
-  let covered = 0;
-  for (const [fileIndex, file] of files.entries()) {
-    const fileStart = Number(file?.offset ?? 0);
-    const fileEnd = fileStart + Number(file?.length ?? 0) - 1;
-    const from = Math.max(pieceStart, fileStart);
-    const to = Math.min(pieceEnd, fileEnd);
-    if (from > to) {
-      continue;
-    }
-    if (!wholeFileAt(fileIndex)) {
-      return false;
-    }
-    covered += to - from + 1;
-  }
-  return covered === pieceEnd - pieceStart + 1;
-}
+/**
+ * @file Reading one piece of a torrent out of the files it has already been
+ * assembled into.
+ *
+ * THE KEYSTONE OF KEEPING WHOLE FILES AT ALL. Without it a whole file is a
+ * second copy of bytes the piece store is also holding, and neither copy can be
+ * dropped: the store cannot drop its own because it is what every piece read
+ * goes to, and the file cannot be dropped because it is what a torrent-free read
+ * goes to. With it the store has a place to fall back to, so
+ *
+ *   1. the spilled copy of a whole file is redundant and can go — the film stops
+ *      being on the disk twice, which on the field host of 2026-09-11 was
+ *      1417 MB of segments plus 1424 MB of spilled pieces for one episode;
+ *   2. the torrent can be destroyed with its store and added again later
+ *      without fetching a byte: what it verifies, it reads from here.
+ *
+ * A piece is a byte range of the torrent, and the torrent's files are laid end
+ * to end in that same space — so a piece belongs to one file, or straddles the
+ * boundary between two. Both cases are the same walk.
+ */
+
+import fs from "node:fs/promises";
+
+/**
+ * Read one piece out of whole files, or answer null.
+ *
+ * Null when any part of the piece is in a file this proxy does not hold whole:
+ * a piece half read is worse than a piece not read, because the layer above
+ * would hash it and mark the piece bad.
+ *
+ * @param {object} params
+ * @param {number} params.index - The piece.
+ * @param {number} params.pieceLength - Every piece but the last is this long.
+ * @param {number} params.length - What the whole torrent weighs.
+ * @param {Array<{ offset: number, length: number }>} params.files - The
+ *   torrent's files in order, as it lays them out.
+ * @param {(fileIndex: number) => { path: string, length: number } | null} params.wholeFileAt
+ * @returns {Promise<Buffer | null>}
+ */
+export async function pieceFromWholeFiles({ index, pieceLength, length, files, wholeFileAt }) {
+  if (!Array.isArray(files) || files.length === 0 || !(pieceLength > 0)) {
+    return null;
+  }
+  const pieceStart = index * pieceLength;
+  const pieceEnd = Math.min(pieceStart + pieceLength, length) - 1;
+  if (pieceStart > pieceEnd) {
+    return null;
+  }
+  const piece = Buffer.allocUnsafe(pieceEnd - pieceStart + 1);
+  let filled = 0;
+  for (const [fileIndex, file] of files.entries()) {
+    const fileStart = Number(file?.offset ?? 0);
+    const fileEnd = fileStart + Number(file?.length ?? 0) - 1;
+    const from = Math.max(pieceStart, fileStart);
+    const to = Math.min(pieceEnd, fileEnd);
+    if (from > to) {
+      continue;
+    }
+    const whole = wholeFileAt(fileIndex);
+    if (!whole) {
+      // Part of this piece is in a file this proxy does not hold whole.
+      return null;
+    }
+    let handle = null;
+    try {
+      handle = await fs.open(whole.path, "r");
+      const { bytesRead } = await handle.read(piece, from - pieceStart, to - from + 1, from - fileStart);
+      if (bytesRead !== to - from + 1) {
+        return null;
+      }
+      filled += bytesRead;
+    } catch {
+      return null;
+    } finally {
+      await handle?.close().catch(() => undefined);
+    }
+  }
+  return filled === piece.length ? piece : null;
+}
+
+/**
+ * Whether every byte of one piece is in files this proxy holds whole.
+ *
+ * Asked before dropping a spilled copy, and answered without reading anything.
+ *
+ * @param {object} params
+ * @param {number} params.index
+ * @param {number} params.pieceLength
+ * @param {number} params.length
+ * @param {Array<{ offset: number, length: number }>} params.files
+ * @param {(fileIndex: number) => { path: string, length: number } | null} params.wholeFileAt
+ * @returns {boolean}
+ */
+export function pieceIsInWholeFiles({ index, pieceLength, length, files, wholeFileAt }) {
+  if (!Array.isArray(files) || files.length === 0 || !(pieceLength > 0)) {
+    return false;
+  }
+  const pieceStart = index * pieceLength;
+  const pieceEnd = Math.min(pieceStart + pieceLength, length) - 1;
+  if (pieceStart > pieceEnd) {
+    return false;
+  }
+  let covered = 0;
+  for (const [fileIndex, file] of files.entries()) {
+    const fileStart = Number(file?.offset ?? 0);
+    const fileEnd = fileStart + Number(file?.length ?? 0) - 1;
+    const from = Math.max(pieceStart, fileStart);
+    const to = Math.min(pieceEnd, fileEnd);
+    if (from > to) {
+      continue;
+    }
+    if (!wholeFileAt(fileIndex)) {
+      return false;
+    }
+    covered += to - from + 1;
+  }
+  return covered === pieceEnd - pieceStart + 1;
+}

package/services/storage/free.js

@@ -1,71 +1,71 @@
-/**
- * @file How much room the disk holding a directory has.
- *
- * Separate from the plain `statfs` reading because of one case that is the
- * normal one, not an edge: the directory may not exist yet. The segments live
- * under `os.tmpdir()/torrent-tv-hls`, which is made when the first session is
- * created and removed when the proxy stops — so at every start, and after every
- * clean exit, `statfs` on it fails. Field 2026-09-10: the first reading said
- * `disk: 0MB free` on a host with 103 GB, and zero means "no room" to everything
- * that reads it.
- *
- * The disk is the same disk whether or not that directory has been made yet, so
- * the answer is the nearest ancestor that exists.
- */
-
-import { statfs } from "node:fs/promises";
-import { statSync } from "node:fs";
-import path from "node:path";
-
-/**
- * @param {string} directory
- * @returns {Promise<number | null>} Bytes free, or null where nothing answered.
- */
-export async function freeBytesFor(directory) {
-  let at = path.resolve(directory);
-  for (let depth = 0; depth < 16; depth += 1) {
-    try {
-      const stats = await statfs(at);
-      return Number(stats.bavail) * Number(stats.bsize);
-    } catch {
-      const up = path.dirname(at);
-      if (up === at) {
-        return null;
-      }
-      at = up;
-    }
-  }
-  return null;
-}
-
-/**
- * Which device holds a directory, so claimants on one disk are told apart from
- * claimants on another.
- *
- * A RESOURCE IS WHAT CANNOT BE SUBSTITUTED, and two filesystems are two of
- * them. Measured on the addon host 2026-09-05: `/tmp`, where the segments and
- * the spill live, is the overlay (`dev=68`); `/data`, where the evidence lives,
- * is ext4 on the nvme (`dev=66305`). Dividing one figure between claimants on
- * both gives each a share of a disk it does not write to.
- *
- * The nearest ancestor that exists, for the same reason `freeBytesFor` walks
- * up: a claimant's own directory is often made later than this is asked.
- *
- * @param {string} directory
- * @returns {string} A name for the resource, stable for the life of the mount.
- */
-export function deviceOf(directory) {
-  let at = path.resolve(directory);
-  for (let depth = 0; depth < 16; depth += 1) {
-    try {
-      return `disk:${statSync(at).dev}`;
-    } catch {
-      const up = path.dirname(at);
-      if (up === at) {
-        return "disk:unknown";
-      }
-      at = up;
-    }
-  }
-  return "disk:unknown";
-}
+/**
+ * @file How much room the disk holding a directory has.
+ *
+ * Separate from the plain `statfs` reading because of one case that is the
+ * normal one, not an edge: the directory may not exist yet. The segments live
+ * under `os.tmpdir()/torrent-tv-hls`, which is made when the first session is
+ * created and removed when the proxy stops — so at every start, and after every
+ * clean exit, `statfs` on it fails. Field 2026-09-10: the first reading said
+ * `disk: 0MB free` on a host with 103 GB, and zero means "no room" to everything
+ * that reads it.
+ *
+ * The disk is the same disk whether or not that directory has been made yet, so
+ * the answer is the nearest ancestor that exists.
+ */
+
+import { statfs } from "node:fs/promises";
+import { statSync } from "node:fs";
+import path from "node:path";
+
+/**
+ * @param {string} directory
+ * @returns {Promise<number | null>} Bytes free, or null where nothing answered.
+ */
+export async function freeBytesFor(directory) {
+  let at = path.resolve(directory);
+  for (let depth = 0; depth < 16; depth += 1) {
+    try {
+      const stats = await statfs(at);
+      return Number(stats.bavail) * Number(stats.bsize);
+    } catch {
+      const up = path.dirname(at);
+      if (up === at) {
+        return null;
+      }
+      at = up;
+    }
+  }
+  return null;
+}
+
+/**
+ * Which device holds a directory, so claimants on one disk are told apart from
+ * claimants on another.
+ *
+ * A RESOURCE IS WHAT CANNOT BE SUBSTITUTED, and two filesystems are two of
+ * them. Measured on the addon host 2026-09-05: `/tmp`, where the segments and
+ * the spill live, is the overlay (`dev=68`); `/data`, where the evidence lives,
+ * is ext4 on the nvme (`dev=66305`). Dividing one figure between claimants on
+ * both gives each a share of a disk it does not write to.
+ *
+ * The nearest ancestor that exists, for the same reason `freeBytesFor` walks
+ * up: a claimant's own directory is often made later than this is asked.
+ *
+ * @param {string} directory
+ * @returns {string} A name for the resource, stable for the life of the mount.
+ */
+export function deviceOf(directory) {
+  let at = path.resolve(directory);
+  for (let depth = 0; depth < 16; depth += 1) {
+    try {
+      return `disk:${statSync(at).dev}`;
+    } catch {
+      const up = path.dirname(at);
+      if (up === at) {
+        return "disk:unknown";
+      }
+      at = up;
+    }
+  }
+  return "disk:unknown";
+}

package/services/storage/keep.js

@@ -1,48 +1,48 @@
-/**
- * @file How long material nobody is using is kept.
- *
- * ONE NUMBER, IN ONE PLACE, because everything it governs stands for the same
- * unmeasured thing: whether the viewer comes back. Everything else in the
- * decision is measured or measurable — re-downloading a piece from the swarm is
- * ~1430 ms on the field host, re-making a segment is its own encode time, and
- * the disk now has an owner that prices holding it. Only the return is unknown,
- * and a period is what stands in for it.
- *
- * IT WAS THREE NUMBERS AND THEY CONTRADICTED EACH OTHER (read 2026-09-10):
- *
- *   torrent and its downloaded bytes   15 minutes
- *   session                            30 minutes
- *   produced segments                   6 hours
- *
- * The torrent therefore went at fifteen minutes while the session it feeds
- * lived to thirty, so between them there was a session with no source: a viewer
- * returning at the twentieth minute got a session that could not make a single
- * new segment until the torrent was added again. That is not two answers to one
- * question, it is a contradiction — and it is what two independent guesses about
- * one unknown produce.
- *
- * With one hour for both kinds of material the session dies first, which is the
- * right order and needs no rule of its own to enforce.
- *
- * WHY AN HOUR, honestly: nothing derives it. It is a stand-in, chosen to be
- * long enough that an interruption — a phone call, a meal — does not cost the
- * film, and short enough that a household disk is not held for a day by
- * somebody who is not coming back. It is the OWNER'S disk, and holding
- * gigabytes on it because there happens to be room is taking something that is
- * not ours.
- *
- * WHAT REPLACES IT, and the proxy is already in a position to measure it: every
- * session opened on an output whose segments are still on disk IS a return, and
- * its age is known. `services/disk/returns.js` records them. A week of those and
- * the distribution answers this directly — keep material for as long as returns
- * actually happen — and then the two kinds can have different numbers, since
- * their costs of coming back differ.
- */
-
-/**
- * How long material nobody has read is kept, in milliseconds.
- *
- * Read by the torrent pool for a torrent and its downloaded bytes, and by the
- * session manager for the segments an encoder produced.
- */
-export const IDLE_KEEP_MS = 60 * 60 * 1000;
+/**
+ * @file How long material nobody is using is kept.
+ *
+ * ONE NUMBER, IN ONE PLACE, because everything it governs stands for the same
+ * unmeasured thing: whether the viewer comes back. Everything else in the
+ * decision is measured or measurable — re-downloading a piece from the swarm is
+ * ~1430 ms on the field host, re-making a segment is its own encode time, and
+ * the disk now has an owner that prices holding it. Only the return is unknown,
+ * and a period is what stands in for it.
+ *
+ * IT WAS THREE NUMBERS AND THEY CONTRADICTED EACH OTHER (read 2026-09-10):
+ *
+ *   torrent and its downloaded bytes   15 minutes
+ *   session                            30 minutes
+ *   produced segments                   6 hours
+ *
+ * The torrent therefore went at fifteen minutes while the session it feeds
+ * lived to thirty, so between them there was a session with no source: a viewer
+ * returning at the twentieth minute got a session that could not make a single
+ * new segment until the torrent was added again. That is not two answers to one
+ * question, it is a contradiction — and it is what two independent guesses about
+ * one unknown produce.
+ *
+ * With one hour for both kinds of material the session dies first, which is the
+ * right order and needs no rule of its own to enforce.
+ *
+ * WHY AN HOUR, honestly: nothing derives it. It is a stand-in, chosen to be
+ * long enough that an interruption — a phone call, a meal — does not cost the
+ * film, and short enough that a household disk is not held for a day by
+ * somebody who is not coming back. It is the OWNER'S disk, and holding
+ * gigabytes on it because there happens to be room is taking something that is
+ * not ours.
+ *
+ * WHAT REPLACES IT, and the proxy is already in a position to measure it: every
+ * session opened on an output whose segments are still on disk IS a return, and
+ * its age is known. `services/disk/returns.js` records them. A week of those and
+ * the distribution answers this directly — keep material for as long as returns
+ * actually happen — and then the two kinds can have different numbers, since
+ * their costs of coming back differ.
+ */
+
+/**
+ * How long material nobody has read is kept, in milliseconds.
+ *
+ * Read by the torrent pool for a torrent and its downloaded bytes, and by the
+ * session manager for the segments an encoder produced.
+ */
+export const IDLE_KEEP_MS = 60 * 60 * 1000;

package/services/storage/machine-memory.js

@@ -1,56 +1,56 @@
-/**
- * @file How much of the machine's memory is available, read once.
- *
- * It was written THREE TIMES, in three layers, with the same body each time:
- * `transport/health-collector.js` for the score a proxy publishes to the registry,
- * `storage/memory-report.js` for the line the process prints every second, and
- * `storage/piece-store/shared-piece-store.js` for the budget the piece store takes.
- * One fact, three owners — and the copies had already drifted once: the piece
- * store was corrected from `os.freemem()` to the kernel's own estimate on
- * 2026-08-27 and the health collector went on publishing the wrong quantity
- * until 2026-09-02, so every Linux proxy in the pool understated itself, each
- * by a different amount according to how much cache it happened to hold.
- *
- * It lives in the storage layer because it is a fact about the RESOURCE, and
- * this layer is the resource's owner: what is free, what we already hold, and
- * what everything that is not us has been seen to need.
- *
- * **Why `MemAvailable` and not `os.freemem()`.** On Linux `freemem` counts only
- * the pages free at that instant, and the kernel deliberately keeps that number
- * low by filling the rest with reclaimable cache — so a machine reads as nearly
- * full while it has gigabytes to give. `MemAvailable` is the kernel's own
- * estimate of what an allocation could actually obtain. Where there is no
- * `/proc` — not Linux, or it is unreadable — `freemem` is the best answer there
- * is, and on those systems it is not misleading.
- */
-
-import { readFileSync } from "node:fs";
-import os from "node:os";
-
-/**
- * What the machine could give an allocation right now.
- *
- * @returns {{ bytes: number, measured: boolean }} `measured` is false where the
- *   kernel's own estimate was not available, so a caller that prints the figure
- *   can say which of the two it is holding.
- */
-export function availableMemory() {
-  try {
-    const match = /^MemAvailable:\s+(\d+)\s+kB$/m.exec(readFileSync("/proc/meminfo", "utf8"));
-    if (match) {
-      return { bytes: Number(match[1]) * 1024, measured: true };
-    }
-  } catch {
-    // silent-ok: not Linux, or /proc is not readable.
-  }
-  return { bytes: os.freemem(), measured: false };
-}
-
-/**
- * What the machine could give an allocation right now, as a plain number.
- *
- * @returns {number}
- */
-export function availableMemoryBytes() {
-  return availableMemory().bytes;
-}
+/**
+ * @file How much of the machine's memory is available, read once.
+ *
+ * It was written THREE TIMES, in three layers, with the same body each time:
+ * `transport/health-collector.js` for the score a proxy publishes to the registry,
+ * `storage/memory-report.js` for the line the process prints every second, and
+ * `storage/piece-store/shared-piece-store.js` for the budget the piece store takes.
+ * One fact, three owners — and the copies had already drifted once: the piece
+ * store was corrected from `os.freemem()` to the kernel's own estimate on
+ * 2026-08-27 and the health collector went on publishing the wrong quantity
+ * until 2026-09-02, so every Linux proxy in the pool understated itself, each
+ * by a different amount according to how much cache it happened to hold.
+ *
+ * It lives in the storage layer because it is a fact about the RESOURCE, and
+ * this layer is the resource's owner: what is free, what we already hold, and
+ * what everything that is not us has been seen to need.
+ *
+ * **Why `MemAvailable` and not `os.freemem()`.** On Linux `freemem` counts only
+ * the pages free at that instant, and the kernel deliberately keeps that number
+ * low by filling the rest with reclaimable cache — so a machine reads as nearly
+ * full while it has gigabytes to give. `MemAvailable` is the kernel's own
+ * estimate of what an allocation could actually obtain. Where there is no
+ * `/proc` — not Linux, or it is unreadable — `freemem` is the best answer there
+ * is, and on those systems it is not misleading.
+ */
+
+import { readFileSync } from "node:fs";
+import os from "node:os";
+
+/**
+ * What the machine could give an allocation right now.
+ *
+ * @returns {{ bytes: number, measured: boolean }} `measured` is false where the
+ *   kernel's own estimate was not available, so a caller that prints the figure
+ *   can say which of the two it is holding.
+ */
+export function availableMemory() {
+  try {
+    const match = /^MemAvailable:\s+(\d+)\s+kB$/m.exec(readFileSync("/proc/meminfo", "utf8"));
+    if (match) {
+      return { bytes: Number(match[1]) * 1024, measured: true };
+    }
+  } catch {
+    // silent-ok: not Linux, or /proc is not readable.
+  }
+  return { bytes: os.freemem(), measured: false };
+}
+
+/**
+ * What the machine could give an allocation right now, as a plain number.
+ *
+ * @returns {number}
+ */
+export function availableMemoryBytes() {
+  return availableMemory().bytes;
+}