@torrent-tv/proxy 2.96.14 → 2.97.0

package/bin/cli.js

@@ -88,6 +88,7 @@ program
   .option("--no-transcode-audio", "Disable optional HLS AAC audio transcoding")
   .option("--no-port-mapping", "Disable automatic UPnP/NAT-PMP port mapping")
   .option("--delivery-sink", "Serve /api/delivery-sink, a torrent-free byte stream for delivery testing")
+  .option("--profile-start <seconds>", "Profile the main thread's CPU for this many seconds from the first source opened, written beside the state (off by default)")
   .option(
     "--send-chunk-bytes <bytes>",
     "Size of one data-channel message when sending a response body (0 = whatever the body read hands over, ~64KB). For measuring whether the delivery wedge depends on that size."
@@ -392,6 +393,7 @@ try {
     budgetPolicy,
     logFile: options.logFile ?? "",
     deliverySink: options.deliverySink === true,
+    profileStartSeconds: Number(options.profileStart) || 0,
     // Late-bound the same way `webRtcManager` is below: the torrent pool is
     // built inside `startProxyServer`, before `dataChannelHandler` — the
     // thing that actually owns a channel to push down — exists.

package/package.json

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

package/routes/encode-input/get.js

@@ -36,6 +36,19 @@ export function handleEncodeInputGet(req, reply, { inputOf, refused = () => {} }
     refused({ token, fileIndex, start: range.start, runTag: input.runTag ?? null });
     return reply.code(503).send({ error: "Original input bytes are outside the admitted ranges." });
   }
+  // What was handed to the system for this answer before its connection
+  // closed, and whether all of it was: an answer runs to the end of its
+  // admitted range and FFmpeg closes the connection once it has what it wants,
+  // so the range answered says nothing about the bytes taken. What FFmpeg read
+  // is at most what was handed over; the kernel's buffer is the difference,
+  // and it cannot be seen from here (torrent-tv/meta#177).
+  const socket = req.raw?.socket;
+  const writtenBefore = socket?.bytesWritten ?? 0;
+  reply.raw?.once?.("close", () => {
+    input.noteAnswer?.({ fileIndex, start: range.start, end: held.end,
+      written: Math.max(0, (socket?.bytesWritten ?? writtenBefore) - writtenBefore),
+      handedOver: reply.raw?.writableFinished === true });
+  });
   return reply.code(206).header("Content-Length", String(held.bytes.length))
     .header("Content-Range", `bytes ${range.start}-${held.end}/${length}`).send(held.bytes);
 }

package/server.js

@@ -80,6 +80,8 @@ import { measureStartAndStop } from "./services/encode/start-stop-cost.js";
 import { benchmarkAudio } from "./services/encode/audio-calibration.js";
 import { logger } from "./utils/logger.js";
 import { completedFilesRoot } from "./services/storage/files/CompletedFiles.js";
+import { startupCpuProfile } from "./services/storage/cpu-profile.js";
+import { startProcessorReport } from "./services/storage/processor-report.js";
 
 const require = createRequire(import.meta.url);
 const { version } = require("./package.json");
@@ -119,6 +121,8 @@ function buildPortCandidates(startPort, maxAttempts = 51) {
 export async function startProxyServer({
   host, port, transcodeAudio, ffmpegBin, memoryBytes, segmentFormat, stateDir, onSubtitleCues, diagnostics, budgetPolicy,
   deliverySink = false,
+  // Seconds of main-thread CPU profile from the first source opened; 0 is off.
+  profileStartSeconds = 0,
   // What viewers' connections carry beyond the film, per byte of film; the
   // transport counts it and is built after this server, so it is late-bound.
   serviceShare = () => null,
@@ -875,6 +879,22 @@ export async function startProxyServer({
       await torrentPool.fillFileInBackground?.(torrent, fileIndex);
     }
   });
+  // Where the processor goes, and at a cold start what the main thread does
+  // with it, when the operator asks (torrent-tv/meta#177).
+  const startupProfile = startupCpuProfile({
+    seconds: profileStartSeconds,
+    dir: stateDir || "",
+    log: (line) => logger.info(line),
+    mayKeep: (bytes) => diagnostics?.mayKeep?.({ what: "a CPU profile", bytes }) ?? true
+  });
+  startProcessorReport({
+    log: (line) => logger.info(line),
+    ffmpegPids: () => [...outputParts.outputs.values()]
+      .flatMap((output) => outputParts.encodeRuns.liveRunsOf(output))
+      .map((run) => run.process?.pid)
+      .filter((pid) => Number.isInteger(pid)),
+    detailed: () => startupProfile.active()
+  });
   // What the last life of this process left on the disk. The kernel kills this
   // one often enough for that to be an ordinary state rather than an odd one —
   // twice in a single viewing on 2026-09-02 — and when it does, no exit handler
@@ -1106,9 +1126,11 @@ export async function startProxyServer({
   );
   // Bytes a browser can time its link with before any film has been chosen.
   app.get("/api/link-probe", async (req, reply) => handleApiLinkProbeGet(req, reply));
-  app.post("/api/sources", async (req, reply) =>
-    handleApiSourcesPost(req, reply, { sourceRegistry, viewers: outputParts.viewers })
-  );
+  app.post("/api/sources", async (req, reply) => {
+    // A cold start begins with the first source opened (torrent-tv/meta#177).
+    startupProfile.begin();
+    return handleApiSourcesPost(req, reply, { sourceRegistry, viewers: outputParts.viewers });
+  });
   app.get("/api/sources/:sourceKey/stats", async (req, reply) =>
     handleApiSourceStatsGet(req, reply, { sourceRegistry, torrentPool })
   );

package/services/encode/EncodeRuns.js

@@ -20,6 +20,7 @@ import { writeAdmittedInput } from "./AdmittedInput.js";
 import { cutOf, cutShiftOf, judgeNeighbors, judgePiece } from "./piece-completeness.js";
 import { presentationSegment } from "./segment-formats/presentation-segment.js";
 import { InputFailures, failedAdmittedInput } from "./InputFailures.js";
+import { readProcessCpuSeconds } from "./host-load.js";
 
 
 /**
@@ -161,6 +162,15 @@ export class EncodeRuns {
    * @type {Map<number, import("./EncodeRun.js").EncodeRun>}
    */
   #runsByInputToken = new Map();
+  /**
+   * Each live run's ffmpeg CPU seconds against the film it had made, as of its
+   * last progress report: what one second of film costs this machine in
+   * processor time, which the speed in x does not say once other work shares
+   * the processor (torrent-tv/meta#177). Said when the run ends.
+   *
+   * @type {WeakMap<object, { cpuSeconds: number, filmSeconds: number, reading: boolean, beside: number }>}
+   */
+  #cpuOfRun = new WeakMap();
 
   #lastInputToken = 0;
   #inputFailures = new InputFailures();
@@ -1046,11 +1056,12 @@ export class EncodeRuns {
             const since = (at) => at ? `${at - run.startedAt}ms` : "never";
             this.#host.logger.info(`encode input of run #${run.from}..#${run.to} on ${session.outputKey}: ` +
               `${reads.count} read(s), ${reads.bytes} bytes, first at ${since(reads.firstAt)}, last at ${since(reads.lastAt)}, ` +
-              `ended at ${Date.now() - run.startedAt}ms`);
+              `ended at ${Date.now() - run.startedAt}ms` + describeTaken(reads.answers, run.startedAt, ended.firstNamedMs));
           }
           this.#noteOpen(session, run, ended);
           admittedInput.release();
         }
+        this.#sayRunCpu(session, run);
         this.noteRunEnded(session, run, ended);
         this.#host.encodersChanged?.();
       }
