@torrent-tv/proxy 2.9.23 → 2.9.25

package/openspec/changes/proxy-observability/specs/observability/spec.md

@@ -0,0 +1,33 @@
+# observability — delta spec
+
+## ADDED Requirements
+
+### Requirement: Health endpoints report the version
+`GET /healthz` and `GET /health` SHALL include the running proxy version
+(from package.json) alongside the existing `ok` field.
+
+#### Scenario: Version visible remotely
+- **WHEN** a client requests `/healthz`
+- **THEN** the response contains `ok: true` and the exact npm package version
+  of the running proxy
+
+### Requirement: Peer-discovery diagnostics
+The proxy SHALL log, per torrent: an added line with file count, `private`
+flag and tracker count; every torrent-level warning (tracker rejections and
+errors surface as warnings); and each tracker announce response with the
+seeder/leecher counts returned. Logging failures MUST NOT affect playback
+(best-effort, defensive against WebTorrent internals).
+
+#### Scenario: Zero-peer torrent is explainable
+- **WHEN** a torrent sits at zero peers
+- **THEN** the log shows either the tracker's rejection/warning text or an
+  announce response with zero seeders — distinguishing "tracker refused us"
+  from "the swarm is empty"
+
+### Requirement: No SSDP listener warnings
+Port mapping SHALL NOT flood the log with `MaxListenersExceededWarning`
+regardless of how many ports one mapper maps or renews.
+
+#### Scenario: WebRTC UDP range mapping
+- **WHEN** the UDP mapper maps its 10-port range and later auto-renews it
+- **THEN** no MaxListenersExceededWarning lines appear in the log

package/openspec/changes/proxy-observability/tasks.md

@@ -0,0 +1,20 @@
+# Tasks: Proxy observability
+
+## 1. Implementation
+
+- [x] 1.1 Version in `/healthz` and `/health` (createRequire package.json in
+      server.js, passed as route dep)
+- [x] 1.2 torrent-pool.js: added-torrent line (files/private/trackers),
+      torrent `warning` logging, tracker `update` (announce seeders/leechers)
+      logging with defensive access, client-level warning logging
+- [x] 1.3 port-mapper.js: setMaxListeners(0) on the UPnP SSDP emitter after
+      the first successful map()
+- [x] 1.4 Syntax checks + healthz handler smoke test (version present)
+
+## 2. Release
+
+- [x] 2.1 CHANGELOG.md entry at 2.9.25
+- [ ] 2.2 `npm run patch` (needs npm auth), then ha-addon bump 0.2.47 + push
+- [ ] 2.3 After the addon updates: verify version via `/healthz`, watch the
+      addon log for announce lines on a real torrent, confirm no SSDP
+      warnings

package/openspec/config.yaml

@@ -0,0 +1,38 @@
+schema: spec-driven
+
+context: |
+  @torrent-tv/proxy — WebTorrent + ffmpeg, published to npm. Downloads a torrent
+  and streams the chosen file to the browser over a WebRTC data channel (plain
+  HTTPS transport planned), transcoding to HLS only for the track(s) the browser
+  cannot play natively (supported track = copied).
+  Constraints (see CLAUDE.md for the full set):
+  - Deployment-agnostic: the HA addon is only one way to run it. No
+    Home-Assistant assumptions; runtime detection with graceful fallback only.
+  - Routes: routes/<path>/<method>.js exporting handle<Name><Method>.
+  - All code, comments and docs in English.
+  - Every behavioural change adds a CHANGELOG.md entry at current package.json
+    version + 1 patch. Never edit package.json version (npm run patch bumps it).
+  - Any behavioural proxy change requires bumping ha-addon config.yaml version
+    in the same changeset (the addon must be re-released to pull the new proxy).
+  - HLS is VOD-only with server-side seeking (never -hls_playlist_type event).
+  - Hardware encoders are gated by a strict startup test; software libx264 is
+    the fallback.
+
+# Project context (optional)
+# This is shown to AI when creating artifacts.
+# Add your tech stack, conventions, style guides, domain knowledge, etc.
+# Example:
+#   context: |
+#     Tech stack: TypeScript, React, Node.js
+#     We use conventional commits
+#     Domain: e-commerce platform
+
+# Per-artifact rules (optional)
+# Add custom rules for specific artifacts.
+# Example:
+#   rules:
+#     proposal:
+#       - Keep proposals under 500 words
+#       - Always include a "Non-goals" section
+#     tasks:
+#       - Break tasks into chunks of max 2 hours

