@torrent-tv/proxy 2.75.0 → 2.76.1

package/services/orchestrators/EncodeOrchestrator.js

@@ -0,0 +1,359 @@
+/**
+ * @file How many encoders run on this proxy, on which outputs, and over which
+ * stretches.
+ *
+ * The application layer over `encode/`. It holds four things and owns none of
+ * their rules:
+ *
+ * 1. what viewers want (`SegmentDemand`), stated once each and read as a union;
+ * 2. what has been made and what is being made, one `CoverageMap` per output;
+ * 3. the encoders that are running (`EncodeRun`), each over a stretch;
+ * 4. a tally of how every run ended, which is what makes "abnormal endings do
+ *    not happen" a number rather than an impression.
+ *
+ * The decision itself is `EncodePlan.planEncoders`, from numbers alone. This
+ * carries it out, and everything it cannot know is injected: how many encoders
+ * this machine can afford, how a run is built for a given stretch, and which
+ * segments already exist.
+ *
+ * **No viewer reaches the decision.** A viewer states a window and is forgotten
+ * as a name; what the plan sees is a union of windows. That is the rule the
+ * layer exists for, stated by the user 2026-09-04: requests come from any
+ * viewers in any number, encoders are managed to suit them, and viewers get the
+ * result when it is ready.
+ */
+
+import { CoverageMap } from "../encode/CoverageMap.js";
+import { firstUnmetWant, planEncoders } from "../encode/EncodePlan.js";
+import { ENCODE_EXIT } from "../encode/encode-exit.js";
+import { SegmentDemand } from "../encode/SegmentDemand.js";
+
+export class EncodeOrchestrator {
+  /** Output address to what has been made of it. @type {Map<string, CoverageMap>} */
+  #coverage = new Map();
+
+  /** Output address to the runs on it. @type {Map<string, import("../encode/EncodeRun.js").EncodeRun[]>} */
+  #runs = new Map();
+
+  /** How runs have ended, by cause. @type {Map<string, number>} */
+  #endings = new Map();
+
+  /**
+   * @param {object} params
+   * @param {(address: string) => number} params.maxRunsFor - How many encoders
+   *   this machine can afford on one output. The same arithmetic that decides
+   *   the quality offer; measured per host, never chosen here.
+   * @param {(params: { address: string, from: number, to: number }) =>
+   *   import("../encode/EncodeRun.js").EncodeRun} params.makeRun - Build a run
+   *   for a stretch. What to read, what to map and how to cut belong to whoever
+   *   knows the source.
+   * @param {number} params.segmentSeconds
+   * @param {number} params.restartCostSec - Measured: 0.12 s on the addon host.
+   * @param {{ info: (line: string) => void, warn: (line: string) => void }} params.logger
+   * @param {() => number} [params.now]
+   */
+  constructor({ maxRunsFor, makeRun, segmentSeconds, restartCostSec, logger, now }) {
+    this.demand = new SegmentDemand();
+    this.maxRunsFor = maxRunsFor;
+    this.makeRun = makeRun;
+    this.segmentSeconds = segmentSeconds;
+    this.restartCostSec = restartCostSec;
+    this.logger = logger;
+    this.now = typeof now === "function" ? now : Date.now;
+  }
+
+  /**
+   * The map of one output, made on first mention.
+   *
+   * @param {string} address
+   * @returns {CoverageMap}
+   */
+  coverageOf(address) {
+    let map = this.#coverage.get(address);
+    if (!map) {
+      map = new CoverageMap();
+      this.#coverage.set(address, map);
+    }
+    return map;
+  }
+
+  /**
+   * @param {string} address
+   * @returns {import("../encode/EncodeRun.js").EncodeRun[]}
+   */
+  runsOn(address) {
+    return this.#runs.get(address) ?? [];
+  }
+
+  /**
+   * How long an output is, once its playlist is known.
+   *
+   * @param {string} address
+   * @param {number} segmentCount
+   */
+  setSegmentCount(address, segmentCount) {
+    this.coverageOf(address).setSegmentCount(segmentCount);
+  }
+
+  /**
+   * Segments that already exist — from a previous life of this process, or
+   * because somebody else made them. Told to the map, which is what stops an
+   * encoder being started to make them again.
+   *
+   * @param {string} address
+   * @param {Iterable<number>} indexes
+   */
+  noteAlreadyMade(address, indexes) {
+    this.coverageOf(address).markReadyAll(indexes);
+  }
+
+  /**
+   * A viewer states what it is waiting for. Replaces whatever it said before.
+   *
+   * @param {object} params
+   * @param {string} params.claimant
+   * @param {string} params.address
+   * @param {number} params.from
+   * @param {number} params.to
+   */
+  want({ claimant, address, from, to }) {
+    this.demand.state({ claimant, address, from, to, statedAt: this.now() });
+  }
+
+  /**
+   * A viewer has gone.
+   *
+   * @param {string} claimant
+   */
+  release(claimant) {
+    this.demand.forget(claimant);
+  }
+
+  /**
+   * A segment has been finished, by whichever run made it.
+   *
+   * @param {string} address
+   * @param {number} index
+   */
+  noteProduced(address, index) {
+    this.coverageOf(address).markReady(index);
+    for (const run of this.runsOn(address)) {
+      run.noteProduced(index);
+    }
+  }
+
+  /**
+   * @param {string} address
+   * @param {object} run
+   * @param {number} speedX
+   */
+  noteSpeed(address, wanted, speedX) {
+    for (const run of this.runsOn(address)) {
+      if (run === wanted) {
+        run.noteSpeed(speedX);
+      }
+    }
+  }
+
+  /**
+   * Decide and act, for every output anybody wants anything of and every output
+   * that still has an encoder on it.
+   *
+   * Safe to call as often as anything changes: the plan is a function of the
+   * state, so a pass that finds nothing to change does nothing.
+   */
+  reconcile() {
+    const addresses = new Set([...this.demand.addresses(), ...this.#runs.keys()]);
+    for (const address of addresses) {
+      this.#reconcileOne(address);
+    }
+  }
+
+  /**
+   * @param {string} address
+   */
+  #reconcileOne(address) {
+    const coverage = this.coverageOf(address);
+    // A run that has ended and said nothing. One built here reports its own
+    // ending and is released by `noteEnded`; one ADOPTED from elsewhere — a
+    // session whose encoder stopped — has no such promise, and its claim would
+    // otherwise sit in the map for the life of the process, telling the plan
+    // that a stretch nobody is making is being made. Nothing would ever be
+    // started there again.
+    for (const run of this.runsOn(address)) {
+      if (!run.isAlive && !run.isStopping) {
+        this.noteEnded({
+          address,
+          run,
+          ending: ENCODE_EXIT.GONE,
+          because: "it is no longer running, and it did not say so"
+        });
+      }
+    }
+    const windows = this.demand.windowsOn(address).map((window) => ({
+      from: window.from,
+      to: window.to
+    }));
+    const live = this.runsOn(address).filter((run) => run.isAlive);
+    const actions = planEncoders({
+      coverage,
+      windows,
+      // The runs themselves. The plan is arithmetic and reads four numbers off
+      // each; what it hands back names the run by BEING it, so nothing has to
+      // invent a token to refer to one by.
+      runs: live,
+      maxRuns: Math.max(0, this.maxRunsFor(address)),
+      segmentSeconds: this.segmentSeconds,
+      restartCostSec: this.restartCostSec
+    });
+
+    for (const action of actions) {
+      if (action.type === "stop") {
+        this.#stop(action.run, action.because);
+        continue;
+      }
+      if (action.type === "move") {
+        // A running encoder's position cannot be changed — it is fixed when the
+        // process starts — so a move is this one ending and another beginning
+        // where the material is missing. Both halves are recorded as what they
+        // are, which is why the ending of a moved run is not called normal.
+        this.#stop(action.run, action.because);
+        this.#start(address, action.from, action.to, action.because);
+        continue;
+      }
+      if (action.type === "start") {
+        this.#start(address, action.from, action.to, action.because);
+        continue;
+      }
+      // A run that stays keeps its claim current: the free stretch ahead of it
+      // may have shrunk since it was given one.
+      coverage.claim(action.run, action.from, action.to);
+    }
+  }
+
+  /**
+   * @param {string} address
+   * @param {number} from
+   * @param {number} to
+   * @param {string} because
+   */
+  #start(address, from, to, because) {
+    // The run names itself: identity is a property of the thing, and two
+    // places minting names is how one stops being unique.
+    const run = this.makeRun({ address, from, to });
+    if (!run) {
+      // Not necessarily a failure: making an encoder can take a probe and a
+      // keyframe read, and this call is arithmetic that must not wait on
+      // either. Whoever builds one answers with nothing while it is on its way,
+      // and the next pass sees it.
+      this.logger.info(`encode: an encoder for #${from}..#${to} of ${address} is not there yet`);
+      return;
+    }
+    const onThisOutput = this.#runs.get(address) ?? [];
+    onThisOutput.push(run);
+    this.#runs.set(address, onThisOutput);
+    this.coverageOf(address).claim(run, from, to);
+    run.start(because);
+  }
+
+  /**
+   * Take charge of a run this class did not start.
+   *
+   * The browser asks for a stream and a run begins for it, long before this
+   * class has an opinion. Left unknown, that run would be invisible to the plan
+   * — which would then start a second encoder over the same numbers, believing
+   * nothing was being made there. So whoever starts one hands it over, and from
+   * then on it is planned like any other.
+   *
+   * @param {string} address
+   * @param {{ id: string, from: number, to: number, head: number, speedX: number, isAlive: boolean, stop: (because: string) => void }} run
+   */
+  adopt(address, run) {
+    if (!run) {
+      return;
+    }
+    const onThisOutput = this.#runs.get(address) ?? [];
+    if (onThisOutput.includes(run)) {
+      return;
+    }
+    onThisOutput.push(run);
+    this.#runs.set(address, onThisOutput);
+    this.coverageOf(address).claim(run, run.from, run.to);
+  }
+
+  /**
+   * @param {object} run
+   * @param {string} because
+   */
+  #stop(run, because) {
+    run.stop(because);
+  }
+
+  /**
+   * A run has ended, however it ended. Its stretch goes back to the map — what
+   * it finished stays made — and the ending is counted.
+   *
+   * Wired by whoever builds the run, so that a run built outside this class is
+   * still accounted for.
+   *
+   * @param {import("../encode/EncodeRun.js").RunEnded} ended
+   */
+  noteEnded(ended) {
+    this.coverageOf(ended.address).release(ended.run);
+    const remaining = this.runsOn(ended.address).filter((run) => run !== ended.run);
+    if (remaining.length === 0) {
+      this.#runs.delete(ended.address);
+    } else {
+      this.#runs.set(ended.address, remaining);
+    }
+    this.#endings.set(ended.ending, (this.#endings.get(ended.ending) ?? 0) + 1);
+  }
+
+  /**
+   * How runs have ended over the life of this process, by cause.
+   *
+   * The abnormal classes are meant to stand at zero. Without the count,
+   * "we understand why it ended" is indistinguishable from "we noticed it once".
+   *
+   * @returns {Record<string, number>}
+   */
+  endings() {
+    /** @type {Record<string, number>} */
+    const tally = {};
+    for (const ending of Object.values(ENCODE_EXIT)) {
+      tally[ending] = this.#endings.get(ending) ?? 0;
+    }
+    return tally;
+  }
+
+  /**
+   * One line saying what this proxy is encoding and whether anybody is waiting.
+   *
+   * `waiting` is the point of it: a proxy with encoders running and a viewer
+   * still stopped at a segment nobody is making is the failure this layer was
+   * built to remove, and it is visible here rather than inferred from a log.
+   *
+   * @returns {string}
+   */
+  describe() {
+    const parts = [];
+    for (const address of new Set([...this.demand.addresses(), ...this.#runs.keys()])) {
+      const coverage = this.coverageOf(address);
+      const windows = this.demand.windowsOn(address).map((w) => ({ from: w.from, to: w.to }));
+      const waiting = firstUnmetWant(coverage, windows);
+      const runs = this.runsOn(address)
+        .map((run) => `#${run.head}..#${run.to}@${run.speedX.toFixed(1)}x`)
+        .join(" ");
+      parts.push(
+        `${address.slice(0, 60)} ready=${coverage.stats().ready} ` +
+        `viewers=${windows.length} runs=[${runs}] ` +
+        `waiting=${waiting === null ? "nobody" : `#${waiting}`}`
+      );
+    }
+    const tally = this.endings();
+    const endings = Object.entries(tally)
+      .map(([cause, count]) => `${cause}=${count}`)
+      .join(" ");
+    return `encode: ${parts.length === 0 ? "nothing wanted" : parts.join(" | ")} :: endings ${endings}`;
+  }
+}

package/services/output/LiveOutputs.js

@@ -0,0 +1,213 @@
+/**
+ * @file Which outputs of one file exist right now, and what each of them is.
+ *
+ * Every question here is answered by walking the live sessions and looking at
+ * what they ARE — the same file, a step, a soundtrack, this height — and not by
+ * following a list of ids anybody keeps. A list of ids is a link between
+ * sessions: it ties their lifetimes together, it goes stale when one of them is
+ * disposed, and it has to be cleaned from the other side. What an output is is
+ * enough to find it, which is the rule `OutputSpec` exists for.
+ *
+ * Nothing here writes anything except the two answers a session memoizes about
+ * itself, and nothing here knows about encoders, viewers, the torrent or the
+ * disk. It is the layer the quality budget and the serving path both stand on,
+ * and it is separated first for that reason.
+ */
+
+import { variantHeightsFor } from "./ladder.js";
+
+export class LiveOutputs {
+  /**
+   * @param {object} params
+   * @param {Map<string, object>} params.sessionsById - The live sessions. Read,
+   *   never written.
+   */
+  constructor({ sessionsById }) {
+    this.sessionsById = sessionsById;
+  }
+
+  /**
+   * Every live session of one file: the picture, its quality steps, and the
+   * soundtracks published separately.
+   *
+   * The file is what they share, so the file is what this asks about. Where the
+   * sums this feeds are concerned that is also the right question: two pictures
+   * of one file are two encoders on one machine whether or not anybody thinks
+   * of them as one film.
+   *
+   * @param {object} session
+   * @returns {object[]}
+   */
+  familyOf(session) {
+    const family = [session];
+    const key = session?.file?.key;
+    for (const other of this.sessionsById.values()) {
+      if (other === session || other.state === "disposed" || other.file?.key !== key) {
+        continue;
+      }
+      family.push(other);
+    }
+    return family;
+  }
+
+  /**
+   * The soundtracks published separately for this picture, live ones only.
+   *
+   * @param {object} base
+   * @returns {object[]}
+   */
+  renditionsOf(base) {
+    return this.familyOf(base).filter((session) => session !== base && session.audioOnly === true);
+  }
+
+  /**
+   * The quality steps of this picture, live ones only.
+   *
+   * A step is a session made as one — `isStep`, written where it is created —
+   * and not merely "another session of this file that carries a picture". The
+   * difference is the second picture: one file can hold two — a browser that
+   * understands rendition groups and one that needs the sound muxed in produce
+   * two — and calling one of them a step of the other would let a switch away
+   * from a step stop the encoder of somebody else's picture.
+   *
+   * @param {object} base
+   * @returns {object[]}
+   */
+  stepsOf(base) {
+    return this.familyOf(base).filter((session) => session !== base && session.isStep === true);
+  }
+
+  /**
+   * The picture a step belongs to, or the session itself when it is not a step.
+   *
+   * How a session came to be is a fact about it, not a link to another session
+   * — so a step whose picture has gone answers for itself rather than following
+   * a dead reference, and nothing has to be cleaned from the other side when
+   * one of them ends.
+   *
+   * One file can carry two pictures at once, and then this returns whichever
+   * was made first. Everything asked of the answer is a fact of the FILE and of
+   * this host: what heights can be offered, what a step costs, when the budget
+   * last acted. Two pictures of one file answer all of those alike.
+   *
+   * @param {object} session
+   * @returns {object}
+   */
+  pictureOf(session) {
+    if (!session || session.isStep !== true) {
+      return session;
+    }
+    for (const other of this.familyOf(session)) {
+      if (other.isStep !== true && other.audioOnly !== true) {
+        return other;
+      }
+    }
+    return session;
+  }
+
+  /**
+   * Which variant a session IS, as a height. Zero encode height means "keep the
+   * source", so the source's own height is the answer.
+   *
+   * Settled once and then kept, because it is a NAME — the player addresses the
+   * variant by it for the whole session, having fetched the master exactly
+   * once. The height a session encodes at is not stable: the realtime budget
+   * steps it down when the host cannot keep up. Deriving the name afresh each
+   * time would mean a downshift silently renames the variant the viewer is
+   * watching, and the next segment request under the old name would build a
+   * SECOND session at the height the host had just proved it could not manage.
+   * A downshift changes the picture inside the variant instead, which is what
+   * it has always done.
+   *
+   * @param {object} session
+   * @returns {number}
+   */
+  variantHeightOf(session) {
+    if (Number.isInteger(session.variantHeight) && session.variantHeight > 0) {
+      return session.variantHeight;
+    }
+    const encodeHeight = Number(session.output.encodeHeight) || 0;
+    session.variantHeight = encodeHeight > 0
+      ? encodeHeight
+      : Math.round(Number(session.file.height) || 0);
+    return session.variantHeight;
+  }
+
+  /**
+   * The height a session's encoder is actually producing, or 0 when it produces
+   * no encoded picture of its own (a copy, or a soundtrack).
+   *
+   * A COPY must never be adopted: it costs no encoder at all, so handing it to
+   * a request for a re-encoded rung would give away the one thing this host can
+   * always serve.
+   *
+   * @param {object} session
+   * @returns {number}
+   */
+  producedHeightOf(session) {
+    if (!session || session.transcodeVideo !== true || session.audioOnly === true) {
+      return 0;
+    }
+    return Math.round(Number(session.output.encodeHeight) || 0);
+  }
+
+  /**
+   * The heights this file's variants CAN be spliced at — a fact about the
+   * source and the cut grid, settled once and never moved.
+   *
+   * Separate from which of them are worth OFFERING to the viewer right now, on
+   * a machine whose load moves every five seconds. Both were the same list
+   * until 2026-08-18, and that is what broke playback outright: the browser is
+   * told at session creation that a master playlist exists, and 192 ms later —
+   * after the session's own encoder had started and the first supply reading
+   * had arrived — the live list had fallen from five rungs to one,
+   * `buildMasterPlaylist` returned null for having fewer than two, and the
+   * master answered 404 to the very session that had just published it. hls.js
+   * treats that as fatal and unrecoverable, so nothing played at all (session
+   * `4ef731d8`, "Moana (2016).mkv", 17:43:01).
+   *
+   * A live figure may decide what to offer. It may not decide whether a
+   * published document exists.
+   *
+   * @param {object} session
+   * @returns {number[]} Largest first.
+   */
+  splicableHeights(session) {
+    const owner = this.pictureOf(session);
+    if (Array.isArray(owner.splicableHeights)) {
+      return owner.splicableHeights;
+    }
+    const heights = new Set(variantHeightsFor(Number(owner.file.height) || 0));
+    const own = this.variantHeightOf(owner);
+    if (own > 0) {
+      heights.add(own);
+    }
+    owner.splicableHeights = [...heights].sort((left, right) => right - left);
+    return owner.splicableHeights;
+  }
+
+  /**
+   * Whether this stream publishes a master playlist at all — that is, whether
+   * there is anything for a player to move BETWEEN.
+   *
+   * Asked in one place because two callers depend on the same answer and used
+   * to compute it differently: the builder refused a copied stream whose cut
+   * grid is a fiction, while the budget looked only at how many heights could
+   * in principle be spliced. A copy with no readable keyframe index therefore
+   * had requests recorded against it — asking a player with no variants to
+   * change variant, once every window, for the whole film.
+   *
+   * @param {object} session
+   * @returns {boolean}
+   */
+  publishesVariants(session) {
+    const owner = this.pictureOf(session);
+    // A copy can only be cut where the source already has a keyframe, so a rung
+    // meant to splice into it has to be cut at exactly those times. A copy that
+    // fell back to an even grid ffmpeg does not cut on has nothing to align to.
+    if (!owner.transcodeVideo && owner.timeline.cutGrid !== "keyframe") {
+      return false;
+    }
+    return this.splicableHeights(owner).length >= 2;
+  }
+}

package/services/output/Output.js

@@ -0,0 +1,94 @@
+/**
+ * @file What one output is encoded AS, decided once.
+ *
+ * `OutputSpec` says what an output is — which tracks, in what form, cut how.
+ * This is the other half: the shape the encoder is actually given for it. The
+ * box in pixels, the frame rate, the speed setting, whether the picture is tone
+ * mapped down from HDR.
+ *
+ * **Why it is not a fact of a session.** It is decided by the realtime budget
+ * at the moment a session is created — what this machine could hold just then —
+ * so two sessions of one output, made minutes apart, could be given different
+ * shapes while claiming the same identity. Everything downstream assumes
+ * otherwise: a segment of one is supposed to be interchangeable with a segment
+ * of the other, and the master playlist names one `RESOLUTION` for both.
+ *
+ * Decided once per output and held here, that cannot happen. What the budget
+ * learns afterwards moves the RATE cap, which is deliberately not here: rate
+ * control appears in neither the SPS nor the PPS, so it can move under a player
+ * that has already cached the init. The size cannot, which is exactly why the
+ * size belongs to the output and the cap belongs to the run.
+ */
+
+export class Output {
+  /**
+   * @param {object} params
+   * @param {number} params.encodeWidth - 0 means the source's own width.
+   * @param {number} params.encodeHeight - 0 means the source's own height.
+   * @param {number} params.outputFps
+   * @param {string | null} params.softwarePreset - The speed setting, where the
+   *   encoder has a ladder and one was chosen from it.
+   * @param {boolean} params.applyTonemap
+   */
+  constructor({ encodeWidth, encodeHeight, outputFps, softwarePreset, applyTonemap }) {
+    this.encodeWidth = Number.isFinite(encodeWidth) ? encodeWidth : 0;
+    this.encodeHeight = Number.isFinite(encodeHeight) ? encodeHeight : 0;
+    this.outputFps = Number.isFinite(outputFps) && outputFps > 0 ? outputFps : 0;
+    this.softwarePreset = typeof softwarePreset === "string" ? softwarePreset : null;
+    this.applyTonemap = applyTonemap === true;
+  }
+}
+
+/**
+ * The shapes this proxy has decided, one per output.
+ *
+ * Keyed by `OutputSpec.toKey()` and by nothing else: the shape is a property of
+ * what is being produced, and two requests that produce the same thing must be
+ * given the same one however far apart they arrive.
+ */
+export class Outputs {
+  /** @type {Map<string, Output>} */
+  #byKey = new Map();
+
+  /**
+   * The shape for this output, decided by `decide` the first time it is asked
+   * for and never again.
+   *
+   * @param {string} key
+   * @param {() => Output} decide
+   * @returns {Output}
+   */
+  get(key, decide) {
+    let output = this.#byKey.get(key);
+    if (!output) {
+      output = decide();
+      this.#byKey.set(key, output);
+    }
+    return output;
+  }
+
+  /**
+   * Drop every shape nobody is holding.
+   *
+   * Same reason the timelines are swept: a map that only grows is the shape of
+   * half the memory faults recorded in this project.
+   *
+   * @param {Set<Output>} inUse
+   * @returns {number}
+   */
+  forgetUnused(inUse) {
+    let dropped = 0;
+    for (const [key, output] of [...this.#byKey]) {
+      if (!inUse.has(output)) {
+        this.#byKey.delete(key);
+        dropped += 1;
+      }
+    }
+    return dropped;
+  }
+
+  /** @returns {number} */
+  get size() {
+    return this.#byKey.size;
+  }
+}