@@ -1167,6 +1178,7 @@ export class EncodeRuns {
     if (!this.isLive(session) || !this.runsOf(session).includes(run)) {
       return;
     }
+    this.#readRunCpu(run, progress);
     if (run.progress.shouldLog(PROGRESS_LOG_INTERVAL_MS)) {
       this.#host.logger.info(
         `transcode ${session.id} "${session.file.name}" ${progress.percent.toFixed(1)}% ` +
@@ -1176,6 +1188,44 @@ export class EncodeRuns {
     }
   }
 
+  /**
+   * Read the run's ffmpeg CPU beside the film it has made, one reading at a
+   * time; a reading that cannot be taken (no `/proc`, the process gone)
+   * leaves the last one.
+   *
+   * @param {import("./EncodeRun.js").EncodeRun} run
+   * @param {{ processedSeconds?: number, startPositionSeconds?: number }} progress
+   */
+  #readRunCpu(run, progress) {
+    const pid = run.process?.pid;
+    const filmSeconds = Number(progress?.processedSeconds) - Number(progress?.startPositionSeconds ?? 0);
+    const known = this.#cpuOfRun.get(run) ?? { cpuSeconds: 0, filmSeconds: 0, reading: false, beside: 0 };
+    this.#cpuOfRun.set(run, known);
+    if (known.reading || !Number.isInteger(pid) || !(filmSeconds > 0)) return;
+    known.reading = true;
+    void readProcessCpuSeconds(pid).then((cpuSeconds) => {
+      if (Number.isFinite(cpuSeconds)) {
+        known.cpuSeconds = cpuSeconds;
+        known.filmSeconds = filmSeconds;
+        known.beside = Math.max(known.beside, this.#runsByInputToken.size - 1);
+      }
+    }).finally(() => { known.reading = false; });
+  }
+
+  /**
+   * What the run's ffmpeg spent per second of film, said once when it ends.
+   *
+   * @param {object} session
+   * @param {import("./EncodeRun.js").EncodeRun} run
+   */
+  #sayRunCpu(session, run) {
+    const known = this.#cpuOfRun.get(run);
+    if (!known || !(known.filmSeconds > 0) || !(known.cpuSeconds > 0)) return;
+    this.#host.logger.info(`encode-run #${run.from}..#${run.to} on ${session.outputKey}: ffmpeg used ` +
+      `${known.cpuSeconds.toFixed(2)}s of CPU for ${known.filmSeconds.toFixed(2)}s of film, ` +
+      `${(known.cpuSeconds / known.filmSeconds).toFixed(3)}s per second of film; at most ${known.beside} other encoder(s) alive beside it`);
+  }
+
   /**
    * What to do about a run that has ended.
    *
@@ -1531,3 +1581,26 @@ export class EncodeRuns {
     });
   }
 }
+
+/**
+ * What FFmpeg was handed of an original input, as a clause of the run's input
+ * line (torrent-tv/meta#177): bytes handed to the system (at most what it
+ * read), connections closed before an answer was all handed over,
+ * the share of reads that went forward, the largest jump back, bytes taken
+ * twice, and what it read before it named its first piece — its open.
+ *
+ * @param {{ count: number, written: number, unfinished: number, forwardShare: number | null, largestBackBytes: number, rewritten: number, list: { at: number, written: number }[] } | undefined} answers
+ * @param {number} startedAt
+ * @param {number | null | undefined} firstNamedMs
+ * @returns {string}
+ */
+function describeTaken(answers, startedAt, firstNamedMs) {
+  if (!answers || answers.count === 0) return "";
+  const opened = Number.isFinite(firstNamedMs)
+    ? answers.list.filter((answer) => answer.at - startedAt <= firstNamedMs) : null;
+  return `; handed over: ${answers.written} bytes in ${answers.count} answer(s), ${answers.unfinished} closed before all was handed over, ` +
+    `${answers.forwardShare === null ? "n/a" : `${Math.round(answers.forwardShare * 100)}%`} forward, ` +
+    `largest jump back ${answers.largestBackBytes} bytes, ${answers.rewritten} bytes taken twice` +
+    (opened ? `; before the first piece was named ${opened.length} answer(s), ` +
+      `${opened.reduce((sum, answer) => sum + answer.written, 0)} bytes` : "");
+}