package/package.json

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

package/routes/health/get.js

@@ -5,8 +5,9 @@
  *
  * @param {import("fastify").FastifyRequest} _req
  * @param {import("fastify").FastifyReply} reply
+ * @param {{ version: string }} deps
  * @returns {Promise<void>}
  */
-export async function handleHealthGet(_req, reply) {
-  return reply.send({ ok: true });
+export async function handleHealthGet(_req, reply, { version } = {}) {
+  return reply.send({ ok: true, version });
 }

package/routes/healthz/get.js

@@ -5,8 +5,9 @@
  *
  * @param {import("fastify").FastifyRequest} _req
  * @param {import("fastify").FastifyReply} reply
+ * @param {{ version: string }} deps
  * @returns {Promise<void>}
  */
-export async function handleHealthzGet(_req, reply) {
-  return reply.send({ ok: true });
+export async function handleHealthzGet(_req, reply, { version } = {}) {
+  return reply.send({ ok: true, version });
 }

package/server.js

@@ -12,6 +12,7 @@ import fastifyHelmet from "@fastify/helmet";
 import fastifyStatic from "@fastify/static";
 import getPort from "get-port";
 import path from "node:path";
+import { createRequire } from "node:module";
 import { fileURLToPath } from "node:url";
 import { handleHealthGet } from "./routes/health/get.js";
 import { handleHealthzGet } from "./routes/healthz/get.js";
@@ -32,6 +33,8 @@ import { logger } from "./utils/logger.js";
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
+const require = createRequire(import.meta.url);
+const { version } = require("./package.json");
 const publicRoot = path.resolve(__dirname, "./public");
 
 /**
@@ -121,8 +124,8 @@ export async function startProxyServer({ host, port, transcodeAudio, ffmpegBin }
     torrentPool
   });
 
-  app.get("/health", async (req, reply) => handleHealthGet(req, reply));
-  app.get("/healthz", async (req, reply) => handleHealthzGet(req, reply));
+  app.get("/health", async (req, reply) => handleHealthGet(req, reply, { version }));
+  app.get("/healthz", async (req, reply) => handleHealthzGet(req, reply, { version }));
   app.post("/api/sources", async (req, reply) =>
     handleApiSourcesPost(req, reply, { sourceRegistry })
   );

package/services/port-mapper.js

@@ -157,6 +157,13 @@ export function createPortMapper({
             `map ${p}`
           );
           mappedCount++;
+          if (mappedCount === 1) {
+            // The UPnP SSDP emitter gains one listener per map()/renewal; a
+            // 10-port range exceeds Node's default limit of 10 and floods the
+            // log with MaxListenersExceededWarning. The client is created
+            // lazily by the first map(), so lift the limit right after it.
+            instance._upnpClient?.ssdp?.setMaxListeners?.(0);
+          }
         } catch (error) {
           logger.warn(`port-mapper: failed to map ${protocol} ${p}: ${describeError(error)}`);
         }

package/services/torrent-pool.js

@@ -7,9 +7,23 @@
  */
 
 import crypto from "node:crypto";
+import os from "node:os";
+import path from "node:path";
+import { rmSync } from "node:fs";
 import WebTorrent from "webtorrent";
 import { logger } from "../utils/logger.js";
 
+// WebTorrent's default download root (see webtorrent lib/torrent.js: TMP =
+// path.join(os.tmpdir(), 'webtorrent')). We use the default store, so all
+// torrent data lives under here.
+const WEBTORRENT_STORE_ROOT = path.join(os.tmpdir(), "webtorrent");
+
+// How long a torrent may sit with zero active file readers before it is
+// removed (with its on-disk store). Generous so brief gaps between ffmpeg
+// range reads — or a short pause — do not evict an in-use torrent; a longer
+// idle (viewer gone) frees the disk. Re-requesting re-adds (re-downloads) it.
+const TORRENT_IDLE_TTL_MS = 300_000;
+
 // Bytes ahead of a read position to mark CRITICAL (download-first) on each
 // range request. Big enough to unstick a seek into an undownloaded region,
 // small enough not to make "everything critical" (which defeats prioritization).
@@ -55,7 +69,26 @@ export class TorrentPool {
    */
   #pending = new Map();
 
+  /**
+   * Pending idle-removal timers, keyed by torrent object. A torrent with zero
+   * file refcount is scheduled for removal; re-acquiring it cancels the timer.
+   *
+   * @type {Map<import("webtorrent").Torrent, ReturnType<typeof setTimeout>>}
+   */
+  #idleTimers = new Map();
+
   constructor() {
+    // Sweep orphaned torrent data left by a previous hard kill (no graceful
+    // shutdown ran, so destroyAll never cleaned the store). Safe here: no
+    // torrents are loaded yet at construction. Best-effort, synchronous so it
+    // completes before the client starts writing.
+    try {
+      rmSync(WEBTORRENT_STORE_ROOT, { recursive: true, force: true });
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      logger.warn(`torrent-pool: could not sweep orphaned store at startup: ${message}`);
+    }
+
     /** @type {import("webtorrent").WebTorrent} */
     this.client = new WebTorrent();
 
@@ -77,6 +110,50 @@ export class TorrentPool {
     this.client.on("error", (error) => {
       logger.error(`WebTorrent client error: ${error.message}`);
     });
+    this.client.on("warning", (warning) => {
+      const message = warning instanceof Error ? warning.message : String(warning);
+      logger.warn(`torrent-pool: client warning: ${message}`);
+    });
+  }
+
+  /**
+   * Attach peer-discovery diagnostics to a freshly added torrent: tracker
+   * announce results (seeders/leechers per announce) and torrent-level
+   * warnings (tracker rejections/errors surface here). Without these a
+   * zero-peer torrent gives no clue WHY it has no peers.
+   *
+   * @param {string} label - Short source label for log lines.
+   * @param {import("webtorrent").Torrent} torrent
+   * @returns {void}
+   */
+  #attachSwarmDiagnostics(label, torrent) {
+    const trackerCount = Array.isArray(torrent.announce) ? torrent.announce.length : 0;
+    logger.info(
+      `torrent-pool: [${label}] added: files=${torrent.files?.length ?? 0} ` +
+        `private=${torrent.private ? "yes" : "no"} trackers=${trackerCount}`
+    );
+
+    torrent.on("warning", (warning) => {
+      const message = warning instanceof Error ? warning.message : String(warning);
+      logger.warn(`torrent-pool: [${label}] warning: ${message}`);
+    });
+
+    // bittorrent-tracker's Client emits "update" with each announce response.
+    // `complete`/`incomplete` are the tracker's seeder/leecher counts — the
+    // authoritative answer to "does the tracker accept us and does the swarm
+    // have anyone in it". Internal API, so strictly best-effort.
+    const tracker = torrent.discovery?.tracker;
+    if (tracker && typeof tracker.on === "function") {
+      tracker.on("update", (data) => {
+        const announceUrl = typeof data?.announce === "string" ? data.announce : "?";
+        logger.info(
+          `torrent-pool: [${label}] announce ${announceUrl}: ` +
+            `seeders=${data?.complete ?? "?"} leechers=${data?.incomplete ?? "?"}`
+        );
+      });
+    } else {
+      logger.info(`torrent-pool: [${label}] tracker client not exposed; announce results not logged`);
+    }
   }
 
   /**
@@ -115,6 +192,9 @@ export class TorrentPool {
         this.client.off("error", onError);
         this.torrents.set(key, readyTorrent);
         this.#pending.delete(key);
+        // Key layout is `${sourceType}:${sha1}`; log with the sha1 prefix so
+        // lines correlate with the [stats] source key.
+        this.#attachSwarmDiagnostics(key.split(":")[1]?.slice(0, 8) ?? key, readyTorrent);
         resolve(readyTorrent);
       });
     });
@@ -170,6 +250,8 @@ export class TorrentPool {
       usage = new Map();
       this.fileUsageByTorrent.set(torrent, usage);
     }
+    // The torrent is in use again — cancel any pending idle removal.
+    this.#cancelIdleRemoval(torrent);
     usage.set(fileIndex, (usage.get(fileIndex) ?? 0) + 1);
     this.#syncSelections(torrent, usage);
 
@@ -187,11 +269,84 @@ export class TorrentPool {
       }
       if (usage.size === 0) {
         this.fileUsageByTorrent.delete(torrent);
+        // No active readers — schedule removal (with store) after an idle TTL.
+        this.#scheduleIdleRemoval(torrent);
       }
       this.#syncSelections(torrent, usage);
     };
   }
 
+  /**
+   * Schedule removal of a torrent (with its on-disk store) after
+   * {@link TORRENT_IDLE_TTL_MS} of zero file refcount. Idempotent — replaces
+   * any existing timer for the torrent.
+   *
+   * @param {import("webtorrent").Torrent} torrent
+   * @returns {void}
+   */
+  #scheduleIdleRemoval(torrent) {
+    if (!torrent) {
+      return;
+    }
+    this.#cancelIdleRemoval(torrent);
+    const timer = setTimeout(() => {
+      this.#idleTimers.delete(torrent);
+      // Re-check: a new acquire since scheduling would have cancelled this
+      // timer, but guard anyway against a race.
+      const usage = this.fileUsageByTorrent.get(torrent);
+      if (usage && usage.size > 0) {
+        return;
+      }
+      this.#removeTorrent(torrent);
+    }, TORRENT_IDLE_TTL_MS);
+    timer.unref?.();
+    this.#idleTimers.set(torrent, timer);
+  }
+
+  /**
+   * Cancel a pending idle-removal timer for a torrent, if any.
+   *
+   * @param {import("webtorrent").Torrent} torrent
+   * @returns {void}
+   */
+  #cancelIdleRemoval(torrent) {
+    const timer = this.#idleTimers.get(torrent);
+    if (timer) {
+      clearTimeout(timer);
+      this.#idleTimers.delete(torrent);
+    }
+  }
+
+  /**
+   * Remove a torrent from the pool together with its on-disk store, freeing
+   * disk while the proxy keeps running. Best-effort.
+   *
+   * @param {import("webtorrent").Torrent} torrent
+   * @returns {void}
+   */
+  #removeTorrent(torrent) {
+    if (!torrent) {
+      return;
+    }
+    // Drop it from the source→torrent map so a later request re-adds it.
+    for (const [key, value] of this.torrents) {
+      if (value === torrent) {
+        this.torrents.delete(key);
+        break;
+      }
+    }
+    this.fileUsageByTorrent.delete(torrent);
+    const name = typeof torrent.name === "string" ? torrent.name : "(unknown)";
+    try {
+      torrent.destroy({ destroyStore: true }, () => {
+        logger.info(`torrent-pool: removed idle torrent "${name}" and its store`);
+      });
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      logger.warn(`torrent-pool: failed to remove idle torrent "${name}": ${message}`);
+    }
+  }
+
   /**
    * Return download statistics for a torrent and optionally a specific file.
    *
@@ -438,6 +593,12 @@ export class TorrentPool {
    * @returns {Promise<void>}
    */
   async destroyAll() {
+    // Cancel any pending idle-removal timers — destroyAll handles teardown.
+    for (const timer of this.#idleTimers.values()) {
+      clearTimeout(timer);
+    }
+    this.#idleTimers.clear();
+
     if (!this.client || this.client.destroyed) {
       return;
     }