@torrent-tv/proxy 2.9.24 → 2.9.25

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.24",
+  "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

@@ -110,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`);
+    }
   }
 
   /**
@@ -148,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);
       });
     });