package/services/encode/OriginalInput.js

@@ -35,6 +35,11 @@ export async function admitOriginalInput({ sources, reserve, readRanges, now = D
     // time went: field 2026-10-08, a run took 6-9 s for a piece FFmpeg makes in
     // 1.6 s from a file, and nothing said whether it was waiting on its input.
     const reads = { count: 0, bytes: 0, firstAt: 0, lastAt: 0 };
+    // Each answer FFmpeg was sent, in order: where it began, where its range
+    // ended, what was handed to the system before the connection closed, and
+    // whether all of it was (torrent-tv/meta#177).
+    /** @type {{ fileIndex: number, start: number, end: number, written: number, handedOver: boolean, at: number }[]} */
+    const answers = [];
     return {
       kind: "result", original: true, sources, bytes, copyMs, fingerprint: hash.digest("hex"),
       // No track's own end: the container names the bytes an interval needs,
@@ -59,7 +64,10 @@ export async function admitOriginalInput({ sources, reserve, readRanges, now = D
         return { length: fileLength, end: stop, bytes: entry.buffers[position].subarray(start - ranges[position][0], stop - ranges[position][0] + 1) };
       },
       lengthOf: fileIndex => held.get(fileIndex)?.source.input.fileLength ?? null,
-      reads: () => ({ ...reads }),
+      reads: () => ({ ...reads, answers: describeAnswers(answers) }),
+      noteAnswer(answer) {
+        if (!released) answers.push({ ...answer, at: Date.now() });
+      },
       release() {
         if (released) return;
         released = true;
@@ -77,3 +85,39 @@ export function originalInputBytes(sources) {
   return sources.reduce((total, source) => total + source.input.ranges
     .reduce((sum, [start, end]) => sum + end - start + 1, 0), 0);
 }
+
+/**
+ * The shape of FFmpeg's reads of one input, from the answers it was sent:
+ * how much was handed to the system (at most what FFmpeg read), how many
+ * connections closed before all of an answer was handed over, what share began
+ * at or after the end of the previous one (a forward read), the largest jump
+ * back, and the bytes written again that an earlier answer had already
+ * written. Per file, since two files are read independently.
+ *
+ * @param {{ fileIndex: number, start: number, end: number, written: number, handedOver: boolean, at: number }[]} answers
+ * @returns {{ count: number, written: number, unfinished: number, forwardShare: number | null, largestBackBytes: number, rewritten: number, list: object[] }}
+ */
+export function describeAnswers(answers) {
+  let written = 0, unfinished = 0, forward = 0, largestBackBytes = 0, rewritten = 0;
+  const reachedOf = new Map();
+  const coveredOf = new Map();
+  for (const answer of answers) {
+    written += answer.written;
+    if (!answer.handedOver) unfinished += 1;
+    const reached = reachedOf.get(answer.fileIndex);
+    if (reached === undefined || answer.start >= reached) forward += 1;
+    else largestBackBytes = Math.max(largestBackBytes, reached - answer.start);
+    // Bytes actually taken by this answer, as a range from its start.
+    const takenEnd = answer.start + Math.max(0, answer.written) - 1;
+    const covered = coveredOf.get(answer.fileIndex) ?? [];
+    for (const [from, to] of covered) {
+      const overlap = Math.min(to, takenEnd) - Math.max(from, answer.start) + 1;
+      if (overlap > 0) rewritten += overlap;
+    }
+    if (takenEnd >= answer.start) covered.push([answer.start, takenEnd]);
+    coveredOf.set(answer.fileIndex, covered);
+    reachedOf.set(answer.fileIndex, Math.max(reached ?? 0, takenEnd + 1));
+  }
+  return { count: answers.length, written, unfinished,
+    forwardShare: answers.length ? forward / answers.length : null, largestBackBytes, rewritten, list: answers };
+}

package/services/storage/MachineBudget.js

@@ -77,6 +77,13 @@ import { OtherDemand, divideAllowance } from "./allowance.js";
 export class MachineBudget {
   #revisionPromise = null;
   #reviseAgain = false;
+  /**
+   * The revision in hand, for its own line: when it was first asked for, how
+   * many asks joined it, and which pass this is. At a cold start on the addon
+   * host a caller waited 20.2 s inside `revise()` and nothing said whether it
+   * waited for passes, for a reading, or for the thread (torrent-tv/meta#177).
+   */
+  #revision = null;
   /** Resource name → how to read what is free, and what others have needed. */
   #resources = new Map();
 
@@ -151,11 +158,14 @@ export class MachineBudget {
   revise() {
     if (this.#revisionPromise) {
       this.#reviseAgain = true;
+      this.#revision.asks += 1;
       return this.#revisionPromise;
     }
+    this.#revision = { askedAt: Date.now(), asks: 1, pass: 0 };
     this.#revisionPromise = (async () => {
       do {
         this.#reviseAgain = false;
+        this.#revision.pass += 1;
         await this.#readRevision();
       } while (this.#reviseAgain);
       return this.#last;
@@ -164,13 +174,17 @@ export class MachineBudget {
   }
 
   async #readRevision() {
+    const passFrom = Date.now();
+    let readingMs = 0;
     for (const [name, resource] of this.#resources) {
       const claimants = this.#claimants.filter((one) => one.resource === name);
       if (claimants.length === 0) {
         continue;
       }
       const held = claimants.reduce((sum, one) => sum + Math.max(0, one.held()), 0);
+      const readFrom = Date.now();
       const free = await resource.readFree();
+      readingMs += Date.now() - readFrom;
       // WITHOUT A READING, NOTHING IS ALLOWED TO GROW. A resource whose free
       // space cannot be read is not a resource with room; answering "unbounded"
       // there is how the spill file came to have no limit in the first place.
@@ -197,7 +211,11 @@ export class MachineBudget {
         );
       }
     }
-    this.#logger?.info?.(this.describe());
+    const revision = this.#revision;
+    this.#logger?.info?.(`${this.describe()}` + (revision
+      ? ` (pass ${revision.pass} of a revision asked ${revision.asks} time(s), first ${Date.now() - revision.askedAt}ms ago; ` +
+        `this pass ${Date.now() - passFrom}ms, ${readingMs}ms of it reading what is free)`
+      : ""));
     return this.#last;
   }
 

package/services/storage/cpu-profile.js

@@ -0,0 +1,68 @@
+/**
+ * @file A CPU profile of the main thread at a cold start, asked for by the
+ * operator and never taken otherwise (torrent-tv/meta#177).
+ *
+ * At a cold start on the addon host (#166 run 12) the picture's first input
+ * waited 29.5 s, 20.2 s of it inside a budget revision, while the main thread
+ * ran at 83-108 % of a core; what it was doing is not in any log. A profile of
+ * that thread names it.
+ *
+ * In-process, through `node:inspector`: the sampling profiler runs beside the
+ * thread and does not stop it — unlike the debugger that stopped every thread
+ * of this process on 2026-09-05 (torrent-tv/meta#77). It begins at the first
+ * source opened, which is where a cold start begins, runs for the seconds the
+ * operator named, and writes `cpu-start-<time>.cpuprofile` beside the log,
+ * readable in Chrome's DevTools (Performance, "Load profile").
+ */
+
+import { Session } from "node:inspector/promises";
+import { writeFile } from "node:fs/promises";
+import path from "node:path";
+
+/**
+ * @param {object} params
+ * @param {number} params.seconds - How long to profile; nothing happens unless positive.
+ * @param {string} params.dir - Where to write the profile.
+ * @param {(line: string) => void} params.log
+ * @param {(bytes: number) => boolean} [params.mayKeep] - Whether the storage budget lets it be kept.
+ * @returns {{ begin: () => void, active: () => boolean }}
+ */
+export function startupCpuProfile({ seconds, dir, log, mayKeep = () => true }) {
+  let begun = false;
+  let running = false;
+  const wanted = Number.isFinite(seconds) && seconds > 0 && typeof dir === "string" && dir.length > 0;
+  const take = async () => {
+    const session = new Session();
+    session.connect();
+    try {
+      await session.post("Profiler.enable");
+      await session.post("Profiler.start");
+      running = true;
+      log(`cpu profile: the main thread is profiled for ${seconds}s from the first source opened`);
+      await new Promise((resolve) => {
+        const timer = setTimeout(resolve, seconds * 1000);
+        if (typeof timer.unref === "function") timer.unref();
+      });
+      const { profile } = await session.post("Profiler.stop");
+      const text = JSON.stringify(profile);
+      if (!mayKeep(Buffer.byteLength(text))) {
+        log(`cpu profile: not kept, ${Buffer.byteLength(text)} bytes refused by the storage budget`);
+        return;
+      }
+      const file = path.join(dir, `cpu-start-${new Date().toISOString().replace(/[:.]/g, "-")}.cpuprofile`);
+      await writeFile(file, text);
+      log(`cpu profile: written to ${file} (${Buffer.byteLength(text)} bytes)`);
+    } finally {
+      running = false;
+      session.disconnect();
+    }
+  };
+  return {
+    begin() {
+      if (!wanted || begun) return;
+      begun = true;
+      void take().catch((error) => log(`cpu profile: failed — ${error.message}`));
+    },
+    active: () => running
+  };
+}

package/services/storage/processor-report.js

@@ -0,0 +1,186 @@
+/**
+ * @file Where this machine's processor goes: the proxy's own threads and every
+ * encoder it runs (torrent-tv/meta#177).
+ *
+ * The encoders are priced in seconds of work per second of film, and the
+ * torrent per megabyte moved. What neither price carries was seen only from
+ * outside: at a cold start on the addon host (#166 run 12, 2026-10-10) the main
+ * thread ran at 83-108 % of a core for thirty seconds, measured by a shell loop
+ * reading `/proc`, while the proxy's own log said nothing for 10.7 s.
+ *
+ * Read once a second, said once a minute as each part's mean and highest
+ * second, and every second while a cold start is being profiled. The Node
+ * process is counted ONCE, as `process.cpuUsage()` reports it; the split into
+ * threads only says where that time went. Each ffmpeg is its own process and
+ * is added beside it. Linux only for the split and for ffmpeg; elsewhere the
+ * process figure alone is said.
+ */
+
+import { readFile, readdir } from "node:fs/promises";
+
+/** Clock ticks per second of `/proc/<pid>/stat`, as in `encode/host-load.js`. */
+const CLOCK_TICKS_PER_SECOND = 100;
+
+/**
+ * The CPU seconds and the name in one `/proc/.../stat` text.
+ *
+ * The name can hold spaces and brackets, so it is everything between the first
+ * `(` and the LAST `)`, and the fields are counted from there.
+ *
+ * @param {string} text
+ * @returns {{ name: string, seconds: number } | null}
+ */
+export function parseStat(text) {
+  const open = text.indexOf("(");
+  const close = text.lastIndexOf(")");
+  if (open < 0 || close < open) return null;
+  const after = text.slice(close + 2).trim().split(/\s+/);
+  // After the name and the state, utime is the 12th field and stime the 13th.
+  const utime = Number(after[11]);
+  const stime = Number(after[12]);
+  if (!Number.isFinite(utime) || !Number.isFinite(stime)) return null;
+  return { name: text.slice(open + 1, close), seconds: (utime + stime) / CLOCK_TICKS_PER_SECOND };
+}
+
+/**
+ * Which part of the proxy a thread belongs to: the main thread, the torrent
+ * thread (Node names a worker's thread `WorkerThread`), or the rest — V8's
+ * helpers, libuv's pool, the inspector — counted together.
+ *
+ * @param {number} tid
+ * @param {string} name
+ * @param {number} pid
+ * @returns {"main" | "worker" | "other"}
+ */
+export function partOfThread(tid, name, pid) {
+  if (tid === pid) return "main";
+  if (name === "WorkerThread") return "worker";
+  return "other";
+}
+
+/**
+ * CPU seconds of this process's threads, by part, or null where `/proc` cannot
+ * be read.
+ *
+ * @param {number} [pid]
+ * @returns {Promise<{ main: number, worker: number, other: number } | null>}
+ */
+export async function readThreadSeconds(pid = process.pid) {
+  let tids;
+  try {
+    tids = await readdir(`/proc/${pid}/task`);
+  } catch {
+    return null;
+  }
+  const parts = { main: 0, worker: 0, other: 0 };
+  await Promise.all(tids.map(async (entry) => {
+    const tid = Number(entry);
+    const stat = await readFile(`/proc/${pid}/task/${entry}/stat`, "utf8").then(parseStat, () => null);
+    if (stat) parts[partOfThread(tid, stat.name, pid)] += stat.seconds;
+  }));
+  return parts;
+}
+
+/**
+ * CPU seconds of each of these processes that can be read now.
+ *
+ * @param {number[]} pids
+ * @returns {Promise<Map<number, number>>}
+ */
+export async function readProcessesSeconds(pids) {
+  const seconds = new Map();
+  await Promise.all(pids.map(async (pid) => {
+    const stat = await readFile(`/proc/${pid}/stat`, "utf8").then(parseStat, () => null);
+    if (stat) seconds.set(pid, stat.seconds);
+  }));
+  return seconds;
+}
+
+/**
+ * Shares of one core between two readings, per part. A thread or a process
+ * present in only one of the two readings contributes nothing, so a process
+ * that came or went in between is not read as a jump.
+ *
+ * @param {{ at: number, process: number, threads: object | null, ffmpeg: Map<number, number> }} before
+ * @param {{ at: number, process: number, threads: object | null, ffmpeg: Map<number, number> }} after
+ * @returns {{ seconds: number, process: number, main: number | null, worker: number | null, other: number | null, ffmpeg: number | null } | null}
+ */
+export function sharesBetween(before, after) {
+  const seconds = (after.at - before.at) / 1000;
+  if (!(seconds > 0)) return null;
+  const share = (from, to) => (Number.isFinite(from) && Number.isFinite(to) ? Math.max(0, to - from) / seconds : null);
+  let ffmpeg = null;
+  for (const [pid, value] of after.ffmpeg) {
+    const earlier = before.ffmpeg.get(pid);
+    if (earlier !== undefined && value >= earlier) ffmpeg = (ffmpeg ?? 0) + (value - earlier) / seconds;
+  }
+  return {
+    seconds,
+    process: share(before.process, after.process),
+    main: share(before.threads?.main, after.threads?.main),
+    worker: share(before.threads?.worker, after.threads?.worker),
+    other: share(before.threads?.other, after.threads?.other),
+    ffmpeg
+  };
+}
+
+/**
+ * One line: per part, the mean over the interval and its highest second, as a
+ * percentage of one core.
+ *
+ * @param {object[]} seconds - Per-second shares from `sharesBetween`.
+ * @returns {string}
+ */
+export function describeShares(seconds) {
+  const parts = ["process", "main", "worker", "other", "ffmpeg"];
+  const said = parts.map((part) => {
+    const values = seconds.map((one) => one[part]).filter((value) => Number.isFinite(value));
+    if (values.length === 0) return `${part} n/a`;
+    const mean = values.reduce((sum, value) => sum + value, 0) / values.length;
+    return `${part} ${Math.round(mean * 100)}% (highest second ${Math.round(Math.max(...values) * 100)}%)`;
+  });
+  return `${said.join(", ")} of a core over ${seconds.length}s`;
+}
+
+/**
+ * Read every second, say once a minute, and every second while `detailed()`
+ * is true.
+ *
+ * @param {object} params
+ * @param {(line: string) => void} params.log
+ * @param {() => number[]} params.ffmpegPids - The encoders running now.
+ * @param {() => boolean} [params.detailed]
+ * @param {number} [params.everyMs]
+ * @param {number} [params.sayEveryMs]
+ * @returns {{ stop: () => void }}
+ */
+export function startProcessorReport({ log, ffmpegPids, detailed = () => false, everyMs = 1000, sayEveryMs = 60_000 }) {
+  let previous = null;
+  let series = [];
+  let since = Date.now();
+  let reading = false;
+  const tick = async () => {
+    if (reading) return;
+    reading = true;
+    try {
+      const usage = process.cpuUsage();
+      const [threads, ffmpeg] = await Promise.all([readThreadSeconds(), readProcessesSeconds(ffmpegPids())]);
+      const now = { at: Date.now(), process: (usage.user + usage.system) / 1e6, threads, ffmpeg };
+      const shares = previous ? sharesBetween(previous, now) : null;
+      previous = now;
+      if (!shares) return;
+      series.push(shares);
+      if (detailed()) log(`processor: ${describeShares([shares])}`);
+      if (now.at - since >= sayEveryMs) {
+        log(`processor: ${describeShares(series)}`);
+        series = [];
+        since = now.at;
+      }
+    } finally {
+      reading = false;
+    }
+  };
+  const timer = setInterval(() => { void tick(); }, everyMs);
+  if (typeof timer.unref === "function") timer.unref();
+  return { stop: () => clearInterval(timer) };
+}

package/services/torrent/worker/client.js

@@ -475,12 +475,13 @@ export class TorrentWorkerClient {
    * @param {{ sourceKey: string, fileIndex: number, durationSeconds: number, zones: { from: number, to: number, priority: number }[] }} params
    * @returns {Promise<void>}
    */
-  async setPriorityMap({ sourceKey, fileIndex, zones, durationSeconds }) {
+  async setPriorityMap({ sourceKey, fileIndex, zones, durationSeconds, postedAt }) {
     return this.#caller.call(Command.PRIORITY_MAP, {
       sourceKey,
       fileIndex,
       zones,
-      durationSeconds
+      durationSeconds,
+      postedAt
     });
   }
 

package/services/torrent/worker/pool-adapter.js

@@ -164,11 +164,11 @@ export class WorkerTorrentPool {
    * @param {{ sourceKey: string, fileIndex: number, durationSeconds: number, zones: object[] }} params
    * @returns {Promise<void>}
    */
-  async setPriorityMap({ sourceKey, fileIndex, durationSeconds, zones }) {
+  async setPriorityMap({ sourceKey, fileIndex, durationSeconds, zones, postedAt }) {
     if (!sourceKey) {
       return;
     }
-    return this.#client.setPriorityMap({ sourceKey, fileIndex, durationSeconds, zones });
+    return this.#client.setPriorityMap({ sourceKey, fileIndex, durationSeconds, zones, postedAt });
   }
 
   /**

package/services/torrent/worker/worker.js

@@ -454,13 +454,17 @@ async function runCommand(command, params, id) {
     }
 
     case Command.PRIORITY_MAP: {
+      // When this handler began, on the clock the main thread posted by: the
+      // post to here holds the transfer and this thread's queue together
+      // (torrent-tv/meta#177).
+      const receivedAt = performance.timeOrigin + performance.now();
       // Source preparation owns adding the source. A delayed publication may
       // only update an existing source, never revive one after its viewer left.
       const zones = Array.isArray(params.zones) ? params.zones : [];
       // Nor may one for a file held whole, which has nothing left to fetch.
       const torrent = await knownTorrent(params.sourceKey);
       if (!torrent) {
-        return { appliedMs: null };
+        return { appliedMs: null, receivedAt, repliedAt: performance.timeOrigin + performance.now() };
       }
       // What applying a map costs this thread, told to whoever sent it: every
       // zone becomes a window of the register and the swarm is told again
@@ -469,7 +473,7 @@ async function runCommand(command, params, id) {
       ensureArrivalsWired(params.sourceKey, torrent);
       pool.applyPriorityMap(torrent, params.fileIndex, zones, params.durationSeconds);
       torrent.emit("priority-map-changed", params.fileIndex);
-      return { appliedMs: performance.now() - startedAt };
+      return { appliedMs: performance.now() - startedAt, receivedAt, repliedAt: performance.timeOrigin + performance.now() };
     }
 
     case Command.READ_RANGE: {

package/services/viewer/DownloadMaps.js

@@ -12,13 +12,21 @@ export class DownloadMaps {
   #nextEpoch = 0;
   #log;
   #now;
+  /**
+   * Milliseconds on the clock both threads read the same way, to the
+   * microsecond: what a publication's stages are measured with, the torrent
+   * thread's receipt included (torrent-tv/meta#177).
+   */
+  #clock;
 
-  constructor({ publish, resolvePlayback = async map => map.zones, log = null, now = Date.now }) {
+  constructor({ publish, resolvePlayback = async map => map.zones, log = null, now = Date.now,
+    clock = () => performance.timeOrigin + performance.now() }) {
     if (typeof publish !== "function") throw new TypeError("Download map publication is required.");
     this.#publish = publish;
     this.#resolvePlayback = resolvePlayback;
     this.#log = typeof log === "function" ? log : null;
     this.#now = now;
+    this.#clock = clock;
   }
 
   async playback({ sourceKey, fileIndex, durationSeconds, zones }) {
@@ -200,6 +208,7 @@ export class DownloadMaps {
   }
 
   #emit(file) {
+    const builtFrom = this.#clock();
     const zones = [...file.zones, ...file.nativeZones];
     for (const { ranges, requestId, priority, urgent, deadlineAt, order } of file.metadata.values()) {
       for (const [byteStart, byteEnd] of ranges) {
@@ -217,16 +226,32 @@ export class DownloadMaps {
     // orders nothing differently, so the deadlines' order is compared and not
     // their values.
     const shape = shapeOf(publication);
+    // WHAT A PUBLICATION COSTS, stage by stage (torrent-tv/meta#177): building
+    // and comparing it here, every time something is stated, sent or not;
+    // waiting behind the previous one; the synchronous post, which drops the
+    // zones repeated for the torrent and copies the rest for the other thread;
+    // from the post to the torrent thread's
+    // handler, which holds the transfer and that thread's queue together; and
+    // applying it there. A cold minute of #166 run 12 built 10 408 maps and
+    // sent 439, and nothing said what that cost.
+    const builtMs = this.#clock() - builtFrom;
     if (file.shape && sameShape(file.shape, shape)) {
-      this.#statsOf(file).unchanged += 1;
+      const stats = this.#statsOf(file);
+      stats.unchanged += 1;
+      stats.unsentBuildMs += builtMs;
       this.#report(file);
       return Promise.resolve();
     }
     file.shape = shape;
+    const askedAt = this.#clock();
     const pending = file.pending.then(() => {
       if (this.#files.get(`${file.sourceKey}:${file.fileIndex}`) !== file) return undefined;
       const sentAt = this.#now();
-      return Promise.resolve(this.#publish(publication)).then(reply => {
+      const postedAt = this.#clock();
+      const sent = this.#publish({ ...publication, postedAt });
+      const postMs = this.#clock() - postedAt;
+      return Promise.resolve(sent).then(reply => {
+        const answeredAt = this.#clock();
         // A torrent not yet in the thread applies nothing, so this map was not
         // delivered and the next one, however alike, has to be.
         if (reply?.appliedMs === null && file.shape === shape) file.shape = null;
@@ -235,6 +260,11 @@ export class DownloadMaps {
         stats.sent += 1;
         stats.zones.push(zones.length);
         stats.deliveredMs.push(this.#now() - sentAt);
+        stats.sentBuildMs.push(builtMs);
+        stats.waitedMs.push(postedAt - askedAt);
+        stats.postMs.push(postMs);
+        if (Number.isFinite(reply?.receivedAt)) stats.toHandlerMs.push(Math.max(0, reply.receivedAt - postedAt - postMs));
+        if (Number.isFinite(reply?.repliedAt)) stats.replyMs.push(Math.max(0, answeredAt - reply.repliedAt));
         if (Number.isFinite(reply?.appliedMs)) stats.appliedMs.push(reply.appliedMs);
         this.#report(file);
         return reply;
@@ -249,7 +279,7 @@ export class DownloadMaps {
   }
 
   #statsOf(file) {
-    file.stats ??= { since: this.#now(), sent: 0, unchanged: 0, zones: [], deliveredMs: [], appliedMs: [] };
+    file.stats ??= emptyStats(this.#now());
     return file.stats;
   }
 
@@ -264,11 +294,28 @@ export class DownloadMaps {
       `zones median ${middle(stats.zones)} max ${largest(stats.zones)}; ` +
       `delivered median ${middle(stats.deliveredMs)}ms max ${largest(stats.deliveredMs)}ms (${total(stats.deliveredMs)}ms in all), ` +
       `applied in the torrent thread median ${middle(stats.appliedMs)}ms max ${largest(stats.appliedMs)}ms ` +
-      `(${total(stats.appliedMs)}ms in all)`);
-    file.stats = { since: now, sent: 0, unchanged: 0, zones: [], deliveredMs: [], appliedMs: [] };
+      `(${total(stats.appliedMs)}ms in all); ` +
+      `stages of a sent map — built ${stage(stats.sentBuildMs)}, waited behind the previous ${stage(stats.waitedMs)}, ` +
+      `posted ${stage(stats.postMs)}, post to the torrent thread's handler ${stage(stats.toHandlerMs)}, ` +
+      `reply back ${stage(stats.replyMs)}; maps built and not sent took ${total([stats.unsentBuildMs])}ms here`);
+    file.stats = emptyStats(now);
   }
 }
 
+/** @param {number} since */
+function emptyStats(since) {
+  return { since, sent: 0, unchanged: 0, zones: [], deliveredMs: [], appliedMs: [],
+    sentBuildMs: [], waitedMs: [], postMs: [], toHandlerMs: [], replyMs: [], unsentBuildMs: 0 };
+}
+
+/** One stage's median, largest and sum, in milliseconds with tenths. @param {number[]} values */
+function stage(values) {
+  if (values.length === 0) return "n/a";
+  const sorted = [...values].sort((left, right) => left - right);
+  const sum = values.reduce((total, value) => total + value, 0);
+  return `median ${sorted[Math.floor(sorted.length / 2)].toFixed(1)}ms max ${sorted.at(-1).toFixed(1)}ms sum ${Math.round(sum)}ms`;
+}
+
 /** How many numbers describe one zone's part in what the torrent does. */
 const ZONE_FIELDS = 7;