@torrent-tv/proxy 2.95.41 → 2.96.1

package/bin/cli.js

@@ -31,6 +31,7 @@ import { createUsrsctpStateReader } from "../services/transport/usrsctp-state.js
 import { startMemoryReport } from "../services/storage/memory-report.js";
 import { fragmentBufferCollection } from "../services/torrent/worker/client.js";
 import { collectHealthMetrics } from "../services/transport/health-collector.js";
+import { LOAD_REFRESH_MS, ProxyStateReporter } from "../services/transport/proxy-state.js";
 import { createPortMapper } from "../services/transport/port-mapper.js";
 import { installationId } from "../services/identity/installation-id.js";
 import { classifyNat } from "../services/transport/nat-classifier.js";
@@ -356,6 +357,24 @@ const diagnostics = new Diagnostics({
   ]
 });
 
+/**
+ * What this proxy says about itself to the server, which chooses proxies by
+ * it: the machine's load and free memory, its room for one more encode, and
+ * the films it holds. Filled in once the server parts exist; before that it
+ * says only the machine.
+ *
+ * @type {() => Promise<{ metrics: object, holds: object[] }>}
+ */
+let describeSelf = async () => ({ metrics: {}, holds: [] });
+
+// The state goes to the server when it changes rather than when it is asked
+// for (torrent-tv/meta#36). The load average has no event, so it is looked at
+// on the cadence the kernel recomputes it.
+const stateReporter = new ProxyStateReporter({
+  describe: () => describeSelf(),
+  send: (state) => tunnelClient?.sendState(state)
+});
+
 try {
   logToFile(options.logFile);
   if (transcodeAudio) {
@@ -379,10 +398,40 @@ try {
     onSubtitleCues: (event) => dataChannelHandler?.publishSubtitleCues(event),
     // Late-bound for the same reason: what the connections carry beyond the
     // film is counted by the data-channel handler, built further down.
-    serviceShare: () => dataChannelHandler?.serviceShare?.() ?? null
+    serviceShare: () => dataChannelHandler?.serviceShare?.() ?? null,
+    onStateChanged: () => void stateReporter.changed()
   });
   app = started.app;
   actualPort = started.port;
+  describeSelf = async () => {
+    // Which films this proxy holds: a viewer sent to a proxy that is
+    // downloading their film costs it the encode and nothing else, while the
+    // same viewer sent anywhere else starts the download from nothing. Asked
+    // of the worker, so a film this proxy let go of is not claimed.
+    let holds = [];
+    try {
+      holds = (await started.torrentPool?.heldTorrents?.()) ?? [];
+    } catch {
+      // silent-ok: a proxy that cannot say what it holds is scored on its
+      // machine alone, which is what every proxy was scored on until now.
+    }
+    // WHETHER THIS MACHINE HAS ROOM FOR ONE MORE ENCODE (roadmap item 97,
+    // step 14): what holds a place on it now, and the speed that leaves every
+    // output at. The load average cannot say this — an encoder admitted a
+    // moment ago has not raised it yet.
+    const encode = started.outputParts?.admission?.headroom?.() ?? null;
+    // The uptime is left out: it changes every second, nothing chooses by it,
+    // and it would make every description differ from the last.
+    const { uptime: _uptime, ...machine } = collectHealthMetrics({ availableMemory });
+    return {
+      metrics: {
+        ...machine,
+        ...(encode ? { encodeSpeedX: encode.encodeSpeedX, encodeOccupiedCostSec: encode.occupiedCostSec } : {})
+      },
+      holds
+    };
+  };
+  setInterval(() => void stateReporter.changed(), LOAD_REFRESH_MS).unref();
   const directBaseUrl = explicitBaseUrl || `http://${bindHost}:${actualPort}`;
 
   // A native fault writes the whole address space out — 4.18 GB each on the
@@ -568,33 +617,6 @@ try {
     onSignal(sessionId, signal) {
       webRtcManager?.handleSignal(sessionId, signal);
     },
-    async onHealthRequest() {
-      // Which films this proxy holds travels with the health poll the browser
-      // already makes before it picks one: a viewer sent to a proxy that is
-      // downloading their film costs it the encode and nothing else, while the
-      // same viewer sent anywhere else starts the download from nothing. Asked
-      // of the worker, so a film this proxy let go of is not claimed.
-      let holds = [];
-      try {
-        holds = (await started?.torrentPool?.heldTorrents?.()) ?? [];
-      } catch {
-        // silent-ok: a proxy that cannot say what it holds is scored on its
-        // machine alone, which is what every proxy was scored on until now.
-      }
-      // WHETHER THIS MACHINE HAS ROOM FOR ONE MORE ENCODE, read by the pool
-      // before any film is chosen (roadmap item 97, step 14): what holds a
-      // place on it now, and the speed that leaves every output at. The load
-      // average cannot say this — an encoder admitted a moment ago has not
-      // raised it yet.
-      const encode = started?.outputParts?.admission?.headroom?.() ?? null;
-      return {
-        metrics: {
-          ...collectHealthMetrics({ availableMemory }),
-          ...(encode ? { encodeSpeedX: encode.encodeSpeedX, encodeOccupiedCostSec: encode.occupiedCostSec } : {})
-        },
-        holds
-      };
-    },
     // Whether this host could sustain a file it has only been told about. The
     // same arithmetic the first offer uses, against this host's own startup
     // benchmarks — no torrent, no bytes, no ffmpeg — so the browser can ask
@@ -604,6 +626,9 @@ try {
       return started?.outputParts?.quality?.predictOfferedHeights?.(mediaInfo) ?? null;
     },
     onConnect() {
+      // A new connection — a reconnect, or a move to another server instance —
+      // has not heard this proxy's state: send it whether or not it changed.
+      void stateReporter.resend();
       // Re-register on every tunnel connect/reconnect so the server's
       // in-memory store stays consistent after server restarts.
       void registerClientSafe().catch((error) => {

package/package.json

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

package/server.js

@@ -123,7 +123,11 @@ export async function startProxyServer({
   // Where the proxy writes its own log. Its DIRECTORY is what matters here:
   // the browser's half of every session is written beside it, so the two are
   // on one durable disk and join by name.
-  logFile = ""
+  logFile = "",
+  // Told whenever what the server chooses proxies by may have changed here:
+  // the films held, an encoder started or ended, a viewer came or went
+  // (`transport/proxy-state.js`).
+  onStateChanged = () => undefined
 }) {
   const app = Fastify({
     // No practical body-size limit — the proxy server is localhost-only and
@@ -159,6 +163,7 @@ export async function startProxyServer({
   const torrentPool = new WorkerTorrentPool({
     memoryBytes,
     stateDir,
+    onHoldingsChanged: () => onStateChanged(),
     onSourceForgotten: ({ sourceKey }) => {
       sourcePreparation?.forget(sourceKey);
       mediaReads.forget(sourceKey);
@@ -613,7 +618,8 @@ export async function startProxyServer({
     indexMemory,
     serviceShare,
     readMetadataActivity: () => containerOrchestrator.activity(),
-    onViewerChanged: () => { void sourcePreparation?.refresh(); },
+    onViewerChanged: () => { void sourcePreparation?.refresh(); onStateChanged(); },
+    onEncodersChanged: () => onStateChanged(),
     sourceInputsFor: (output, index) => downloadMaps.inputsForOutput(output.file.sourceKey, output.outputKey, index),
     readSourceMedia: async (params) => {
       await playbackPlanner.getPlan(params);

package/services/encode/EncodeRuns.js

@@ -1035,6 +1035,7 @@ export class EncodeRuns {
           admittedInput.release();
         }
         this.noteRunEnded(session, run, ended);
+        this.#host.encodersChanged?.();
       }
     });
     if (admittedInput.original) {
@@ -1070,6 +1071,7 @@ export class EncodeRuns {
       });
     }
     this.#runsByInputToken.set(inputToken, run);
+    this.#host.encodersChanged?.();
     // THE ONE FAULT THAT IS OTHERWISE SILENT, asked before this run produces a
     // frame. It lost its caller in a refactor on 2026-09-04 and had none until
     // 2026-09-15 — not by a decision, which is why it is back rather than gone.

package/services/server/wire-outputs.js

@@ -226,7 +226,10 @@ export function wireOutputs({
     // the transport measured it (`transport/delivery-shares.js`); null while
     // nothing has been delivered.
     serviceShare = () => null,
-    onViewerChanged = null}) {
+    onViewerChanged = null,
+    // Told when an encoder starts or ends: the room this host has for one more
+    // encode changes with it, and the server chooses proxies by that room.
+    onEncodersChanged = null}) {
   const parts = {};
   const audioDescriptionOf = (output) => (getCachedAudioTracks?.({
     sourceKey: output.file.sourceKey, fileIndex: output.spec.grid?.fileIndex ?? output.file.fileIndex
@@ -339,6 +342,7 @@ export function wireOutputs({
     get encoders() { return parts.encoders; },
     invalidateWaits: (output) => parts.serving.invalidateWaits(output),
     productionFailed: (output) => parts.renditions.noteProductionFailed(output),
+    encodersChanged: () => onEncodersChanged?.(),
   });
   // How much film is ready in front of the viewers, said; and the spare soundtracks fetched once it is full.
   parts.cushion = new CushionReport({

package/services/storage/files/CompletedFiles.js

@@ -103,6 +103,25 @@ export class CompletedFiles {
     return total;
   }
 
+  /**
+   * Every file held whole, by torrent: what this proxy can serve without any
+   * swarm. Read without counting as a read, so asking does not keep a file.
+   *
+   * @returns {Map<string, { fileIndexes: number[], bytes: number }>} Infohash → its files.
+   */
+  heldByTorrent() {
+    const byTorrent = new Map();
+    for (const [key, file] of this.#held) {
+      const slash = key.lastIndexOf("/");
+      const infoHash = key.slice(0, slash);
+      const entry = byTorrent.get(infoHash) ?? { fileIndexes: [], bytes: 0 };
+      entry.fileIndexes.push(Number(key.slice(slash + 1)));
+      entry.bytes += file.length;
+      byTorrent.set(infoHash, entry);
+    }
+    return byTorrent;
+  }
+
   /**
    * @param {string} infoHash
    * @param {number} fileIndex

package/services/torrent/worker/client.js

@@ -111,11 +111,13 @@ export class TorrentWorkerClient {
   /** @type {(event: { sourceKey: string, fileIndexes: number[] }) => void} */
   #onPiecesArrived;
   #onSourceForgotten;
+  /** Told when what this proxy holds changed; see `Event.HOLDINGS_CHANGED`. */
+  #onHoldingsChanged;
 
   /**
    * @param {{ memoryBytes?: number, stateDir?: string, onPiecesArrived?: (event: object) => void }} [options]
    */
-  constructor({ memoryBytes, stateDir, onPiecesArrived, onSourceForgotten } = {}) {
+  constructor({ memoryBytes, stateDir, onPiecesArrived, onSourceForgotten, onHoldingsChanged } = {}) {
     this.#worker = new Worker(fileURLToPath(WORKER_URL), {
       // `stateDir` travels because the worker writes heap snapshots of its own
       // isolate there. It cannot choose a directory any other way: a worker may
@@ -126,6 +128,7 @@ export class TorrentWorkerClient {
     this.#caller = createCaller(this.#worker);
     this.#onPiecesArrived = onPiecesArrived ?? (() => undefined);
     this.#onSourceForgotten = onSourceForgotten ?? (() => undefined);
+    this.#onHoldingsChanged = onHoldingsChanged ?? (() => undefined);
 
     this.#worker.on("message", (message) => {
       // A failed read must fail its stream. This is checked BEFORE the caller
@@ -241,6 +244,9 @@ export class TorrentWorkerClient {
         case Event.SOURCE_FORGOTTEN:
           this.#onSourceForgotten({ sourceKey: message.sourceKey });
           break;
+        case Event.HOLDINGS_CHANGED:
+          this.#onHoldingsChanged();
+          break;
         case Event.PIECES_ARRIVED:
         case Event.PIECES_CHANGED:
           // ANNOUNCED by the thread that owns the swarm, acted on here: the

package/services/torrent/worker/protocol.js

@@ -155,7 +155,13 @@ export const Event = {
    * for anything: an ordinary read of an ordinary file, with no piece store
    * between them and nothing that can refuse it for want of memory.
    */
-  FILE_COMPLETE: "file-complete"
+  FILE_COMPLETE: "file-complete",
+  /**
+   * What this proxy holds has changed: a torrent was added or closed, a file
+   * was kept whole or let go. Announced by this thread, which owns both; the
+   * main thread tells the server, which chooses proxies by what they hold.
+   */
+  HOLDINGS_CHANGED: "holdings-changed"
 };
 
 /**

package/services/torrent/worker/worker.js

@@ -381,6 +381,7 @@ async function runCommand(command, params, id) {
       // stand-ins, which is only cleared on shutdown and would name films this
       // proxy let go of hours ago.
       const held = [];
+      const whole = completedFiles.heldByTorrent();
       for (const torrent of pool.client?.torrents ?? []) {
         const infoHash = String(torrent?.infoHash ?? "");
         if (!infoHash) {
@@ -392,8 +393,15 @@ async function runCommand(command, params, id) {
           // nothing, so the share is reported and the decision is made where
           // the viewer is.
           progress: Number.isFinite(torrent?.progress) ? torrent.progress : 0,
-          bytes: Number.isFinite(torrent?.downloaded) ? torrent.downloaded : 0
+          bytes: Number.isFinite(torrent?.downloaded) ? torrent.downloaded : 0,
+          wholeFiles: whole.get(infoHash)?.fileIndexes ?? []
         });
+        whole.delete(infoHash);
+      }
+      // A film downloaded whole is kept as files after its torrent is removed:
+      // this proxy still holds it, and serves it with no swarm at all.
+      for (const [infoHash, files] of whole) {
+        held.push({ infoHash, progress: null, bytes: files.bytes, wholeFiles: files.fileIndexes });
       }
       return { held };
     }
@@ -525,6 +533,7 @@ async function runCommand(command, params, id) {
       // other. What arrives is their share; what goes back is what they hold
       // after it, which is what the owner divides by next time.
       const after = await completedFiles.allow(Number(params.bytes));
+      if (after.removed > 0) holdingsChanged();
       return after.bytes;
     }
 
@@ -848,6 +857,7 @@ function ensureArrivalsWired(sourceKey, torrent) {
     return;
   }
   arrivalsWired.add(torrent);
+  holdingsChanged();
   torrent.on("verified", () => announceArrivals(sourceKey, torrent));
   torrent.on("piece-withdrawn", () => announceArrivals(sourceKey, torrent, "withdrawn"));
   torrent.once("close", () => {
@@ -858,9 +868,15 @@ function ensureArrivalsWired(sourceKey, torrent) {
       const retained = wholeSources.describe(sourceKey);
       announceWholeFiles(sourceKey, retained);
     } else parentPort.postMessage({ type: Event.SOURCE_FORGOTTEN, sourceKey });
+    holdingsChanged();
   });
 }
 
+/** Say that what this proxy holds has changed (`Event.HOLDINGS_CHANGED`). */
+function holdingsChanged() {
+  parentPort.postMessage({ type: Event.HOLDINGS_CHANGED });
+}
+
 /**
  * Files this proxy has downloaded whole. One directory, two readers of it: this
  * thread writes them, the main thread serves them without asking anybody.
@@ -913,6 +929,7 @@ pool.buildStoresWith({
 });
 void completedFiles.adopt(() => null).then((adopted) => {
   if (adopted > 0) {
+    holdingsChanged();
     logger.info(
       `whole files: took up ${adopted} file(s) a previous life left in ${completedFiles.root}`
     );
@@ -1008,6 +1025,7 @@ async function keepWholeFiles() {
             length: kept.length,
             name: kept.name
           });
+          holdingsChanged();
         }
       } catch (error) {
         logger.warn(`whole files: could not keep "${file?.name}": ${error?.message ?? error}`);

package/services/transport/proxy-state.js

@@ -0,0 +1,95 @@
+/**
+ * @file What this proxy tells the server about itself, sent when it changes.
+ *
+ * The server chooses a proxy for every viewer from a table of proxies it keeps
+ * (torrent-tv/meta#36): their load, their room for one more encode, and the
+ * films they hold. It used to ask every proxy for all of it on every choice and
+ * wait up to two seconds for the answers; now each proxy says it when it
+ * changes, and the server answers a choice from what it already knows.
+ *
+ * `changed()` is the one entry: called on every event that may change the
+ * state (a torrent added or closed, a file kept whole, an encoder started or
+ * ended, a viewer coming or going) and on the cadence of the load average,
+ * which has no event of its own. Calls that arrive while one description is
+ * being made are joined into one more after it, and a description identical
+ * to the last one sent is not sent again.
+ */
+
+/**
+ * How often the load average is looked at. Linux recomputes it every five
+ * seconds (`LOAD_FREQ` in `kernel/sched/loadavg.c`); reading it more often
+ * finds the same number, less often lets the server's copy lag behind it.
+ */
+export const LOAD_REFRESH_MS = 5_000;
+
+export class ProxyStateReporter {
+  /** @type {() => Promise<object> | object} */
+  #describe;
+
+  /** @type {(state: object) => void} */
+  #send;
+
+  /** @type {Promise<void> | null} */
+  #running = null;
+
+  #again = false;
+
+  /** What was sent last, as text, so an unchanged state is not sent again. */
+  #lastSent = "";
+
+  /**
+   * @param {object} params
+   * @param {() => Promise<object> | object} params.describe - This proxy's state now.
+   * @param {(state: object) => void} params.send - Deliver it to the server.
+   */
+  constructor({ describe, send }) {
+    this.#describe = describe;
+    this.#send = send;
+  }
+
+  /**
+   * Something that may change the state happened: describe it and send what
+   * differs. Never throws; never waits for the caller.
+   *
+   * @returns {Promise<void>}
+   */
+  changed() {
+    if (this.#running) {
+      this.#again = true;
+      return this.#running;
+    }
+    this.#running = this.#run().finally(() => {
+      this.#running = null;
+    });
+    return this.#running;
+  }
+
+  /**
+   * Send the state even when it is unchanged: a new connection to the server
+   * (a reconnect, or a move to another server instance) has not heard it.
+   *
+   * @returns {Promise<void>}
+   */
+  resend() {
+    this.#lastSent = "";
+    return this.changed();
+  }
+
+  async #run() {
+    do {
+      this.#again = false;
+      let state;
+      try {
+        state = await this.#describe();
+      } catch {
+        // silent-ok: a state that cannot be described now is described at the
+        // next change or load reading; the server keeps the last one it heard.
+        continue;
+      }
+      const text = JSON.stringify(state);
+      if (text === this.#lastSent) continue;
+      this.#lastSent = text;
+      this.#send(state);
+    } while (this.#again);
+  }
+}

package/services/transport/tunnel-client.js

@@ -20,7 +20,6 @@
 
 import { WebSocket } from "ws";
 
-/** @import { HealthMetrics } from './health-collector.js' */
 
 /**
  * Configuration for the tunnel client.
@@ -52,9 +51,6 @@ import { WebSocket } from "ws";
  *   Answered from this host's startup benchmarks alone: no torrent is added, no
  *   bytes are fetched and ffmpeg is not run, so it costs milliseconds and can
  *   be asked of every proxy in the pool at once.
- * @property {() => HealthMetrics} [onHealthRequest]
- *   Called when the server sends a `health-request` message.  The return value is
- *   sent back as `health-response` and used by the server to score this proxy.
  * @property {(message: string) => void} [onLog]
  *   Optional structured log sink.
  */
@@ -136,7 +132,6 @@ export function createTunnelClient({
   baseUrl = "",
   onSignal,
   onConnect,
-  onHealthRequest,
   onCanServeRequest,
   onLog,
   connectionLifetimeMs = CONNECTION_LIFETIME_MS
@@ -278,6 +273,14 @@ export function createTunnelClient({
         return;
       }
 
+      // The server's answer to this proxy's keepalive, echoed at once on the
+      // same connection: the server measures the tunnel round trip from it on
+      // its own clock, and chooses proxies partly by that.
+      if (message.type === "rtt-probe") {
+        send({ type: "rtt-echo", sentAt: message.sentAt }, connection);
+        return;
+      }
+
       // Could this host serve a file it is only told ABOUT? Asked when the
       // proxy a viewer landed on has refused the file, so the browser can be
       // sent somewhere that will work instead of being shown an error. The
@@ -297,29 +300,6 @@ export function createTunnelClient({
         send({ type: "can-serve-response", requestId: message.requestId, offer }, connection);
         return;
       }
-
-      // Health check: server requests current metrics for proxy scoring.
-      if (message.type === "health-request") {
-        // Awaited: the answer now carries which films this proxy holds, and the
-        // truthful list of those lives on the torrent thread.
-        void (async () => {
-          let answer = {};
-          try {
-            answer = typeof onHealthRequest === "function" ? await onHealthRequest() : {};
-          } catch {
-            // silent-ok: a proxy that cannot describe itself is scored on
-            // nothing rather than not answered at all, which would drop it out
-            // of every selection until the next poll.
-          }
-          send({
-            type: "health-response",
-            requestId: message.requestId,
-            metrics: answer?.metrics ?? answer ?? {},
-            holds: Array.isArray(answer?.holds) ? answer.holds : []
-          }, connection);
-        })();
-        return;
-      }
     });
 
     connection.addEventListener("close", (event) => {
@@ -508,6 +488,21 @@ export function createTunnelClient({
       }
     },
 
+    /**
+     * Tell the server this proxy's state: its load, its room for one more
+     * encode and the films it holds (`transport/proxy-state.js`). Over every
+     * open connection: during a move between server instances both keep a
+     * table of proxies, and each chooses from its own.
+     *
+     * @param {{ metrics?: object, holds?: object[] }} state
+     * @returns {void}
+     */
+    sendState(state) {
+      for (const connection of openConnections) {
+        send({ type: "proxy-state", metrics: state?.metrics ?? {}, holds: Array.isArray(state?.holds) ? state.holds : [] }, connection);
+      }
+    },
+
     /**
      * Forward a WebRTC signal (SDP answer or ICE candidate) from this proxy
      * to the browser via the server tunnel.