@torrent-tv/proxy 2.58.1 → 2.58.3

package/CHANGELOG.md

@@ -1,3 +1,14 @@
+## 2.58.3
+
+- **New**: the proxy says what it is holding, once a minute — resident memory, heap, external and array buffers, the torrent stores in BYTES, and what the machine has left. It was killed on 2026-08-28 by the kernel's own out-of-memory killer at 2.4 GB resident (`exit code 137`, no core dump, `Out of memory: Killed process ... anon-rss: 2422628kB`) and the log had never recorded a single figure about memory. There was one final reading, taken by the kernel, and no series leading to it.
+- **Fix**: the torrent stores share ONE budget instead of each taking its own. It was per torrent, so two torrents meant two of it, and nothing anywhere asked what the process as a whole was holding. On the film the proxy died under, one store had taken the full 504 MB.
+- **Fix**: that budget is a share of `MemAvailable` rather than of `os.freemem()`. On Linux the second counts only the pages free at that instant, while the kernel deliberately keeps that number low by filling the rest with reclaimable cache — so the share it produced had little to do with what an allocation could actually obtain. The kernel publishes the estimate; we read it.
+- **New**: the piece-store line reports megabytes beside its piece count. The count alone says nothing without the piece size, and the piece size differs per torrent: on that film, "63" meant 504 MB.
+
+## 2.58.2
+
+- **Fix**: `utp-native` moves to 2.5.3-ttv.8, which removes the whole crash family rather than another instance of it. Nine deaths in a fortnight had one shape — libuv holding a pointer into memory that had gone — because the structs carrying `uv_udp_t`, `uv_timer_t` and `uv_udp_send_t` were allocated by JavaScript as `Buffer.alloc(sizeof(...))`, putting them under the garbage collector while libuv's rule is that they must live until the close or completion callback has run. Every earlier fix reconciled the two owners with a rule and the next release found another way through. The module now allocates and frees that memory itself, at the point libuv has provably finished; JavaScript holds only a token, and freeing points the token at nothing so a late call does nothing instead of faulting. On the environment's own teardown nothing is freed at all — a deliberate leak while the process ends beats touching napi as it goes. Checked on the target: 77 tests pass, and 60 create/serve/destroy cycles leave memory flat.
+
 ## 2.58.1
 
 - **Fix**: `utp-native` moves to 2.5.3-ttv.7, which removes a defect ttv.6 itself introduced. That release registered an environment cleanup hook per uTP context and never removed it on the ordinary close path, so once a context finished closing and its buffer was collected the hook stayed registered against freed memory. At teardown it then ran there and called `uv_close` on handles that no longer existed, putting a dead handle into libuv's closing machinery; the fault surfaced later and elsewhere, when a healthy handle was unlinked and its neighbour in the loop's handle queue turned out to be that dead one. Read from `core.WorkerThread.81.1787857798` down to the faulting instruction — `QUEUE_REMOVE`'s second store with an unmapped operand — and by walking the loop's handle queue until a node could not be read (`research/worker-crash-cleanup-hook-2026-08-27.md`).

package/bin/cli.js

@@ -25,6 +25,7 @@ import { createWebRtcManager } from "../services/webrtc-manager.js";
 import { createDataChannelHandler } from "../services/data-channel-handler.js";
 import { pruneCoreDumps } from "../services/core-dumps.js";
 import { adoptOrphanRingFiles, createPacketWitness, pruneWitnessCaptures } from "../services/packet-witness.js";
+import { startMemoryReport } from "../services/memory-report.js";
 import { collectHealthMetrics } from "../services/health-collector.js";
 import { createPortMapper } from "../services/port-mapper.js";
 import { classifyNat } from "../services/nat-classifier.js";
