@torrent-tv/proxy 2.9.73 → 2.9.75

package/services/piece-store/disk-tier.js

@@ -0,0 +1,151 @@
+/**
+ * @file The second tier: pieces that no longer fit in memory.
+ *
+ * One sparse file per torrent, a piece at `index * chunkLength`. Not the
+ * torrent's real files — nobody reads those directly; playback goes through
+ * `/stream`, and the data is discarded when the torrent goes idle. A single
+ * file by piece index keeps the mapping arithmetic instead of bookkeeping, and
+ * sparseness means the untouched gaps cost nothing.
+ *
+ * Reads take a destination buffer rather than returning a fresh one. That is
+ * not a style preference — measured on the field host, an 8 MB piece costs
+ * 22.08 ms via `readFile`, which allocates, and **7.63 ms** read into a buffer
+ * we already hold. Two thirds of the apparent "disk" cost was allocation.
+ */
+
+import fs from "node:fs/promises";
+import { constants } from "node:fs";
+import path from "node:path";
+
+export class DiskTier {
+  #filePath;
+  #chunkLength;
+  /** @type {import("node:fs/promises").FileHandle | null} */
+  #handle = null;
+  /** Piece indices known to be on disk. */
+  #stored = new Set();
+  /** @type {Promise<void> | null} */
+  #opening = null;
+
+  /**
+   * @param {object} params
+   * @param {string} params.directory - Where the backing file lives.
+   * @param {string} params.name - File name, unique per torrent.
+   * @param {number} params.chunkLength - Piece size; fixes the stride on disk.
+   */
+  constructor({ directory, name, chunkLength }) {
+    this.#filePath = path.join(directory, name);
+    this.#chunkLength = chunkLength;
+  }
+
+  /** Where the backing file lives, for logging and cleanup. */
+  get filePath() {
+    return this.#filePath;
+  }
+
+  /** How many pieces are currently held on disk. */
+  get size() {
+    return this.#stored.size;
+  }
+
+  /**
+   * Open the backing file, creating it and its directory if needed.
+   *
+   * Concurrent callers share one open — several evictions can start at once.
+   *
+   * @returns {Promise<import("node:fs/promises").FileHandle>}
+   */
+  async #open() {
+    if (this.#handle) {
+      return this.#handle;
+    }
+    if (!this.#opening) {
+      this.#opening = (async () => {
+        await fs.mkdir(path.dirname(this.#filePath), { recursive: true });
+        // Read/write, created if absent — NOT append mode. Under `a+` POSIX
+        // ignores the position on every write and puts the bytes at the end of
+        // the file, so pieces would pile up in arrival order and each read
+        // would return whichever piece happened to land at that offset.
+        this.#handle = await fs.open(this.#filePath, constants.O_RDWR | constants.O_CREAT);
+      })();
+    }
+    await this.#opening;
+    if (!this.#handle) {
+      throw new Error(`Could not open the piece file at ${this.#filePath}.`);
+    }
+    return this.#handle;
+  }
+
+  /**
+   * @param {number} index
+   * @returns {boolean}
+   */
+  has(index) {
+    return this.#stored.has(index);
+  }
+
+  /**
+   * Write a piece out.
+   *
+   * @param {number} index
+   * @param {Uint8Array} bytes
+   * @returns {Promise<void>}
+   */
+  async write(index, bytes) {
+    const handle = await this.#open();
+    await handle.write(bytes, 0, bytes.length, index * this.#chunkLength);
+    this.#stored.add(index);
+  }
+
+  /**
+   * Read a piece back into a buffer the caller already owns.
+   *
+   * @param {number} index
+   * @param {Uint8Array} target - Destination; its length is what gets read.
+   * @returns {Promise<number>} Bytes read.
+   */
+  async read(index, target) {
+    if (!this.#stored.has(index)) {
+      throw new Error(`Piece ${index} is not on disk.`);
+    }
+    const handle = await this.#open();
+    const { bytesRead } = await handle.read(target, 0, target.length, index * this.#chunkLength);
+    return bytesRead;
+  }
+
+  /**
+   * Forget a piece. The bytes stay on disk until the file is removed — there is
+   * nothing to gain from punching them out, since the file is discarded whole.
+   *
+   * @param {number} index
+   * @returns {void}
+   */
+  forget(index) {
+    this.#stored.delete(index);
+  }
+
+  /**
+   * Close the file, leaving its contents in place.
+   *
+   * @returns {Promise<void>}
+   */
+  async close() {
+    const handle = this.#handle;
+    this.#handle = null;
+    this.#opening = null;
+    if (handle) {
+      await handle.close();
+    }
+  }
+
+  /**
+   * Close and delete the backing file.
+   *
+   * @returns {Promise<void>}
+   */
+  async destroy() {
+    await this.close();
+    this.#stored.clear();
+    await fs.rm(this.#filePath, { force: true });
+  }
+}

package/services/piece-store/piece-lru.js

@@ -0,0 +1,150 @@
+/**
+ * @file Which piece leaves memory next — and which one may not.
+ *
+ * Two responsibilities, deliberately kept apart from any storage:
+ *
+ *  - **recency**, so the piece evicted is the one least likely to be wanted;
+ *  - **pinning**, so a piece being read cannot be evicted at all.
+ *
+ * The second is not a refinement of the first. webtor's seeder relies on recency
+ * alone and guards the actual eviction with a read/write lock per piece
+ * (`mmap.go`, 1024 shards) — because ordering says a piece is *unlikely* to be
+ * in use, never that it is not. We have already paid for that difference once:
+ * proxy 2.9.71 removed a torrent, and its data, out from under an active reader,
+ * after which every read hung and ffmpeg saw an empty input. Here the guarantee
+ * is explicit: a pinned piece is never returned as an eviction candidate, and
+ * pins nest, because a piece can be read by several sessions at once.
+ */
+
+/**
+ * Recency and pin bookkeeping for one torrent's pieces.
+ *
+ * Holds no data — it answers "what may go" and nothing else, which is what
+ * makes it testable without a torrent, a disk or a thread.
+ */
+export class PieceLru {
+  /** Insertion-ordered: the first key is the least recently used. */
+  #order = new Set();
+  /** Piece index → number of readers currently holding it. */
+  #pins = new Map();
+  #capacity;
+
+  /**
+   * @param {number} capacity - How many pieces may be resident at once.
+   */
+  constructor(capacity) {
+    if (!Number.isInteger(capacity) || capacity < 1) {
+      throw new Error(`Piece capacity must be a positive integer, got ${capacity}.`);
+    }
+    this.#capacity = capacity;
+  }
+
+  /** How many pieces are resident. */
+  get size() {
+    return this.#order.size;
+  }
+
+  /** How many pieces may be resident at once. */
+  get capacity() {
+    return this.#capacity;
+  }
+
+  /**
+   * Mark a piece as resident, or as used again if it already was.
+   *
+   * A `Set` preserves insertion order, so deleting and re-adding is what moves
+   * a piece to the most-recent end.
+   *
+   * @param {number} index
+   * @returns {void}
+   */
+  touch(index) {
+    this.#order.delete(index);
+    this.#order.add(index);
+  }
+
+  /**
+   * @param {number} index
+   * @returns {boolean}
+   */
+  has(index) {
+    return this.#order.has(index);
+  }
+
+  /**
+   * Stop tracking a piece — it is no longer resident.
+   *
+   * @param {number} index
+   * @returns {void}
+   */
+  remove(index) {
+    this.#order.delete(index);
+  }
+
+  /**
+   * Hold a piece in memory for the duration of a read.
+   *
+   * Nested: two readers of the same piece take two pins, and the piece stays
+   * held until both let go.
+   *
+   * @param {number} index
+   * @returns {void}
+   */
+  pin(index) {
+    this.#pins.set(index, (this.#pins.get(index) ?? 0) + 1);
+  }
+
+  /**
+   * Release one pin taken with {@link pin}.
+   *
+   * @param {number} index
+   * @returns {void}
+   */
+  unpin(index) {
+    const held = this.#pins.get(index);
+    if (held === undefined) {
+      return;
+    }
+    if (held <= 1) {
+      this.#pins.delete(index);
+      return;
+    }
+    this.#pins.set(index, held - 1);
+  }
+
+  /**
+   * @param {number} index
+   * @returns {boolean}
+   */
+  isPinned(index) {
+    return this.#pins.has(index);
+  }
+
+  /**
+   * The least recently used piece that is free to go, or `null` when every
+   * resident piece is pinned.
+   *
+   * Returning `null` rather than evicting a pinned piece is the whole point:
+   * the caller must then wait or fail, never take memory out from under a
+   * reader.
+   *
+   * @returns {number | null}
+   */
+  evictionCandidate() {
+    for (const index of this.#order) {
+      if (!this.#pins.has(index)) {
+        return index;
+      }
+    }
+    return null;
+  }
+
+  /**
+   * Whether admitting one more piece would exceed the capacity.
+   *
+   * @returns {boolean}
+   */
+  isFull() {
+    return this.#order.size >= this.#capacity;
+  }
+}

package/services/piece-store/shared-piece-store.js

@@ -0,0 +1,416 @@
+/**
+ * @file Torrent pieces in shared memory, with disk as the second tier.
+ *
+ * Replaces the chunk store WebTorrent would otherwise build for itself. Two
+ * reasons, one forced and one chosen.
+ *
+ * **Forced.** WebTorrent's own piece cache hands out the buffer it keeps using
+ * and slices again on the next read. The torrent client now runs on its own
+ * thread, and moving a piece to the main thread by transferring ownership
+ * detached the cache's memory: proxy 2.9.71-2.9.73 answered every read with an
+ * empty body (`Stream ends prematurely at 0`) and the failure was invisible,
+ * because the error never reached the reader. Owning the memory ourselves
+ * removes the question of whose it was.
+ *
+ * **Chosen.** Memory this side of the thread boundary can be *shared* memory,
+ * which the main thread reads by offset instead of receiving as bytes — see
+ * {@link SharedPieceStore#locate}. Measured on the field host: a piece copy
+ * costs 3.64 ms, a read from the page cache into a buffer we own 7.63 ms, and
+ * re-downloading a piece from the swarm ~1430 ms. So memory first, disk under
+ * it, and never the swarm twice.
+ *
+ * What this deliberately does NOT do is manage the disk as a cache of its own.
+ * Pieces evicted from memory are written once and read back on demand; the file
+ * is discarded whole when the torrent goes away. libtorrent 2.0 and webtor's
+ * seeder both concluded that a hand-rolled disk cache earns less than it costs,
+ * and nothing here disagrees.
+ */
+
+import os from "node:os";
+import { PieceLru } from "./piece-lru.js";
+import { DiskTier } from "./disk-tier.js";
+
+/**
+ * Live stores, so the worker can report on them.
+ *
+ * WebTorrent constructs the store itself, deep inside its own wrappers, so
+ * there is no handle to reach for from outside. Registering here is what makes
+ * the store's behaviour visible in the field at all — without it the first
+ * strange case has nothing to go on.
+ *
+ * @type {Set<SharedPieceStore>}
+ */
+const liveStores = new Set();
+
+/**
+ * A snapshot of every live store, for logging.
+ *
+ * @returns {{ name: string, resident: number, capacity: number, spilled: number, fromMemory: number, fromDisk: number, spills: number, revivals: number, blockedByPins: number }[]}
+ */
+export function collectStoreStats() {
+  return [...liveStores].map((store) => store.stats());
+}
+
+/**
+ * Ceiling for the automatic budget, and the share of free memory it will take.
+ *
+ * A flat default would be a guess dressed as a decision: the proxy runs on
+ * whatever the owner has, from a Pi to a rented box, and the budget is **per
+ * torrent** — several viewers mean several of these. Measured on the field host
+ * after one session: the proxy container sat at 796 MB with 4.1 GB free and 1.3
+ * GB already in swap, so a fixed half-gigabyte per torrent is not something to
+ * hand out blindly. Hence: a quarter of what is free, capped.
+ */
+const MEMORY_BUDGET_CEILING_BYTES = 512 * 1024 * 1024;
+const FREE_MEMORY_SHARE = 0.25;
+
+/**
+ * Budget for one torrent's resident pieces when the caller names none.
+ *
+ * @returns {number}
+ */
+function defaultMemoryBytes() {
+  const share = Math.floor(os.freemem() * FREE_MEMORY_SHARE);
+  return Math.max(MIN_BUDGET_BYTES, Math.min(MEMORY_BUDGET_CEILING_BYTES, share));
+}
+
+/** Floor for the automatic budget — below this the store thrashes to disk. */
+const MIN_BUDGET_BYTES = 64 * 1024 * 1024;
+/**
+ * Never keep fewer than this many pieces resident, whatever the budget says.
+ *
+ * Two is the smallest workable number rather than a round one: a piece being
+ * read holds its slot, so a second slot must exist for the next piece to land
+ * in. With one, a single reader would deadlock the store against itself.
+ */
+const MIN_RESIDENT_PIECES = 2;
+
+/**
+ * A chunk store holding pieces in a `SharedArrayBuffer`, spilling to disk.
+ *
+ * Implements the `abstract-chunk-store` shape WebTorrent expects — `put`,
+ * `get`, `close`, `destroy` — plus {@link locate}, {@link pin} and
+ * {@link unpin}, which is how the main thread reads a piece without it being
+ * copied or moved.
+ */
+export class SharedPieceStore {
+  #chunkLength;
+  #lastChunkLength;
+  #lastChunkIndex;
+  #capacity;
+  /** @type {SharedArrayBuffer} */
+  #shared;
+  /** @type {Buffer} A view over the whole pool, for slot arithmetic. */
+  #pool;
+  /** Piece index → slot number. */
+  #slotOf = new Map();
+  /** Slot numbers not currently holding a piece. */
+  #freeSlots = [];
+  #lru;
+  #disk;
+  /** Slots backed by memory right now; grows towards {@link capacity}. */
+  #allocatedSlots = 0;
+  #closed = false;
+  #name;
+  /**
+   * What the store has actually been doing. Reported, not just kept: the
+   * balance between memory and disk reads is the number that says whether the
+   * budget is right, and it cannot be guessed from outside.
+   */
+  #counters = {
+    fromMemory: 0,
+    fromDisk: 0,
+    spills: 0,
+    revivals: 0,
+    blockedByPins: 0
+  };
+
+  /**
+   * @param {number} chunkLength - Piece length, and therefore the slot size.
+   * @param {object} [options]
+   * @param {number} [options.length] - Total torrent length, so the short last piece is sized correctly.
+   * @param {number} [options.memoryBytes] - Budget for resident pieces.
+   * @param {string} [options.path] - Directory for the spill file.
+   * @param {string} [options.name] - Spill file name; must be unique per torrent.
+   */
+  constructor(chunkLength, options = {}) {
+    if (!Number.isInteger(chunkLength) || chunkLength < 1) {
+      throw new Error(`Chunk length must be a positive integer, got ${chunkLength}.`);
+    }
+    this.#chunkLength = chunkLength;
+
+    const totalLength = Number.isFinite(options.length) ? options.length : 0;
+    this.#lastChunkIndex = totalLength > 0 ? Math.ceil(totalLength / chunkLength) - 1 : -1;
+    const remainder = totalLength % chunkLength;
+    this.#lastChunkLength = remainder === 0 ? chunkLength : remainder;
+
+    const memoryBytes = Number.isFinite(options.memoryBytes) && options.memoryBytes > 0
+      ? options.memoryBytes
+      : defaultMemoryBytes();
+    this.#capacity = Math.max(MIN_RESIDENT_PIECES, Math.floor(memoryBytes / chunkLength));
+
+    // Grows into the budget instead of taking it up front. The budget is per
+    // torrent, so claiming all of it on `add` would charge a host for pieces
+    // nobody has asked for — and a torrent that is merely open, or one being
+    // probed for its codecs, needs a handful of slots, not the ceiling.
+    this.#shared = new SharedArrayBuffer(MIN_RESIDENT_PIECES * chunkLength, {
+      maxByteLength: this.#capacity * chunkLength
+    });
+    this.#pool = Buffer.from(this.#shared);
+    for (let slot = 0; slot < MIN_RESIDENT_PIECES; slot += 1) {
+      this.#freeSlots.push(slot);
+    }
+    this.#allocatedSlots = MIN_RESIDENT_PIECES;
+    this.#lru = new PieceLru(this.#capacity);
+    this.#name = options.name ?? "pieces";
+    this.#disk = new DiskTier({
+      directory: options.path ?? ".",
+      name: `${this.#name}.pieces`,
+      chunkLength
+    });
+    liveStores.add(this);
+  }
+
+  /**
+   * What this store has been doing, for the periodic report.
+   *
+   * @returns {{ name: string, resident: number, capacity: number, spilled: number, fromMemory: number, fromDisk: number, spills: number, revivals: number, blockedByPins: number }}
+   */
+  stats() {
+    return {
+      name: this.#name,
+      resident: this.#slotOf.size,
+      capacity: this.#capacity,
+      spilled: this.#disk.size,
+      ...this.#counters
+    };
+  }
+
+  /** `abstract-chunk-store` exposes the piece size under this name. */
+  get chunkLength() {
+    return this.#chunkLength;
+  }
+
+  /**
+   * The pool itself, so another thread can map the same memory and read a piece
+   * by the offset {@link locate} reports.
+   *
+   * @returns {SharedArrayBuffer}
+   */
+  get sharedBuffer() {
+    return this.#shared;
+  }
+
+  /** How many pieces fit in memory at once. */
+  get capacity() {
+    return this.#capacity;
+  }
+
+  /** How many pieces are resident right now. */
+  get residentCount() {
+    return this.#slotOf.size;
+  }
+
+  /** How many pieces have been spilled to disk. */
+  get spilledCount() {
+    return this.#disk.size;
+  }
+
+  /**
+   * Length of a given piece — the last one is usually short.
+   *
+   * @param {number} index
+   * @returns {number}
+   */
+  #lengthOf(index) {
+    return index === this.#lastChunkIndex ? this.#lastChunkLength : this.#chunkLength;
+  }
+
+  /**
+   * Where a resident piece sits in the shared pool, or `null` if it is not
+   * resident.
+   *
+   * The main thread reads straight from those bytes, so callers MUST hold a pin
+   * across the read — see {@link pin}.
+   *
+   * @param {number} index
+   * @returns {{ offset: number, length: number } | null}
+   */
+  locate(index) {
+    const slot = this.#slotOf.get(index);
+    if (slot === undefined) {
+      return null;
+    }
+    return { offset: slot * this.#chunkLength, length: this.#lengthOf(index) };
+  }
+
+  /**
+   * Hold a piece in memory across a read. Nested; release with {@link unpin}.
+   *
+   * @param {number} index
+   * @returns {void}
+   */
+  pin(index) {
+    this.#lru.pin(index);
+  }
+
+  /**
+   * @param {number} index
+   * @returns {void}
+   */
+  unpin(index) {
+    this.#lru.unpin(index);
+  }
+
+  /**
+   * Make a slot available, spilling the least recently used piece if need be.
+   *
+   * @returns {Promise<number>} Slot number.
+   */
+  async #claimSlot() {
+    const free = this.#freeSlots.pop();
+    if (free !== undefined) {
+      return free;
+    }
+
+    // Room left in the budget: take more memory rather than evicting. Growing
+    // replaces the view over the pool, so every slot offset stays valid — the
+    // bytes do not move.
+    if (this.#allocatedSlots < this.#capacity) {
+      this.#allocatedSlots += 1;
+      this.#shared.grow(this.#allocatedSlots * this.#chunkLength);
+      this.#pool = Buffer.from(this.#shared);
+      return this.#allocatedSlots - 1;
+    }
+
+    const victim = this.#lru.evictionCandidate();
+    if (victim === null) {
+      // Every resident piece is being read. Taking one anyway is precisely the
+      // failure this store exists to make impossible.
+      this.#counters.blockedByPins += 1;
+      throw new Error("Every resident piece is pinned; no slot can be freed.");
+    }
+
+    const slot = this.#slotOf.get(victim);
+    const bytes = this.#pool.subarray(slot * this.#chunkLength, slot * this.#chunkLength + this.#lengthOf(victim));
+    await this.#disk.write(victim, bytes);
+    this.#counters.spills += 1;
+
+    this.#slotOf.delete(victim);
+    this.#lru.remove(victim);
+    return slot;
+  }
+
+  /**
+   * Store a piece.
+   *
+   * @param {number} index
+   * @param {Uint8Array} bytes
+   * @param {(error?: Error | null) => void} [callback]
+   * @returns {void}
+   */
+  put(index, bytes, callback = () => undefined) {
+    if (this.#closed) {
+      queueMicrotask(() => callback(new Error("Piece store is closed.")));
+      return;
+    }
+
+    const existing = this.#slotOf.get(index);
+    const write = async () => {
+      const slot = existing ?? (await this.#claimSlot());
+      bytes.copy
+        ? bytes.copy(this.#pool, slot * this.#chunkLength)
+        : this.#pool.set(bytes, slot * this.#chunkLength);
+      this.#slotOf.set(index, slot);
+      this.#lru.touch(index);
+      // A newer copy is in memory; whatever is on disk is stale.
+      this.#disk.forget(index);
+    };
+
+    write().then(() => callback(null), (error) => callback(error));
+  }
+
+  /**
+   * Fetch a piece, or a range within it.
+   *
+   * Returns a buffer of its own rather than a view into the pool: WebTorrent
+   * keeps what it is given — to verify a hash, to serve a peer — and the slot
+   * underneath may be reused meanwhile. The thread-crossing path avoids this
+   * copy entirely by going through {@link locate}.
+   *
+   * @param {number} index
+   * @param {{ offset?: number, length?: number } | ((error: Error | null, bytes?: Buffer) => void)} [options]
+   * @param {(error: Error | null, bytes?: Buffer) => void} [callback]
+   * @returns {void}
+   */
+  get(index, options, callback) {
+    if (typeof options === "function") {
+      return this.get(index, undefined, options);
+    }
+    const done = callback ?? (() => undefined);
+    if (this.#closed) {
+      queueMicrotask(() => done(new Error("Piece store is closed.")));
+      return;
+    }
+
+    const pieceLength = this.#lengthOf(index);
+    const offset = options?.offset ?? 0;
+    const length = options?.length ?? pieceLength - offset;
+
+    const fetch = async () => {
+      const slot = this.#slotOf.get(index);
+      if (slot !== undefined) {
+        this.#lru.touch(index);
+        this.#counters.fromMemory += 1;
+        const start = slot * this.#chunkLength + offset;
+        return Buffer.from(this.#pool.subarray(start, start + length));
+      }
+
+      if (!this.#disk.has(index)) {
+        throw new Error(`Piece ${index} is not in the store.`);
+      }
+
+      // Bring it back into memory: it was just asked for, so it is likely to be
+      // asked for again, and the caller may follow up with `locate`.
+      const revived = await this.#claimSlot();
+      const target = this.#pool.subarray(
+        revived * this.#chunkLength,
+        revived * this.#chunkLength + pieceLength
+      );
+      await this.#disk.read(index, target);
+      this.#slotOf.set(index, revived);
+      this.#lru.touch(index);
+      this.#counters.fromDisk += 1;
+      this.#counters.revivals += 1;
+      const start = revived * this.#chunkLength + offset;
+      return Buffer.from(this.#pool.subarray(start, start + length));
+    };
+
+    fetch().then((bytes) => done(null, bytes), (error) => done(error));
+  }
+
+  /**
+   * Close the store, keeping the spill file.
+   *
+   * @param {(error?: Error | null) => void} [callback]
+   * @returns {void}
+   */
+  close(callback = () => undefined) {
+    this.#closed = true;
+    liveStores.delete(this);
+    this.#disk.close().then(() => callback(null), (error) => callback(error));
+  }
+
+  /**
+   * Close the store and delete everything it wrote.
+   *
+   * @param {(error?: Error | null) => void} [callback]
+   * @returns {void}
+   */
+  destroy(callback = () => undefined) {
+    this.#closed = true;
+    liveStores.delete(this);
+    this.#slotOf.clear();
+    this.#disk.destroy().then(() => callback(null), (error) => callback(error));
+  }
+}