@torrent-tv/proxy 2.107.51 → 2.107.52

package/package.json

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

package/services/torrent/download/TailRepeat.js

@@ -0,0 +1,155 @@
+/**
+ * @file Decide when a second copy of a late missing block is useful.
+ *
+ * WebTorrent normally owns picking, queues and request reassignment. This
+ * exception is bounded to the currently required urgent pieces, a tail of at
+ * most 16 missing blocks, requests older than one wire queue, and two copies
+ * per block. The injected adapter is the only place that touches WebTorrent's
+ * private piece/reservation/request state.
+ */
+
+/** `PIPELINE_MAX_DURATION`: WebTorrent sizes each wire queue to one second. */
+const WIRE_QUEUE_MS = 1000;
+const SHORT_TAIL_BLOCKS = 16;
+const MAX_COPIES = 2;
+
+export class TailRepeat {
+  #requiredPieces;
+  #adapter;
+  #schedule;
+  #wake;
+  #clear;
+  #scheduled = false;
+  #timer = null;
+  #timerAt = Number.POSITIVE_INFINITY;
+  #disposed = false;
+  #unwatch;
+  #log;
+  #now;
+  #reportedUnavailable = false;
+
+  /**
+   * @param {object} params
+   * @param {() => Array<{ from: number, to: number }>} params.requiredPieces
+   * @param {{ observe: Function, repeatBlock: Function, watch: Function }} params.adapter
+   * @param {(work: () => void) => void} [params.schedule]
+   * @param {(work: () => void, ms: number) => unknown} [params.wake]
+   * @param {(handle: unknown) => void} [params.clear]
+   * @param {(line: string) => void} [params.log]
+   * @param {() => number} [params.now]
+   */
+  constructor({ requiredPieces, adapter, schedule = setImmediate, wake = setTimeout, clear = clearTimeout, log = null, now = Date.now }) {
+    this.#requiredPieces = requiredPieces;
+    this.#adapter = adapter;
+    this.#schedule = schedule;
+    this.#wake = wake;
+    this.#clear = clear;
+    this.#log = log;
+    this.#now = now;
+    this.totals = { duplicated: 0, looks: 0, lateBlocks: 0 };
+    try {
+      this.#unwatch = adapter.watch(() => this.poke(), () => { this.totals.lateBlocks += 1; });
+    } catch {
+      this.#reportUnavailable();
+      this.#unwatch = null;
+    }
+  }
+
+  /** Look at the tails once this turn of the event loop is over. */
+  poke() {
+    if (this.#scheduled || this.#disposed) return;
+    this.#scheduled = true;
+    this.#schedule(() => this.#look());
+  }
+
+  /** Stop watching and cancel the one armed age check. */
+  dispose() {
+    this.#disposed = true;
+    this.#unwatch?.();
+    this.#unwatch = null;
+    if (this.#timer !== null) this.#clear(this.#timer);
+    this.#timer = null;
+  }
+
+  #lookAgainAt(at, now) {
+    if (!Number.isFinite(at) || at >= this.#timerAt || this.#disposed) return;
+    if (this.#timer !== null) this.#clear(this.#timer);
+    this.#timerAt = at;
+    this.#timer = this.#wake(() => {
+      this.#timer = null;
+      this.#timerAt = Number.POSITIVE_INFINITY;
+      this.poke();
+    }, Math.max(0, at - now));
+    this.#timer?.unref?.();
+  }
+
+  #look() {
+    this.#scheduled = false;
+    if (this.#disposed) return;
+    this.totals.looks += 1;
+    const now = this.#now();
+    let dueAt = Number.POSITIVE_INFINITY;
+    let unplaced = 0;
+    const asked = [];
+
+    for (const { from, to } of this.#requiredPieces()) {
+      for (let pieceIndex = from; pieceIndex <= to; pieceIndex += 1) {
+        if (this.#disposed) return;
+        let observation;
+        try {
+          observation = this.#adapter.observe(pieceIndex, SHORT_TAIL_BLOCKS);
+        } catch {
+          this.#reportUnavailable();
+          continue;
+        }
+        if (!observation?.available) {
+          this.#reportUnavailable();
+          continue;
+        }
+        if (observation.missingCount === 0 || observation.missingCount > SHORT_TAIL_BLOCKS) continue;
+
+        let pieceCopies = 0;
+        for (const block of observation.blocks) {
+          if (block.copies === 0 || block.copies >= MAX_COPIES) continue;
+          const firstAskedAt = block.firstAskedAt ?? Number.NEGATIVE_INFINITY;
+          if (now - firstAskedAt < WIRE_QUEUE_MS) {
+            dueAt = Math.min(dueAt, firstAskedAt + WIRE_QUEUE_MS);
+            continue;
+          }
+          let result;
+          try {
+            result = this.#adapter.repeatBlock(pieceIndex, block.index);
+          } catch {
+            this.#reportUnavailable();
+            continue;
+          }
+          if (result === "unavailable") {
+            this.#reportUnavailable();
+            continue;
+          }
+          if (result === "placed") {
+            pieceCopies += 1;
+            this.totals.duplicated += 1;
+          } else {
+            unplaced += 1;
+          }
+        }
+        if (pieceCopies > 0) asked.push(`${pieceIndex}:${pieceCopies}/${observation.missingCount}`);
+      }
+    }
+
+    if (asked.length > 0) {
+      this.#log?.(`tail: asked a second peer for the last blocks of piece:blocks/missing ${asked.join(" ")}; ` +
+        `${this.totals.duplicated} block copies asked so far, ${this.totals.lateBlocks} block(s) arrived after their piece was complete`);
+    }
+    if (unplaced > 0) dueAt = Math.min(dueAt, now + WIRE_QUEUE_MS);
+    this.#lookAgainAt(dueAt, now);
+  }
+
+  #reportUnavailable() {
+    if (this.#reportedUnavailable) return;
+    this.#reportedUnavailable = true;
+    this.#adapter.disable?.();
+    this.#log?.("tail: bounded repeat unavailable; using WebTorrent's ordinary picker");
+  }
+}

package/services/torrent/torrent-pool.js

@@ -25,14 +25,15 @@ import { deadlineOfMapZone, levelOfMapZone, priorityOfMapZone } from "./map-zone
 import { deriveSourceKey } from "../../utils/torrent-source-key.js";
 import { noteTorrentDestroyed } from "./destroyed-torrents.js";
 import { PieceTimings, describePieceTiming } from "./piece-timing.js";
-import { TailRepeat } from "./worker/tail-repeat.js";
+import { TailRepeat } from "./download/TailRepeat.js";
+import { WebTorrentTailRepeatAdapter } from "./worker/WebTorrentTailRepeatAdapter.js";
 import { tracePieceStorePut } from "./worker/trace-piece-store-put.js";
 import { beginSwarmLifecycleTrace, noteSwarmDiscovery, noteSwarmMetadata, noteSwarmPeer } from "./worker/trace-swarm-lifecycle.js";
 
 /**
  * The second-peer requests for the last blocks of a piece somebody waits for,
  * one per torrent, made when the torrent is first watched and stopped when it
- * is forgotten (`worker/tail-repeat.js`).
+ * is forgotten (`download/TailRepeat.js`).
  *
  * @type {WeakMap<object, TailRepeat>}
  */
@@ -1901,7 +1902,8 @@ export class TorrentPool {
     // per piece: a 2.3 GB film is 563.
     const timings = new PieceTimings();
     const waitTracePieceStarts = new Map();
-    tailRepeats.set(torrent, new TailRepeat({ torrent, requiredPieces: () => demandFor(torrent).selection.requiredPieces(),
+    tailRepeats.set(torrent, new TailRepeat({ adapter: new WebTorrentTailRepeatAdapter(torrent),
+      requiredPieces: () => demandFor(torrent).selection.requiredPieces(),
       log: (line) => logger.info(`download ${label()} ${line}`) }));
     torrent.on("wire", (wire) => {
       // WebTorrent asks a wire for a block by calling `request` and states
@@ -1922,7 +1924,7 @@ export class TorrentPool {
             trace("W8", "begin", { piece: index, startedAt, firstOffset: offset, blockLength: length });
           }
           // When this wire was asked for the block: how long it has held it is
-          // what decides whether a second peer is asked (`duplicateTailFor`).
+          // what decides whether a second peer is asked (download/TailRepeat).
           this.requests.at(-1).askedAt = now;
         }
         return answer;

package/services/torrent/worker/WebTorrentTailRepeatAdapter.js

@@ -0,0 +1,216 @@
+/**
+ * @file The narrow WebTorrent 2.8.5 adapter used by torrent/download/TailRepeat.
+ *
+ * This is the only live caller allowed to inspect piece buffers and wire
+ * queues, or to touch Piece.cancel/reserve and Torrent._request for bounded
+ * late-tail repetition. Keep library-private assumptions here and update the
+ * compatibility check when the pinned WebTorrent/torrent-piece pair changes.
+ */
+
+const BLOCK_BYTES = 1 << 14;
+
+function speedOf(wire) {
+  try {
+    const speed = wire?.downloadSpeed?.();
+    return Number.isFinite(speed) ? speed : 0;
+  } catch {
+    return 0;
+  }
+}
+
+function usableWires(torrent, pieceIndex) {
+  const wires = Array.isArray(torrent?.wires) ? torrent.wires : [];
+  return wires.filter((wire) => {
+    // WebTorrent's _request uses reserveRemaining/chunkLengthRemaining for a
+    // webseed, which requests the piece suffix rather than one bounded block.
+    if (!wire || wire.type === "webSeed" || wire.destroyed || wire.peerChoking) return false;
+    try {
+      return wire.peerPieces?.get?.(pieceIndex) === true;
+    } catch {
+      return false;
+    }
+  }).sort((left, right) => speedOf(right) - speedOf(left));
+}
+
+function requestCoversBlock(request, pieceIndex, blockIndex, chunks) {
+  if (request?.piece !== pieceIndex || !Number.isFinite(request.offset) || request.offset < 0) return false;
+  const firstBlock = Math.floor(request.offset / BLOCK_BYTES);
+  // A request without a length is an incompatible observation. Count it
+  // conservatively through the piece's end rather than allowing extra copies.
+  const lastBlock = Number.isFinite(request.length) && request.length > 0
+    ? Math.min(chunks - 1, Math.ceil((request.offset + request.length) / BLOCK_BYTES) - 1)
+    : chunks - 1;
+  return blockIndex >= firstBlock && blockIndex <= lastBlock;
+}
+
+/**
+ * Adapts a live WebTorrent Torrent to the small observation/action contract
+ * needed by TailRepeat. It does not choose which piece or block to repeat.
+ */
+export class WebTorrentTailRepeatAdapter {
+  #torrent;
+  #disabled = false;
+
+  /** @param {object} torrent A WebTorrent Torrent instance. */
+  constructor(torrent) {
+    this.#torrent = torrent;
+  }
+
+  /** Disable the exception after an incompatible private API is observed. */
+  disable() {
+    this.#disabled = true;
+  }
+
+  /**
+   * Read missing blocks and their in-flight copy count/age.
+   *
+   * @param {number} pieceIndex
+   * @param {number} maxMissing Upper bound supplied by the download policy; a
+   *   larger tail is reported by count without allocating a per-block list.
+   * @returns {{ available: boolean, missingCount: number, blocks: Array<{ index: number, copies: number, firstAskedAt: number|null }> }}
+   */
+  observe(pieceIndex, maxMissing) {
+    const torrent = this.#torrent;
+    const piece = torrent?.pieces?.[pieceIndex];
+    // Completed pieces are removed from Torrent.pieces; a piece with no
+    // allocated block buffer has no request in flight, so neither is a tail.
+    if (!piece) return { available: true, missingCount: 0, blocks: [] };
+    const buffer = Array.isArray(piece?._buffer) ? piece._buffer : null;
+    if (!buffer) return { available: true, missingCount: 0, blocks: [] };
+    if (this.#disabled || typeof piece.cancel !== "function" || typeof torrent?._request !== "function") {
+      this.#disabled = true;
+      return { available: false, missingCount: 0, blocks: [] };
+    }
+
+    const chunks = Number.isFinite(piece._chunks) ? piece._chunks : buffer.length;
+    let missingCount = Number.isFinite(piece._buffered) ? chunks - piece._buffered : 0;
+    if (!Number.isFinite(piece._buffered)) {
+      for (let index = 0; index < chunks; index += 1) if (!buffer[index]) missingCount += 1;
+    }
+    if (missingCount === 0 || missingCount > maxMissing) {
+      return { available: true, missingCount, blocks: [] };
+    }
+
+    const blocks = [];
+    for (let index = 0; index < chunks; index += 1) {
+      if (buffer[index]) continue;
+      blocks.push({ index, copies: 0, firstAskedAt: null });
+    }
+    for (const wire of Array.isArray(torrent.wires) ? torrent.wires : []) {
+      for (const request of Array.isArray(wire?.requests) ? wire.requests : []) {
+        for (const block of blocks) {
+          if (!requestCoversBlock(request, pieceIndex, block.index, chunks)) continue;
+          block.copies += 1;
+          const askedAt = Number.isFinite(request.askedAt) ? request.askedAt : Number.NEGATIVE_INFINITY;
+          block.firstAskedAt = block.firstAskedAt === null ? askedAt : Math.min(block.firstAskedAt, askedAt);
+        }
+      }
+    }
+    return { available: true, missingCount, blocks };
+  }
+
+  /**
+   * Try one repeat for an already-selected, already-aged missing block.
+   * Returns a status instead of throwing so an incompatible private API cannot
+   * stop ordinary downloading. Every refusal restores the reservation.
+   *
+   * @param {number} pieceIndex
+   * @param {number} blockIndex
+   * @returns {"placed"|"refused"|"unavailable"}
+   */
+  repeatBlock(pieceIndex, blockIndex) {
+    const torrent = this.#torrent;
+    const piece = torrent?.pieces?.[pieceIndex];
+    const buffer = Array.isArray(piece?._buffer) ? piece._buffer : null;
+    if (this.#disabled || !piece || !buffer || buffer[blockIndex] || typeof piece.cancel !== "function" ||
+        typeof piece.reserve !== "function" || typeof torrent?._request !== "function") {
+      return "unavailable";
+    }
+
+    const candidates = usableWires(torrent, pieceIndex);
+    const chunks = Number.isFinite(piece._chunks) ? piece._chunks : buffer.length;
+    if (candidates.length === 0) return "refused";
+
+    for (const wire of candidates) {
+      if ((wire.requests ?? []).some((request) => requestCoversBlock(request, pieceIndex, blockIndex, chunks))) continue;
+
+      try {
+        piece.cancel(blockIndex);
+      } catch {
+        this.#disabled = true;
+        return "unavailable";
+      }
+
+      let placed = false;
+      try {
+        // false prevents WebTorrent's hotswap from freeing a third reservation.
+        placed = torrent._request(wire, pieceIndex, false) === true;
+      } catch {
+        // A thrown private call may have queued the request before failing.
+        placed = (wire.requests ?? []).some((request) => request?.piece === pieceIndex &&
+          Math.floor(request.offset / BLOCK_BYTES) === blockIndex);
+        if (!placed) {
+          try {
+            if (piece.reserve() !== blockIndex) this.#disabled = true;
+          } catch { this.#disabled = true; }
+        }
+        this.#disabled = true;
+        return placed ? "placed" : "unavailable";
+      }
+      if (placed) return "placed";
+
+      // _request refused before reserving. Claim the freed block back so the
+      // normal picker cannot see an unaccounted reservation.
+      try {
+        if (piece.reserve() !== blockIndex) {
+          this.#disabled = true;
+          return "unavailable";
+        }
+      } catch {
+        this.#disabled = true;
+        return "unavailable";
+      }
+    }
+    return "refused";
+  }
+
+  /** Subscribe to changes that can alter tail observations. */
+  watch(onChange, onLateBlock = () => {}) {
+    const torrent = this.#torrent;
+    const watched = new Map();
+    const poke = () => onChange();
+    const forget = (wire) => {
+      const listeners = watched.get(wire);
+      if (!listeners) return;
+      wire.removeListener?.("piece", listeners.onBlock);
+      for (const event of ["unchoke", "have", "bitfield"]) wire.removeListener?.(event, listeners.onPeer);
+      wire.removeListener?.("close", listeners.onClose);
+      watched.delete(wire);
+    };
+    const watchWire = (wire) => {
+      if (!wire || watched.has(wire) || typeof wire.on !== "function") return;
+      const listeners = {
+        onBlock: (index) => {
+          if (Number.isInteger(index) && torrent.bitfield?.get?.(index)) onLateBlock();
+          poke();
+        },
+        onPeer: poke,
+        onClose: () => { forget(wire); poke(); }
+      };
+      watched.set(wire, listeners);
+      wire.on("piece", listeners.onBlock);
+      for (const event of ["unchoke", "have", "bitfield"]) wire.on(event, listeners.onPeer);
+      wire.once?.("close", listeners.onClose);
+      poke();
+    };
+    const onWire = watchWire;
+    torrent.on?.("wire", onWire);
+    torrent.on?.("verified", poke);
+    for (const wire of Array.isArray(torrent.wires) ? torrent.wires : []) watchWire(wire);
+    return () => {
+      torrent.removeListener?.("wire", onWire);
+      torrent.removeListener?.("verified", poke);
+      for (const wire of [...watched.keys()]) forget(wire);
+    };
+  }
+}

package/services/torrent/worker/fastest-wires.js

@@ -1,398 +0,0 @@
-/**
- * @file Put the piece a reader is blocked on onto the fastest wires that hold
- * it.
- *
- * Measured 2026-08-17: the swarm delivered 5.1-5.9 MB/s against a film consumed
- * at about 1 MB/s — a fivefold surplus — and the reader still blocked 47 times
- * in two minutes, 1.0-4.5 s each. So the shortage is not bandwidth. The piece
- * that blocked had been requested from a median of five peers, and what set the
- * tail was WHICH wire held the last outstanding block: a block is reserved for
- * exactly one wire, and the read finishes when the slowest holder delivers.
- *
- * What the library already does, and what it does not: `torrent.critical()`
- * (which the reader already sets over its window) enables HOTSWAP — an idle
- * wire may take a block away from the SLOWEST holder. It does not duplicate:
- * `piece.reserve()` returns -1 once every block is spoken for, and the
- * end-game that would ask a second peer for the same block is commented out in
- * `webtorrent/lib/torrent.js`. Hotswap therefore fires only when the library's
- * own picker happens to visit an idle wire while our piece is critical.
- *
- * This asks for it on purpose, and chooses who: the wires that are unchoked,
- * hold the piece and are measurably fastest are handed the piece through the
- * same entry the library's picker uses, with hotswap enabled. Nothing is
- * duplicated and no protocol rule is bent — the block moves to a faster holder
- * instead of staying with whoever got it first.
- */
-
-/**
- * How short a piece's remaining tail must be for a second copy of it to be
- * worth asking for.
- *
- * Sixteen blocks is 256 KB against the 4-16 MB piece they hold up. The figure
- * comes from what was measured rather than chosen for roundness: the tails a
- * blocked reader waits on were 2 to 14 blocks of 512 on 2026-08-19, and 3 of
- * 512 in the field failure of 2026-09-03 that took 46.3 s. Above this the piece
- * is still arriving normally and duplicating would spend the shared link on
- * bytes already on their way.
- */
-const SHORT_TAIL_BLOCKS = 16;
-
-/** A block of a piece, as `torrent-piece` cuts it (`Piece.BLOCK_LENGTH`): a request's offset over this is its block. */
-const BLOCK_BYTES = 1 << 14;
-
-/**
- * The library's own request entry. Internal, so its absence must be noticed
- * rather than swallowed: without it this lever silently does nothing.
- *
- * @param {object} torrent
- * @returns {boolean}
- */
-export function canPlaceRequests(torrent) {
-  return typeof torrent?._request === "function";
-}
-
-/**
- * Wires that could deliver this piece right now, fastest first.
- *
- * Excluded, each for its own reason: a wire that is choking us cannot be asked
- * at all; one that does not hold the piece has nothing to give; a destroyed one
- * is a corpse. Speed is the library's own measurement over its own window, so
- * nothing here needs a history of its own.
- *
- * @param {object} torrent
- * @param {number} pieceIndex
- * @returns {object[]}
- */
-export function wiresForPiece(torrent, pieceIndex) {
-  const wires = Array.isArray(torrent?.wires) ? torrent.wires : [];
-  const usable = [];
-  for (const wire of wires) {
-    if (!wire || wire.destroyed || wire.peerChoking) {
-      continue;
-    }
-    if (wire.peerPieces?.get?.(pieceIndex) !== true) {
-      continue;
-    }
-    usable.push(wire);
-  }
-  return usable.sort((left, right) => speedOf(right) - speedOf(left));
-}
-
-/**
- * A wire's measured download speed in bytes per second, or 0 when it has not
- * been measured. Wrapped because `downloadSpeed` is a method on the wire and a
- * throw from a destroyed one must not take the caller with it.
- *
- * @param {object} wire
- * @returns {number}
- */
-function speedOf(wire) {
-  try {
-    const speed = wire?.downloadSpeed?.();
-    return Number.isFinite(speed) ? speed : 0;
-  } catch {
-    // A wire that cannot say how fast it is ranks last, which is the honest
-    // answer — and the caller's own log line reports how many were asked.
-    return 0;
-  }
-}
-
-/**
- * Ask the fastest holders of `pieceIndex` for it.
- *
- * @param {object} torrent
- * @param {number} pieceIndex
- * @param {number} [limit] - How many wires to push it onto.
- * @returns {{ asked: number, refusedWhileReserved: number, attempted: number, considered: number, fastestBytesPerSecond: number }}
- *   `asked` counts requests the library actually placed: it refuses when a
- *   wire's pipeline is full or when nothing can be reserved even with hotswap,
- *   and that refusal is information — a piece nobody can be asked for is
- *   waiting on the wire, not on the picker.
- */
-export function askFastestWiresFor(torrent, pieceIndex, limit = 3) {
-  if (!canPlaceRequests(torrent) || !Number.isInteger(pieceIndex) || pieceIndex < 0) {
-    return { asked: 0, refusedWhileReserved: 0, attempted: 0, considered: 0, fastestBytesPerSecond: 0 };
-  }
-  const candidates = wiresForPiece(torrent, pieceIndex);
-  let asked = 0;
-  let refusedWhileReserved = 0;
-  for (const wire of candidates.slice(0, Math.max(1, limit))) {
-    try {
-      // `true` is hotswap: if every block is reserved, take one from the
-      // slowest holder. That is the whole point — the reader is blocked
-      // precisely because a slow holder has one.
-      if (torrent._request(wire, pieceIndex, true) === true) {
-        asked += 1;
-      } else {
-        // Refused. Two reasons and they are different: this wire's pipeline is
-        // full, or every block of the piece is reserved and displacement did
-        // not happen. The second is the interesting one, because the thresholds
-        // that decide it are constants inside the library and not settings — a
-        // holder at 50 KB/s is just above the 48 KB/s line and is never
-        // displaced, however long the piece has been waited for. This counter
-        // is what would justify replacing `_hotswap` on the torrent, and
-        // without it that would be a change made on a hunch.
-        if (pieceIsFullyReserved(torrent, pieceIndex)) {
-          refusedWhileReserved += 1;
-        }
-      }
-    } catch (error) {
-      // Internal call: report it once per attempt rather than letting the lever
-      // fail in silence.
-      throw new Error(`could not place a request for piece ${pieceIndex}: ${error?.message ?? error}`);
-    }
-  }
-  return {
-    asked,
-    refusedWhileReserved,
-    considered: candidates.length,
-    // How many of the asks the library placed, against how many it was asked
-    // for. The caller sums these over the whole wait, and summing `asked`
-    // against a `considered` taken from the LAST attempt is how the field log
-    // came to read "steered onto 12 of 6 holders" — a ratio of two different
-    // things. Both halves are returned per attempt so the caller can add each
-    // to its own total.
-    attempted: Math.min(candidates.length, Math.max(1, limit)),
-    fastestBytesPerSecond: candidates.length > 0 ? speedOf(candidates[0]) : 0
-  };
-}
-
-/**
- * What is actually holding up a piece the reader is blocked on.
- *
- * The steering above can only move a block that the library will hand over, and
- * the field says it often hands over nothing: `steered onto 0 of 9 asks (8
- * peers held it)`, recorded 2026-08-18 while eight peers had the piece. When
- * every block of a piece is already reserved, `Piece.reserve()` answers -1 and
- * there is no request left to place — the read then ends when the SLOWEST
- * holder delivers its block, however fast the rest of the swarm is.
- *
- * Duplicating those last blocks onto faster wires is the standard remedy, and
- * it is not free: every duplicate is a block's worth of traffic paid twice. So
- * this describes the tail before anything is built with it — how many blocks
- * are still missing, and on which wires they sit, with each wire's speed. If
- * the missing blocks turn out to sit on one slow wire, duplication is aimed at
- * exactly the right thing; if they are spread across fast ones, the wait has
- * another cause and this work should not be done at all.
- *
- * Reads only: nothing here changes a reservation or places a request.
- *
- * @param {import("webtorrent").Torrent} torrent
- * @param {number} pieceIndex
- * @returns {{ chunks: number, missing: number,
- *   outstanding: Array<{ blocks: number, bytesPerSecond: number, choking: boolean }> } | null}
- *   Null only when the piece object is gone — it completed and was cleared.
- *   A piece nobody has reserved a block of yet is NOT null: `torrent-piece`
- *   creates its buffer lazily on the first reserve, so a piece the picker has
- *   not reached reads as every block missing and nothing outstanding, which is
- *   the most informative answer this can give — the wait is not on a slow
- *   holder, it is on nobody having been asked.
- */
-export function describePieceTail(torrent, pieceIndex) {
-  const piece = torrent?.pieces?.[pieceIndex];
-  if (!piece) {
-    return null;
-  }
-  const buffer = Array.isArray(piece._buffer) ? piece._buffer : null;
-  const chunks = Number.isFinite(piece._chunks)
-    ? piece._chunks
-    : (buffer ? buffer.length : 0);
-  // No buffer means no block of this piece has been reserved yet, so all of it
-  // is missing. Reading that as "no tail" hid the case worth seeing most.
-  let missing = chunks;
-  if (buffer) {
-    missing = 0;
-    for (let index = 0; index < chunks; index += 1) {
-      if (!buffer[index]) {
-        missing += 1;
-      }
-    }
-  }
-
-  const wires = Array.isArray(torrent?.wires) ? torrent.wires : [];
-  const outstanding = [];
-  for (const wire of wires) {
-    const requests = Array.isArray(wire?.requests) ? wire.requests : [];
-    const blocks = requests.filter((request) => request?.piece === pieceIndex).length;
-    if (blocks > 0) {
-      outstanding.push({
-        blocks,
-        bytesPerSecond: speedOf(wire),
-        choking: wire?.peerChoking === true
-      });
-    }
-  }
-  // Slowest first: that is the wire the read is waiting on, and the one a
-  // duplicate would be aimed past.
-  outstanding.sort((left, right) => left.bytesPerSecond - right.bytesPerSecond);
-  return { chunks, missing, outstanding };
-}
-
-/**
- * Ask a second wire for blocks the reader is still waiting on.
- *
- * WebTorrent reserves each block for exactly one wire, so once `Piece.reserve()`
- * answers -1 there is no request left to place and the read ends when the
- * holder of the last block delivers it — however fast the rest of the swarm is.
- * The library's own remedy is `_hotswap`, and it does precisely the right
- * thing: `piece.cancel(blockIndex)` frees the reservation while leaving the
- * first wire's request in flight, so a second wire can be asked for the same
- * block and whichever arrives first wins. What it will not do is apply that to
- * these tails. It is gated on speed — the held-up wire must be under 48 KB/s
- * (`3 * BLOCK_LENGTH`) and at least twice as slow as the asker — and measured
- * on a real swarm 2026-08-19, the tails a reader waits on sit at 109, 317 and
- * 870 KB/s. Peers the library rightly considers good, because for bulk
- * downloading they are; the gate is about throughput across a torrent and knows
- * nothing about a reader blocked on one piece now.
- *
- * Speed is not even what is wrong with them: two blocks — 32 KB — on a wire
- * measured at 109 KB/s is 0.3 s of transfer, and that read waited 4.6 s. The
- * blocks are not travelling slowly, they are queued behind that wire's other
- * work, which no average speed can show.
- *
- * The cost is bounded by the same measurement: the tails were 2 to 14 blocks of
- * 512, so 32 to 224 KB against the 8 MiB piece they hold up. A block already in
- * flight on `maxCopies` wires is not asked again, however often this is called:
- * it is called on every block that arrives (`TailRepeat`), and without that
- * check each call asked one more copy of the same block.
- *
- * Safe against the completion path: a block that arrives twice is dropped by
- * `Piece.set`, which writes only into an empty slot, and a piece already
- * flushed answers `false` from `Piece.init` so the second arrival returns
- * before `flush()` is reached.
- *
- * @param {object} torrent
- * @param {number} pieceIndex
- * @param {object} [options]
- * A BLOCK IS ASKED AGAIN ONLY ONCE IT IS LATE. A short tail is not by itself a
- * delay: copied as soon as the tail was short, 12-16 blocks of nearly every
- * piece were asked twice and 82 of 215 copies arrived after their piece was
- * complete (r41, Home Assistant, torrent-tv/meta#178). So a block is asked of a
- * second peer once its request to the first has been out `minAgeMs` — by
- * default the second WebTorrent sizes a wire's queue to fill
- * (`PIPELINE_MAX_DURATION`), a starting point to be checked in the field — and
- * the earliest moment a held block becomes late is returned, so whoever calls
- * this can look again then.
- *
- * @param {object} torrent
- * @param {number} pieceIndex
- * @param {object} [options]
- * @param {number} [options.maxCopies] - How many wires a missing block may be
- *   in flight on at once: the first request and one copy beside it.
- * @param {number} [options.minAgeMs] - How long the first request must have been out.
- * @param {number} [options.now] - Wall clock, ms.
- * @returns {{ duplicated: number, missing: number, wires: number, unplaced: number, dueAt: number | null }}
- *   `duplicated` counts requests the library actually placed for a block that
- *   was already outstanding elsewhere; `unplaced` the late blocks in flight on
- *   one wire alone that no other wire could be asked for now; `dueAt` when the
- *   first block held by one wire and not yet late becomes late, or null.
- */
-export function duplicateTailFor(torrent, pieceIndex, { maxCopies = 2, minAgeMs = 1000, now = Date.now() } = {}) {
-  const piece = torrent?.pieces?.[pieceIndex];
-  const buffer = Array.isArray(piece?._buffer) ? piece._buffer : null;
-  if (!piece || !buffer || typeof piece.cancel !== "function" || !canPlaceRequests(torrent)) {
-    return { duplicated: 0, missing: 0, wires: 0, unplaced: 0, dueAt: null };
-  }
-  const chunks = Number.isFinite(piece._chunks) ? piece._chunks : buffer.length;
-  // Most calls are for a piece still arriving in bulk; its own count says so
-  // without walking its blocks or every wire's queue.
-  if (Number.isFinite(piece._buffered) && chunks - piece._buffered > SHORT_TAIL_BLOCKS) {
-    return { duplicated: 0, missing: chunks - piece._buffered, wires: 0, unplaced: 0, dueAt: null };
-  }
-
-  const missing = [];
-  for (let index = 0; index < chunks; index += 1) {
-    if (!buffer[index]) {
-      missing.push(index);
-    }
-  }
-  const candidates = wiresForPiece(torrent, pieceIndex);
-  if (missing.length === 0 || candidates.length === 0) {
-    return { duplicated: 0, missing: missing.length, wires: candidates.length, unplaced: 0, dueAt: null };
-  }
-
-  // A tail this short is what a blocked read is actually waiting on, and a
-  // second copy of it costs a few dozen kilobytes. A longer one is a piece
-  // still arriving normally, where duplicating would spend the shared link on
-  // bytes that are already coming — measured 2026-08-19, the tails a reader
-  // waits on are 2 to 14 blocks of 512.
-  if (missing.length > SHORT_TAIL_BLOCKS) {
-    return { duplicated: 0, missing: missing.length, wires: candidates.length, unplaced: 0, dueAt: null };
-  }
-
-  // Which wires each missing block is in flight on, and since when, read from
-  // the wires' own queues: the library keeps a block's reservation for one
-  // wire only, and a copy asked here is visible nowhere else. A request with no
-  // time of its own was asked before anybody watched, and is old.
-  const holders = new Map(missing.map(block => [block, { wires: new Set(), since: Number.POSITIVE_INFINITY }]));
-  for (const wire of Array.isArray(torrent.wires) ? torrent.wires : []) {
-    for (const request of Array.isArray(wire?.requests) ? wire.requests : []) {
-      if (request?.piece !== pieceIndex) continue;
-      const holding = holders.get(Math.floor(request.offset / BLOCK_BYTES));
-      if (!holding) continue;
-      holding.wires.add(wire);
-      holding.since = Math.min(holding.since, Number.isFinite(request.askedAt) ? request.askedAt : Number.NEGATIVE_INFINITY);
-    }
-  }
-
-  let duplicated = 0, unplaced = 0, dueAt = null;
-  for (const block of missing) {
-    const { wires: held, since } = holders.get(block);
-    // Not in flight anywhere: the library's own picker asks for it; a block
-    // nobody has been asked for is not a tail held by a slow peer.
-    if (held.size === 0 || held.size >= maxCopies) continue;
-    if (now - since < minAgeMs) {
-      dueAt = Math.min(dueAt ?? Number.POSITIVE_INFINITY, since + minAgeMs);
-      continue;
-    }
-    let placed = false;
-    for (const wire of candidates) {
-      if (held.has(wire)) continue;
-      // Freeing the reservation is what makes the block askable again; the
-      // request already in flight is deliberately left alone, because the
-      // point is to have two of them.
-      piece.cancel(block);
-      // `false` is hotswap: the library's own swap must not run on top of
-      // this, or it would free a THIRD wire's block as well.
-      if (torrent._request(wire, pieceIndex, false) === true) {
-        held.add(wire);
-        duplicated += 1;
-        placed = true;
-        break;
-      }
-      // Refused before anything was reserved (that wire's pipeline is full):
-      // the freed block is taken back, or the library would hand it to the
-      // next wire that asks, a copy nobody counted. The next wire's pipeline
-      // is its own, so it is still asked.
-      piece.reserve();
-    }
-    if (!placed) unplaced += 1;
-  }
-  return { duplicated, missing: missing.length, wires: candidates.length, unplaced, dueAt };
-}
-
-/**
- * Whether every block of a piece is spoken for by some wire.
- *
- * The condition under which the library refuses a request and only displacement
- * could change the answer. Read from the piece's own reservation state, which
- * is what `_request` consults.
- *
- * @param {object} torrent
- * @param {number} pieceIndex
- * @returns {boolean}
- */
-function pieceIsFullyReserved(torrent, pieceIndex) {
-  const piece = torrent?.pieces?.[pieceIndex];
-  if (!piece || typeof piece.reserve !== "function") {
-    return false;
-  }
-  const reservation = piece.reserve();
-  if (reservation === -1) {
-    return true;
-  }
-  // Taken only to ask the question; give it straight back, or this reader has
-  // quietly claimed a block nobody will ever deliver.
-  piece.cancel?.(reservation);
-  return false;
-}

package/services/torrent/worker/tail-repeat.js

@@ -1,171 +0,0 @@
-/**
- * @file Ask a second peer for the last blocks of a piece somebody is waiting
- * for, when one slow peer holds them (torrent-tv/meta#178).
- *
- * Field r40 (Home Assistant, 2026-10-14, a cold 1080p MKV): the first run's
- * input waited 10.0 s, last for piece 8, whose slowest block was 4.5 s in
- * flight from one peer; pieces 14-16 waited 10.0-11.5 s on one peer each. A
- * block is reserved for one wire, and the piece completes when its slowest
- * holder delivers (`duplicateTailFor`). Nothing had asked a second peer since
- * the blocked-read path that did so was removed (`0e38ec3`, torrent-tv/meta#95).
- *
- * Which pieces: those of the urgent first class the swarm was last told
- * (`SwarmSelection.requiredPieces`) — what somebody waits for now. A map that
- * withdraws them, or an input that is ready, takes them out, and nothing more
- * is asked for them.
- *
- * When: a tail changes when a block arrives, a wire's queue moves on, or a
- * peer becomes able or unable to give the piece; so it is looked at on those —
- * a block arriving, a wire unchoking, a peer stating a piece, a wire joining
- * or closing, a piece verified, a new map. Several in one turn of the event
- * loop are one look. A block is asked again only once its request has been out
- * a wire's queue time (`duplicateTailFor`), so a block not yet late is looked
- * at again when it becomes late, and a late one no other wire could take is
- * looked at again a queue time later — once, in case nothing else happens in
- * between. WebTorrent sizes a wire's queue to one second of its speed
- * (`PIPELINE_MAX_DURATION`).
- */
-
-import { duplicateTailFor } from "./fastest-wires.js";
-
-/** WebTorrent's `PIPELINE_MAX_DURATION`: a wire is given one second of its speed to fetch. */
-const WIRE_QUEUE_SECONDS = 1;
-
-/** What a wire says, besides a block arriving, that can change who could be asked for a piece. */
-const WIRE_EVENTS = ["unchoke", "have", "bitfield"];
-
-export class TailRepeat {
-  #torrent;
-  #requiredPieces;
-  #duplicate;
-  #schedule;
-  #wake;
-  #clear;
-  #scheduled = false;
-  #timer = null;
-  /** When the armed look runs, wall clock ms. */
-  #timerAt = Number.POSITIVE_INFINITY;
-  #disposed = false;
-  /** @type {Map<object, { onBlock: (index: number) => void, onPeer: () => void }>} */
-  #wires = new Map();
-  #onWire;
-  #onPoke;
-  #log;
-  #now;
-  /**
-   * Grow-only, for the log: block copies asked, looks taken, and blocks that
-   * arrived after their piece was complete — what the copies cost.
-   */
-  totals = { duplicated: 0, looks: 0, lateBlocks: 0 };
-
-  /**
-   * @param {object} params
-   * @param {object} params.torrent
-   * @param {() => Array<{ from: number, to: number }>} params.requiredPieces
-   * @param {typeof duplicateTailFor} [params.duplicate]
-   * @param {(work: () => void) => void} [params.schedule] - Runs work once this turn of the event loop is over.
-   * @param {(work: () => void, ms: number) => unknown} [params.wake]
-   * @param {(handle: unknown) => void} [params.clear]
-   * @param {(line: string) => void} [params.log]
-   * @param {() => number} [params.now]
-   */
-  constructor({ torrent, requiredPieces, duplicate = duplicateTailFor, schedule = setImmediate, wake = setTimeout, clear = clearTimeout, log = null, now = Date.now }) {
-    this.#log = log;
-    this.#now = now;
-    this.#torrent = torrent;
-    this.#requiredPieces = requiredPieces;
-    this.#duplicate = duplicate;
-    this.#schedule = schedule;
-    this.#wake = wake;
-    this.#clear = clear;
-    this.#onWire = (wire) => this.#watch(wire);
-    this.#onPoke = () => this.poke();
-    torrent.on?.("wire", this.#onWire);
-    torrent.on?.("verified", this.#onPoke);
-    for (const wire of Array.isArray(torrent.wires) ? torrent.wires : []) this.#watch(wire);
-  }
-
-  /** Look at the tails once this turn of the event loop is over. */
-  poke() {
-    if (this.#scheduled || this.#disposed) return;
-    this.#scheduled = true;
-    this.#schedule(() => this.#look());
-  }
-
-  /** Stop watching: the torrent is going. */
-  dispose() {
-    this.#disposed = true;
-    this.#torrent.removeListener?.("wire", this.#onWire);
-    this.#torrent.removeListener?.("verified", this.#onPoke);
-    for (const wire of [...this.#wires.keys()]) this.#forget(wire);
-    if (this.#timer !== null) this.#clear(this.#timer);
-    this.#timer = null;
-  }
-
-  /** One look armed at a time, at the earliest moment asked for. */
-  #lookAgainAt(at, now) {
-    if (!Number.isFinite(at) || at >= this.#timerAt) return;
-    if (this.#timer !== null) this.#clear(this.#timer);
-    this.#timerAt = at;
-    this.#timer = this.#wake(() => {
-      this.#timer = null;
-      this.#timerAt = Number.POSITIVE_INFINITY;
-      this.poke();
-    }, Math.max(0, at - now));
-    this.#timer?.unref?.();
-  }
-
-  #watch(wire) {
-    if (!wire || this.#wires.has(wire) || typeof wire.on !== "function") return;
-    const listeners = {
-      onBlock: (index) => {
-        // A block of a piece already verified is a copy that came second; the
-        // block that completes a piece arrives before the piece is verified.
-        if (Number.isInteger(index) && this.#torrent.bitfield?.get?.(index)) this.totals.lateBlocks += 1;
-        this.poke();
-      },
-      onPeer: () => this.poke()
-    };
-    this.#wires.set(wire, listeners);
-    wire.on("piece", listeners.onBlock);
-    for (const event of WIRE_EVENTS) wire.on(event, listeners.onPeer);
-    wire.once?.("close", () => {
-      this.#forget(wire);
-      this.poke();
-    });
-    this.poke();
-  }
-
-  #forget(wire) {
-    const listeners = this.#wires.get(wire);
-    if (!listeners) return;
-    wire.removeListener?.("piece", listeners.onBlock);
-    for (const event of WIRE_EVENTS) wire.removeListener?.(event, listeners.onPeer);
-    this.#wires.delete(wire);
-  }
-
-  #look() {
-    this.#scheduled = false;
-    if (this.#disposed) return;
-    this.totals.looks += 1;
-    const now = this.#now();
-    let unplaced = 0, dueAt = Number.POSITIVE_INFINITY;
-    const asked = [];
-    for (const { from, to } of this.#requiredPieces()) {
-      for (let index = from; index <= to; index += 1) {
-        if (this.#torrent.bitfield?.get?.(index)) continue;
-        const result = this.#duplicate(this.#torrent, index, { minAgeMs: WIRE_QUEUE_SECONDS * 1000, now });
-        this.totals.duplicated += result.duplicated;
-        unplaced += result.unplaced;
-        if (Number.isFinite(result.dueAt)) dueAt = Math.min(dueAt, result.dueAt);
-        if (result.duplicated > 0) asked.push(`${index}:${result.duplicated}/${result.missing}`);
-      }
-    }
-    if (asked.length > 0) {
-      this.#log?.(`tail: asked a second peer for the last blocks of piece:blocks/missing ${asked.join(" ")}; ` +
-        `${this.totals.duplicated} block copies asked so far, ${this.totals.lateBlocks} block(s) arrived after their piece was complete`);
-    }
-    if (unplaced > 0) dueAt = Math.min(dueAt, now + WIRE_QUEUE_SECONDS * 1000);
-    this.#lookAgainAt(dueAt, now);
-  }
-}