@torrent-tv/proxy 2.64.4 → 2.64.6

package/CHANGELOG.md

@@ -1,3 +1,25 @@
+## 2.64.6
+
+- **New**: The torrent worker reads its own memory once a SECOND, and writes a line only when something moved. A minute cannot see what kills it: three times — 2026-08-30 14:00 and 23:19, 2026-08-31 13:27 — the worker's own line read `heap=28-36MB`, and by the sample after next the thread had been terminated for reaching its heap ceiling, with the whole rise fitting inside a single sixty-second gap. The reading and the line are now separate cadences: taken every second, written when the heap has moved by 25 MB or when a quiet minute is up, so a healthy session costs the same one line a minute it costs today and a runaway is a curve rather than a step.
+- **New**: A heap snapshot of the WORKER's own isolate, on every new high-water above 400 MB, into the state directory, three kept. Every snapshot ever written by this proxy has been of the MAIN isolate — `v8.writeHeapSnapshot` snapshots the thread that calls it, and the main thread's heap is 26 MB while the one that dies climbs to 2240 MB. So the isolate that has died three times has never once been looked at, and the question "what is holding this memory" has had no way to be answered. Deliberately NOT taken as the ceiling is approached: a snapshot is about the size of the heap it is of, so asking for one at 1.9 GB on a machine with 600 MB left is a way to cause the kill being studied — and at one reading a second no 400 MB step is ever missed. `stateDir` now travels to the worker for this, because a worker cannot change the process's working directory and had no way to choose where a file lands.
+- **New**: The memory line says the heap ceiling beside the heap — `heap=1800MB/1904MB of 2240MB allowed`. That ceiling is what the runtime terminates a thread for reaching, it is inherited from the main isolate by a worker created without `resourceLimits`, and without it the log said "30MB" with no way to tell how far that was from the end.
+
+- **Fix**: Room for a piece in the store is an owned reservation, released in a `finally`, instead of a number one function increments and another decrements. Every consequence of the old pairing was a defect, and all of them are gone with it: a failure between `#claimSlot` and `#registerPiece` — a disk read that throws — lost a slot for the life of the process, because there was no `try/finally` anywhere on that path; `put`'s error path tried to correct that by guessing, and its own comments said so ("Heuristic:", "We conservatively decrement"), so it could take back a reservation belonging to a different claim in flight and let the store admit past its allowance until the next minute's revision evicted the excess. `stats()` now reports `outstanding`, and the periodic `piece-store` line prints it when it is not zero: a reservation that never comes back is invisible until the store cannot admit anything, and by then the reason is long gone.
+- **Fix**: A claim waits on PROGRESS, not on activity. The five-second "every resident piece is pinned" error was skipped entirely while a spill was in flight or any reservation was held, so ONE lost reservation from the defect above made that error permanently unreachable and a read retried every 50 ms for the rest of the process's life — never completing, never failing, and never saying anything. The clock now restarts when something actually moves (a piece admitted, a spill finished, a pin released) and the error is raised when nothing has moved for five seconds, whatever is nominally in flight.
+- **Fix**: The wait between attempts allocates once instead of once per pending spill. It attached a fresh pair of handlers to EVERY spill in flight on EVERY attempt and left an uncancelled timer behind each time, so a claim that could not be satisfied allocated in proportion to attempts times spills. One idempotent handler now, its timer cleared when it is woken, and a settling spill wakes the store itself — which is where that belonged, and which `#claimSlotOnce`'s own spills were not doing at all.
+- **Fix**: Closing or destroying the store wakes whoever is waiting for room, and a claim checks for a closed store on every attempt. Callers inside `#claimSlot` were simply left asleep for ever.
+- **Fix**: A piece handed back to memory while its own spill is still being written no longer reappears on disk. `DiskTier.write` records the index when it COMPLETES, and `put` called `forget` before that, so the completing write put the stale copy back and a later read returned bytes from before the rewrite. `put` now waits for that piece's spill to finish before forgetting it.
+- **Fix**: A spill that fails while the allowance is being lowered is counted (`spill-failures` in the store's line) instead of thrown into nothing. Nobody awaits those spills, so the rethrow was an unhandled rejection, and an unhandled rejection in the torrent worker ends the thread — a second way to lose the torrent client on top of the one being investigated.
+- **Fix**: Two concurrent revivals of the same piece no longer each allocate and register a buffer for it, leaving whoever holds the first reading memory the store has stopped tracking. The second finds the piece already back and uses it.
+- **Fix**: `PieceLru` follows the store's live allowance. It was built with the capacity the store was created with and never revised, so `isFull()` answered against a number that had stopped being the limit — dormant only because nothing calls it today.
+- **Chore**: The store accepts an injected disk tier so a test can hold a write open or make one fail on purpose. Four of the defects above live in what happens when the disk does not answer at once, and none of them was reachable from outside before (`test/piece-store-reservations.test.js`).
+
+All eight were found by reading the file after the torrent worker was killed by its own JS heap limit on 2026-08-31 (`research/worker-heap-oom-2026-08-31.md`, §5). None of them is proven to be that growth; they are what the reading found, and each is a defect in its own right.
+
+## 2.64.5
+
+- **Fix**: A rung measured at 0.007x is no longer kept just because it is on screen. The `playingHeight` exemption is now checked after the `measured < 1` withdrawal, so a 4K HEVC transcode at 0.007x on a CM4 (field 2026-08-31, 0.1x at 23:45 and 0.007x at 06:57, 0.04s buffered) is withdrawn and the offer can become empty instead of stalling the viewer with no way to downgrade. `ownHeight` is kept only for a copied source (`!transcodeVideo`), not for a re-encode already running at 0.18x.
+
 ## 2.64.4
 
 - **Fix**: Piece store holds one `SharedArrayBuffer` per resident piece instead of a single growable pool that only ever grew. Evicting a piece deletes its buffer and the memory is reclaimable by GC — `committed` is now `resident * chunkLength`, not a high-water. On the field host a 6-piece 8 MiB overflow kept 48 MB committed; now it keeps 32 MB (roadmap 2).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@torrent-tv/proxy",
-  "version": "2.64.4",
+  "version": "2.64.6",
   "description": "Torrent proxy client that exposes webseed-like HTTP stream endpoint.",
   "license": "GPL-3.0-or-later",
   "publishConfig": {

package/server.js

@@ -116,7 +116,7 @@ export async function startProxyServer({
   // idled. Serving a segment shared that thread, so reading an already-finished
   // 10 MB file took 12-23 s against 125 ms to hand it to the channel. The
   // adapter keeps TorrentPool's interface, so nothing downstream changed.
-  const torrentPool = new WorkerTorrentPool({ maxDiskBytes, memoryBytes, onSubtitleCues });
+  const torrentPool = new WorkerTorrentPool({ maxDiskBytes, memoryBytes, stateDir, onSubtitleCues });
   const selectedPort = await getPort({
     port: buildPortCandidates(port)
   });

package/services/hls-session-manager.js

@@ -7529,32 +7529,35 @@ export class HlsSessionManager {
     /** @type {Map<number, number | null>} */
     const predictedByHeight = new Map();
     for (const height of heights) {
-      // The rung ON SCREEN is never withdrawn, whatever anything says about it:
-      // every route guard reads this list, so dropping it would 404 the next
-      // segment of a stream that is playing.
-      if (height === playingHeight) {
-        kept.push(height);
-        continue;
-      }
       // A rung this session has actually been seen running below realtime is
       // withdrawn on that evidence, whatever the prediction says. This is the
-      // one thing a live reading is authority on: itself — and it is asked
-      // BEFORE the exemptions below, which it did not used to be.
-      //
-      // That order was harmless while a step rewrote the encode inside the base
-      // and the viewer never left it: `ownHeight` then always WAS the rung on
-      // screen. Now a step moves the viewer to another variant, and the height
-      // they left goes on being exempt although nothing is producing it — so
-      // the step back up would ask for the one rung this machine has been
-      // measured failing at, then fail again, then step down, for ever. The
-      // copied source height cannot reach this: `#measuredRungSpeeds` records
-      // only sessions that re-encode, so a copy has no reading to be withdrawn
-      // on, which is right — it costs no encoder.
+      // one thing a live reading is authority on: itself. It is asked before
+      // any exemption so a rung measured failing while on screen does not stay
+      // offered because it was on screen when measured — otherwise a step
+      // would ask for the one rung this machine has been measured failing at,
+      // then fail again, then step down, for ever. A copied source height
+      // cannot reach this: `#measuredRungSpeeds` records only sessions that
+      // re-encode, so a copy has no reading to be withdrawn on, which is right
+      // — it costs no encoder.
       const measured = measuredHeights?.get(height) ?? null;
       if (measured !== null && measured < 1) {
+        // Even the rung on screen is withdrawn on measured failure: keeping it
+        // would 404 the next segment, but keeping a rung measured at 0.007x
+        // (field 2026-08-31, 4K HEVC on CM4) stalls the viewer for minutes with
+        // 0.04s buffered and no way to downgrade because every other rung is
+        // also dropped. Withdrawing it lets the offer become empty, which the
+        // caller turns into an error the viewer can act on (try another proxy
+        // or a lower source) instead of an endless spinner.
         dropped.push(`${height}p=${measured.toFixed(2)}x measured`);
         continue;
       }
+      // The rung ON SCREEN is kept only when it has not been measured failing
+      // above. Keeping a rung measured at 0.007x would stall the viewer with
+      // no path to a faster rung, which is what the field showed.
+      if (height === playingHeight) {
+        kept.push(height);
+        continue;
+      }
       // The height an encoder is ALREADY producing, and the source's own height
       // when the FAMILY serves it by copy — neither has to be predicted,
       // because it is happening. A copied rung costs no encoder at all, so no
@@ -7567,9 +7570,13 @@ export class HlsSessionManager {
       // A source height that would have to be RE-ENCODED is a prediction like
       // any other: on a session whose budget stepped down to 480p, the source's
       // 1080p is neither copied nor being produced, and keeping it unpriced
-      // would offer exactly the kind of rung this refuses.
+      // would offer exactly the kind of rung this refuses. Likewise, a rung
+      // this session is already producing at 0.007x (field 2026-08-31, 4K HEVC
+      // on CM4, 0.1x at 23:45 and 0.007x at 06:57) is not sustainable just
+      // because it is running — keeping it offered no path to a faster rung
+      // and left the viewer at 0.04s buffered with no downgrade.
       if (
-        height === ownHeight ||
+        (height === ownHeight && !transcodeVideo) ||
         (height === sourceHeight && !transcodeVideo)
       ) {
         kept.push(height);

package/services/memory-report.js

@@ -19,7 +19,7 @@
  * runtime already maintains.
  */
 
-import { readFile, statfs } from "node:fs/promises";
+import { readdir, readFile, rm, statfs } from "node:fs/promises";
 import os from "node:os";
 import v8 from "node:v8";
 import path from "node:path";
@@ -27,6 +27,18 @@ import path from "node:path";
 /** How often the reading is taken and written. */
 export const MEMORY_REPORT_INTERVAL_MS = 60_000;
 
+/**
+ * How often the torrent worker takes its own reading.
+ *
+ * A minute cannot see what killed it. Three times — 2026-08-30 14:00 and 23:19,
+ * 2026-08-31 13:27 — the worker's heap read 28-36 MB in one sample and the
+ * thread was dead by the sample after next, with the whole rise from 30 MB to
+ * the 2240 MB heap limit fitting inside a single gap. A second is short enough
+ * that the rise is a curve rather than a step, and the line is only WRITTEN when
+ * something moved, so a quiet session costs what it costs today.
+ */
+export const WORKER_MEMORY_SAMPLE_MS = 1_000;
+
 /**
  * What the process is holding, from the runtime's own counters.
  *
@@ -36,16 +48,30 @@ export const MEMORY_REPORT_INTERVAL_MS = 60_000;
  * since torrent pieces sit in a `SharedArrayBuffer` and segment bodies pass
  * through buffers.
  *
- * @returns {{ rss: number, heapUsed: number, heapTotal: number, external: number, arrayBuffers: number }}
+ * `heapLimit` is this isolate's own ceiling, and it belongs beside the heap
+ * figures because it is what the runtime kills the thread for reaching — a
+ * worker created without `resourceLimits` inherits the main isolate's, 2240 MB
+ * on the addon host. Without it the log said 30 MB and gave no idea how far
+ * that was from the end.
+ *
+ * @returns {{ rss: number, heapUsed: number, heapTotal: number, external: number, arrayBuffers: number, heapLimit: number }}
  */
 export function readProcessMemory() {
   const usage = process.memoryUsage();
+  let heapLimit = 0;
+  try {
+    heapLimit = v8.getHeapStatistics().heap_size_limit ?? 0;
+  } catch {
+    // silent-ok: a missing ceiling leaves the term out, it does not cost the
+    // reading beside it.
+  }
   return {
     rss: usage.rss,
     heapUsed: usage.heapUsed,
     heapTotal: usage.heapTotal,
     external: usage.external,
-    arrayBuffers: usage.arrayBuffers ?? 0
+    arrayBuffers: usage.arrayBuffers ?? 0,
+    heapLimit
   };
 }
 
@@ -198,7 +224,8 @@ export function describeMemory({
       `committed ${megabytes(storeCommitted)} of ${megabytes(storeBudget)} allowed, ` +
       `${megabytes(storeSpilled)} spilled to disk`;
   const isolate =
-    `heap=${megabytes(usage.heapUsed)}/${megabytes(usage.heapTotal)} ` +
+    `heap=${megabytes(usage.heapUsed)}/${megabytes(usage.heapTotal)}` +
+    `${usage.heapLimit ? ` of ${megabytes(usage.heapLimit)} allowed` : ""} ` +
     `external=${megabytes(usage.external)} arrayBuffers=${megabytes(usage.arrayBuffers)}`;
   if (scope === "thread") {
     return `memory (${label || "thread"}): ${isolate}; ${storesPart}`;
@@ -213,6 +240,39 @@ export function describeMemory({
   );
 }
 
+/**
+ * Whether this reading is worth writing down, and why.
+ *
+ * A series taken every second and printed every second is unreadable, and one
+ * printed every minute cannot see a rise that takes forty seconds. So the
+ * cadence of the READING and the cadence of the LINE are separate: the figure
+ * is taken often, and written when it has moved or when the quiet interval has
+ * passed. Pure, so the rule can be pinned without a clock.
+ *
+ * @param {Object} state
+ * @param {number} state.watchedBytes - The figure this scope is watching.
+ * @param {number} state.lastWrittenBytes
+ * @param {number} state.sinceWrittenMs
+ * @param {number} state.changeBytes - Movement that earns a line of its own.
+ * @param {number} state.quietMs - How long silence may last regardless.
+ * @returns {boolean}
+ */
+export function readingIsWorthWriting({
+  watchedBytes,
+  lastWrittenBytes,
+  sinceWrittenMs,
+  changeBytes,
+  quietMs
+}) {
+  if (quietMs <= 0 || sinceWrittenMs >= quietMs) {
+    return true;
+  }
+  if (changeBytes <= 0) {
+    return false;
+  }
+  return Math.abs(watchedBytes - lastWrittenBytes) >= changeBytes;
+}
+
 /**
  * Report memory on a timer until stopped.
  *
@@ -225,7 +285,17 @@ export function describeMemory({
  * @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]
+ * @param {number} [options.intervalMs] - How often the figure is READ.
+ * @param {number} [options.quietMs] - How long the line may stay silent while
+ *   nothing moves. Zero writes every reading, which is what the process scope
+ *   has always done.
+ * @param {number} [options.changeBytes] - Movement that earns a line before the
+ *   quiet interval is up.
+ * @param {string} [options.snapshotDir] - Where heap snapshots are written.
+ *   Defaults to the temporary directory, as the process scope always did.
+ * @param {number} [options.snapshotFloorBytes]
+ * @param {number} [options.snapshotGrowthBytes]
+ * @param {number} [options.keepSnapshots] - Newest to keep; zero keeps all.
  * @returns {{ stop: () => void }}
  */
 export function startMemoryReport({
@@ -234,9 +304,62 @@ export function startMemoryReport({
   scope = "process",
   label = "",
   diskPath = "",
-  intervalMs = MEMORY_REPORT_INTERVAL_MS
+  intervalMs = MEMORY_REPORT_INTERVAL_MS,
+  quietMs = 0,
+  changeBytes = 0,
+  snapshotDir = "",
+  snapshotFloorBytes = 500 * 1024 * 1024,
+  snapshotGrowthBytes = 100 * 1024 * 1024,
+  keepSnapshots = 0
 }) {
-  let highWaterRss = 0;
+  let highWater = 0;
+  let lastWrittenBytes = 0;
+  let lastWrittenAt = 0;
+  // The process watches what the kernel kills it for; a thread watches what the
+  // runtime kills IT for, which is its own heap and not the process's resident
+  // memory — the main isolate sat at 26 MB while the worker's heap climbed to
+  // its 2240 MB ceiling.
+  const watchedOf = (memory) => (scope === "thread" ? memory.heapTotal : memory.rss);
+  const slug = (label || scope).replace(/[^a-z0-9]+/gi, "-").toLowerCase();
+  const directory = snapshotDir || os.tmpdir();
+
+  /**
+   * @param {number} watchedBytes
+   * @param {string} why
+   * @returns {Promise<void>}
+   */
+  const takeSnapshot = async (watchedBytes, why) => {
+    let snapPath = "";
+    try {
+      snapPath = path.join(directory, `heap-${slug}-${Date.now()}-${watchedBytes}.heapsnapshot`);
+      // Synchronous and proportional to the heap, so it stops this thread for
+      // as long as it takes to write. That is the price of the only reading
+      // that names what is holding the memory, and it is why it is bounded by
+      // a floor, by a growth step and by how many are kept.
+      v8.writeHeapSnapshot(snapPath);
+      log(`memory: wrote heap snapshot of the ${label || scope} to ${snapPath} (${megabytes(watchedBytes)}, ${why})`);
+    } catch {
+      // silent-ok: no snapshot is worse than a snapshot, and much better than
+      // ending the series that leads to the next one.
+      return;
+    }
+    if (keepSnapshots <= 0) {
+      return;
+    }
+    try {
+      const prefix = `heap-${slug}-`;
+      const mine = (await readdir(directory))
+        .filter((name) => name.startsWith(prefix) && name.endsWith(".heapsnapshot"))
+        .sort();
+      for (const name of mine.slice(0, Math.max(0, mine.length - keepSnapshots))) {
+        await rm(path.join(directory, name), { force: true });
+      }
+    } catch {
+      // silent-ok: a snapshot that could not be pruned is a disk-space problem
+      // for later, not a reason to lose the one just written.
+    }
+  };
+
   const tick = async () => {
     try {
       let stores = [];
@@ -247,35 +370,57 @@ export function startMemoryReport({
         // that matters, which is the process's own.
       }
       const processMemory = readProcessMemory();
+      const watched = watchedOf(processMemory);
+      const now = Date.now();
+      const write = readingIsWorthWriting({
+        watchedBytes: watched,
+        lastWrittenBytes,
+        sinceWrittenMs: lastWrittenAt === 0 ? Number.POSITIVE_INFINITY : now - lastWrittenAt,
+        changeBytes,
+        quietMs
+      });
+
+      let anonymousBytes = null;
       if (scope === "thread") {
-        log(describeMemory({ scope, label, process: processMemory, stores }));
-        return;
+        if (write) {
+          log(describeMemory({ scope, label, process: processMemory, stores }));
+        }
+      } else {
+        const { bytes, measured } = await availableMemory();
+        anonymousBytes = await readAnonymousMemory();
+        const diskFreeBytes = diskPath ? await readDiskFree(diskPath) : null;
+        if (write) {
+          log(describeMemory({
+            scope,
+            label,
+            process: processMemory,
+            availableBytes: bytes,
+            availableMeasured: measured,
+            anonymousBytes,
+            diskFreeBytes,
+            stores
+          }));
+        }
+      }
+      if (write) {
+        lastWrittenBytes = watched;
+        lastWrittenAt = now;
       }
-      const { bytes, measured } = await availableMemory();
-      const anonymousBytes = await readAnonymousMemory();
-      const diskFreeBytes = diskPath ? await readDiskFree(diskPath) : null;
-      log(describeMemory({
-        scope,
-        label,
-        process: processMemory,
-        availableBytes: bytes,
-        availableMeasured: measured,
-        anonymousBytes,
-        diskFreeBytes,
-        stores
-      }));
-      // High-water and heap snapshot on growth — gives a file to open in Chrome DevTools
-      // when the kernel is about to kill the process. One snapshot per high-water.
-      if (processMemory.rss > highWaterRss + 100 * 1024 * 1024 && processMemory.rss > 500 * 1024 * 1024) {
-        highWaterRss = processMemory.rss;
-        try {
-          const snapPath = path.join(os.tmpdir(), `heap-${Date.now()}-${processMemory.rss}.heapsnapshot`);
-          v8.writeHeapSnapshot(snapPath);
-          log(`memory: wrote heap snapshot to ${snapPath} rss=${Math.round(processMemory.rss / (1024 * 1024))}MB anon=${anonymousBytes ? Math.round(anonymousBytes / (1024 * 1024)) : "?"}MB`);
-        } catch {}
+
+      // A snapshot per high-water, so there is a file to open when the growth
+      // has to be named rather than described.
+      //
+      // Deliberately NOT one taken as the ceiling is approached: a snapshot is
+      // written by the isolate itself and is about the size of its heap, so
+      // asking for one at 1.9 GB on a machine with 600 MB left is a good way to
+      // cause the kill being studied. Whatever holds 1.6 GB is the same thing
+      // that holds 2.2 GB, and at one reading a second no step is ever missed.
+      if (watched > highWater + snapshotGrowthBytes && watched > snapshotFloorBytes) {
+        highWater = watched;
+        await takeSnapshot(watched, "a new high-water");
       }
-      if (anonymousBytes !== null && processMemory.rss > 800 * 1024 * 1024) {
-        log(`memory: high rss=${Math.round(processMemory.rss / (1024 * 1024))}MB anon=${Math.round(anonymousBytes / (1024 * 1024))}MB heap=${Math.round(processMemory.heapUsed / (1024 * 1024))}MB — watch for OOM`);
+      if (scope !== "thread" && anonymousBytes !== null && processMemory.rss > 800 * 1024 * 1024) {
+        log(`memory: high rss=${megabytes(processMemory.rss)} anon=${megabytes(anonymousBytes)} heap=${megabytes(processMemory.heapUsed)} — watch for OOM`);
       }
     } catch {
       // silent-ok: a reading that fails is not worth ending the series over.

package/services/piece-store/piece-lru.js

@@ -64,6 +64,22 @@ export class PieceLru {
     return this.#capacity;
   }
 
+  /**
+   * Follow the store's live allowance, which moves with the machine's free
+   * memory. Without this the capacity stayed at whatever the store was created
+   * with, and {@link PieceLru#isFull} answered against a number that had not
+   * been the limit for some time.
+   *
+   * @param {number} capacity
+   * @returns {void}
+   */
+  setCapacity(capacity) {
+    if (!Number.isInteger(capacity) || capacity < 1) {
+      return;
+    }
+    this.#capacity = capacity;
+  }
+
   /**
    * How many pieces are currently held by a reader.
    *