@torrent-tv/proxy 2.38.0 → 2.39.0

package/test/piece-tail.test.js

@@ -0,0 +1,97 @@
+/**
+ * @file What a blocked piece's tail looks like, before anything is built on it.
+ *
+ * The steering shipped in 2.29.0 often places nothing — `steered onto 0 of 9
+ * asks (8 peers held it)`, measured 2026-08-18 — because every block of the
+ * piece is already reserved and the library will not hand out a second request
+ * for the same block. Duplicating those blocks is the standard remedy and costs
+ * traffic, so the tail is described first: how much is missing, and on which
+ * wires it sits.
+ */
+
+import test from "node:test";
+import assert from "node:assert/strict";
+import { describePieceTail } from "../services/torrent-worker/fastest-wires.js";
+
+/** A torrent whose piece has some blocks in hand and some in flight. */
+function torrentWith({ buffer, wires }) {
+  return {
+    pieces: [{ _buffer: buffer, _chunks: buffer.length }],
+    wires
+  };
+}
+
+function wire({ has = true, blocks = 0, speed = 0, choking = false }) {
+  return {
+    peerPieces: { get: () => has },
+    requests: Array.from({ length: blocks }, () => ({ piece: 0 })),
+    downloadSpeed: () => speed,
+    peerChoking: choking
+  };
+}
+
+test("the tail names how much is missing and who is holding it", () => {
+  const tail = describePieceTail(
+    torrentWith({
+      // Four blocks, two already in hand.
+      buffer: [new Uint8Array(1), new Uint8Array(1), null, null],
+      wires: [
+        wire({ blocks: 1, speed: 900_000 }),
+        wire({ blocks: 1, speed: 12_000 }),
+        wire({ has: true, blocks: 0, speed: 5_000_000 })
+      ]
+    }),
+    0
+  );
+
+  assert.equal(tail.missing, 2);
+  assert.equal(tail.chunks, 4);
+  assert.equal(tail.outstanding.length, 2, "only the wires actually holding a block of it");
+  assert.equal(
+    tail.outstanding[0].bytesPerSecond,
+    12_000,
+    "slowest first — that is the wire the read is waiting on"
+  );
+});
+
+test("a piece nobody is fetching reads as entirely missing, held by nobody", () => {
+  const tail = describePieceTail(
+    torrentWith({ buffer: [null, null], wires: [wire({ has: false, blocks: 0 })] }),
+    0
+  );
+
+  assert.equal(tail.outstanding.length, 0);
+  assert.equal(tail.missing, 2, "and the missing count still says the piece is untouched");
+});
+
+test("a piece no block of which has been reserved is described, not skipped", () => {
+  // `torrent-piece` builds its buffer lazily on the first reserve, so a piece
+  // the picker has not reached has none. Reading that as "no tail" hid the
+  // clearest answer there is: the wait is on nobody having been asked.
+  const tail = describePieceTail(
+    { pieces: [{ _buffer: null, _chunks: 512 }], wires: [wire({ has: true, blocks: 0, speed: 900_000 })] },
+    0
+  );
+
+  assert.equal(tail.missing, 512, "every block of it is missing");
+  assert.equal(tail.chunks, 512);
+  assert.equal(tail.outstanding.length, 0, "and not one of them has been asked for");
+});
+
+test("a completed piece is not described at all", () => {
+  // WebTorrent nulls `pieces[index]` once the piece is verified and stored.
+  assert.equal(describePieceTail({ pieces: [null], wires: [] }, 0), null);
+  assert.equal(describePieceTail({ pieces: [], wires: [] }, 0), null);
+});
+
+test("a wire that is choking us is named as such", () => {
+  const tail = describePieceTail(
+    torrentWith({
+      buffer: [null],
+      wires: [wire({ blocks: 1, speed: 100, choking: true })]
+    }),
+    0
+  );
+
+  assert.equal(tail.outstanding[0].choking, true, "a block reserved by a choking wire is going nowhere");
+});

package/test/tail-duplication.test.js