@@ -334,6 +335,12 @@ try {
   // the pruner recognises BEFORE anything starts a new ring over them.
   void adoptOrphanRingFiles(packetWitness.dir).then(() => pruneWitnessCaptures(packetWitness.dir));
 
+  // What this process holds, once a minute. The kernel killed the proxy on
+  // 2026-08-28 at 2.4 GB resident and the log had never said a word about
+  // memory, so the growth that ended in that kill has no shape in any record we
+  // keep. RSS is the figure the OOM killer reads, so RSS is the figure to say.
+  startMemoryReport({ log: (message) => logger.info(message) });
+
   logger.info(`Starting @torrent-tv/proxy v${PROXY_VERSION}`);
   logger.info(`Local stream endpoint: http://${bindHost}:${actualPort}/stream`);
   logger.info(`Advertised direct URL: ${directBaseUrl}`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@torrent-tv/proxy",
-  "version": "2.58.1",
+  "version": "2.58.3",
   "description": "Torrent proxy client that exposes webseed-like HTTP stream endpoint.",
   "license": "GPL-3.0-or-later",
   "publishConfig": {
@@ -45,6 +45,6 @@
     "@biomejs/biome": "^2.5.7"
   },
   "overrides": {
-    "utp-native": "npm:@torrent-tv/utp-native@2.5.3-ttv.7"
+    "utp-native": "npm:@torrent-tv/utp-native@2.5.3-ttv.8"
   }
 }

package/services/memory-report.js

@@ -0,0 +1,166 @@
+/**
+ * @file What this process is holding, said out loud on a regular cadence.
+ *
+ * Written 2026-08-28, after the kernel killed the proxy and the log could not
+ * say why. The supervisor recorded `exit code 137` — SIGKILL, so no core dump —
+ * and the kernel ring buffer held the whole of what was known:
+ *
+ *   Out of memory: Killed process 3036113 (MainThread)
+ *     anon-rss: 2422628kB  total-vm: 20856720kB  oom_score_adj: 200
+ *
+ * Two point four gigabytes, on a host with under two free, and the addon is the
+ * first thing the kernel picks because Home Assistant gives addons a positive
+ * `oom_score_adj`. What the proxy had been logging all along was its share of a
+ * CPU. Nothing anywhere said how much memory it held, so the growth that ended
+ * in that line has no shape: one final reading taken by the kernel, and no
+ * series leading to it.
+ *
+ * This is that series. It costs one line a minute and reads only counters the
+ * runtime already maintains.
+ */
+
+import { readFile } from "node:fs/promises";
+import os from "node:os";
+
+/** How often the reading is taken and written. */
+export const MEMORY_REPORT_INTERVAL_MS = 60_000;
+
+/**
+ * What the process is holding, from the runtime's own counters.
+ *
+ * `rss` is what the kernel counts against us and therefore what the OOM killer
+ * reads. The rest says where it went: the JavaScript heap, and everything held
+ * outside it — which for this proxy is where the interesting growth lives,
+ * since torrent pieces sit in a `SharedArrayBuffer` and segment bodies pass
+ * through buffers.
+ *
+ * @returns {{ rss: number, heapUsed: number, heapTotal: number, external: number, arrayBuffers: number }}
+ */
+export function readProcessMemory() {
+  const usage = process.memoryUsage();
+  return {
+    rss: usage.rss,
+    heapUsed: usage.heapUsed,
+    heapTotal: usage.heapTotal,
+    external: usage.external,
+    arrayBuffers: usage.arrayBuffers ?? 0
+  };
+}
+
+/**
+ * How much memory the machine could still give out, in bytes.
+ *
+ * `os.freemem()` is the wrong quantity on Linux and the difference is not
+ * academic: it counts only pages that are free RIGHT NOW, while the kernel
+ * deliberately keeps that number low by filling the rest with reclaimable page
+ * cache. `MemAvailable` is the kernel's own estimate of what a new allocation
+ * could actually obtain, cache included. Reading the estimate the kernel
+ * publishes beats recomputing a worse one.
+ *
+ * @returns {Promise<number | null>} Bytes, or null where /proc is not there.
+ */
+export async function readAvailableMemory() {
+  try {
+    const text = await readFile("/proc/meminfo", "utf8");
+    const match = /^MemAvailable:\s+(\d+)\s+kB$/m.exec(text);
+    if (match) {
+      return Number(match[1]) * 1024;
+    }
+  } catch {
+    // silent-ok: not Linux, or /proc is not mounted. The fallback below is a
+    // worse answer, and saying so is the point of returning it separately.
+  }
+  return null;
+}
+
+/**
+ * Available memory, falling back to what the runtime can offer.
+ *
+ * @returns {Promise<{ bytes: number, measured: boolean }>}
+ */
+export async function availableMemory() {
+  const fromKernel = await readAvailableMemory();
+  if (fromKernel !== null) {
+    return { bytes: fromKernel, measured: true };
+  }
+  return { bytes: os.freemem(), measured: false };
+}
+
+/**
+ * Render a size the way a person reads one.
+ *
+ * @param {number} bytes
+ * @returns {string}
+ */
+function megabytes(bytes) {
+  return `${Math.round(bytes / (1024 * 1024))}MB`;
+}
+
+/**
+ * One line saying what the process holds and what the machine has left.
+ *
+ * Pure, so the wording and the arithmetic can be pinned without a running
+ * process. Store figures are given in BYTES rather than in pieces: the piece
+ * 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.
+ *
+ * @param {Object} reading
+ * @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]
+ * @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);
+  const storesPart = stores.length === 0
+    ? "no torrent stores"
+    : `${stores.length} torrent store(s) holding ${megabytes(storeResident)} ` +
+      `of ${megabytes(storeBudget)} allowed`;
+  return (
+    `memory: rss=${megabytes(usage.rss)} heap=${megabytes(usage.heapUsed)}/${megabytes(usage.heapTotal)} ` +
+    `external=${megabytes(usage.external)} arrayBuffers=${megabytes(usage.arrayBuffers)}; ` +
+    `${storesPart}; ` +
+    `machine has ${megabytes(availableBytes)} available` +
+    `${availableMeasured ? "" : " (estimated — /proc/meminfo could not be read)"}`
+  );
+}
+
+/**
+ * Report memory on a timer until stopped.
+ *
+ * @param {Object} options
+ * @param {(message: string) => void} options.log
+ * @param {() => { name: string, residentBytes: number, budgetBytes: number }[]} [options.readStores]
+ * @param {number} [options.intervalMs]
+ * @returns {{ stop: () => void }}
+ */
+export function startMemoryReport({ log, readStores, intervalMs = MEMORY_REPORT_INTERVAL_MS }) {
+  const tick = async () => {
+    try {
+      const { bytes, measured } = await availableMemory();
+      let stores = [];
+      try {
+        stores = typeof readStores === "function" ? readStores() ?? [] : [];
+      } catch {
+        // silent-ok: a store list that cannot be read must not stop the reading
+        // that matters, which is the process's own.
+      }
+      log(describeMemory({
+        process: readProcessMemory(),
+        availableBytes: bytes,
+        availableMeasured: measured,
+        stores
+      }));
+    } catch {
+      // silent-ok: a reading that fails is not worth ending the series over.
+    }
+  };
+  void tick();
+  const timer = setInterval(() => { void tick(); }, intervalMs);
+  if (typeof timer.unref === "function") {
+    timer.unref();
+  }
+  return { stop: () => clearInterval(timer) };
+}