@@ -0,0 +1,123 @@
+/**
+ * @file Asking a second wire for the blocks a reader is still waiting on.
+ *
+ * Measured on a real swarm 2026-08-19: a blocked read's tail is 2-14 blocks of
+ * 512, and it sits on wires at 109-886 KB/s — above the 48 KB/s gate that
+ * WebTorrent's own `_hotswap` requires, so the library never duplicates them.
+ * The mechanism is the library's: free the reservation with `Piece.cancel` and
+ * leave the first request in flight, then ask a second wire through the
+ * library's own request path.
+ */
+
+import test from "node:test";
+import assert from "node:assert/strict";
+import { duplicateTailFor } from "../services/torrent-worker/fastest-wires.js";
+
+/** A piece with `chunks` blocks, of which `missing` at the end are absent. */
+function piece(chunks, missing) {
+  const buffer = new Array(chunks);
+  for (let index = 0; index < chunks - missing; index += 1) {
+    buffer[index] = new Uint8Array(1);
+  }
+  const cancelled = [];
+  return {
+    _buffer: buffer,
+    _chunks: chunks,
+    cancel: (index) => cancelled.push(index),
+    cancelled
+  };
+}
+
+function wire({ speed = 500_000, has = true } = {}) {
+  return {
+    peerPieces: { get: () => has },
+    downloadSpeed: () => speed,
+    peerChoking: false,
+    destroyed: false,
+    requests: []
+  };
+}
+
+test("the missing blocks are freed and asked of a second wire", () => {
+  const target = piece(512, 3);
+  const placed = [];
+  const torrent = {
+    pieces: [target],
+    wires: [wire({ speed: 900_000 }), wire({ speed: 800_000 }), wire({ speed: 700_000 })],
+    _request: (wireAsked, index) => {
+      placed.push({ wireAsked, index });
+      return true;
+    }
+  };
+
+  const result = duplicateTailFor(torrent, 0);
+
+  assert.equal(result.missing, 3, "the tail is what is still absent from the piece");
+  assert.equal(result.duplicated, 3);
+  assert.deepEqual(target.cancelled, [509, 510, 511], "each block's reservation is freed first");
+  assert.equal(placed.length, 3, "and each is then asked of a wire through the library's own path");
+  assert.equal(placed[0].wireAsked, torrent.wires[0], "fastest wire first");
+});
+
+test("at most one duplicate per wire, however long the tail", () => {
+  const target = piece(512, 40);
+  const torrent = {
+    pieces: [target],
+    wires: [wire(), wire()],
+    _request: () => true
+  };
+
+  const result = duplicateTailFor(torrent, 0);
+
+  assert.equal(result.duplicated, 2, "two wires, two duplicates — the rest waits for the next attempt");
+  assert.equal(target.cancelled.length, 2, "and no reservation is freed that nobody was asked for");
+});
+
+test("a wire whose pipeline is full ends the attempt", () => {
+  const target = piece(512, 5);
+  const torrent = {
+    pieces: [target],
+    wires: [wire(), wire(), wire()],
+    // The library refuses when the wire already has as many requests as its
+    // measured speed justifies.
+    _request: () => false
+  };
+
+  const result = duplicateTailFor(torrent, 0);
+
+  assert.equal(result.duplicated, 0);
+  assert.equal(
+    target.cancelled.length,
+    1,
+    "only the block that was actually offered is freed; the rest keep their reservations"
+  );
+});
+
+test("a piece with nothing missing is left alone", () => {
+  const target = piece(4, 0);
+  const torrent = { pieces: [target], wires: [wire()], _request: () => true };
+
+  const result = duplicateTailFor(torrent, 0);
+
+  assert.equal(result.duplicated, 0);
+  assert.equal(result.missing, 0);
+  assert.equal(target.cancelled.length, 0);
+});
+
+test("with no wire holding the piece there is nothing to duplicate onto", () => {
+  const target = piece(8, 2);
+  const torrent = { pieces: [target], wires: [wire({ has: false })], _request: () => true };
+
+  const result = duplicateTailFor(torrent, 0);
+
+  assert.equal(result.wires, 0);
+  assert.equal(result.duplicated, 0);
+  assert.equal(target.cancelled.length, 0, "and no reservation is freed for nobody");
+});
+
+test("a completed piece is not touched", () => {
+  assert.deepEqual(
+    duplicateTailFor({ pieces: [null], wires: [wire()], _request: () => true }, 0),
+    { duplicated: 0, missing: 0, wires: 0 }
+  );
+});