@torrent-tv/proxy 2.73.1 → 2.74.0

package/CLAUDE.md

@@ -1,160 +1,165 @@
-# proxy — @torrent-tv/proxy (WebTorrent + ffmpeg)
-
-Downloads a torrent and streams the chosen file to the browser, transcoding to
-HLS only when needed. See the parent `../CLAUDE.md` for the overall architecture
-and release process.
-
-## Deployment-agnostic — important
-
-The HA addon is only ONE way to run this; bare npm and Docker are planned. Keep
-all code free of Home-Assistant assumptions. Anything host-specific (GPU
-devices, ffmpeg build, CLI flags) belongs in the `ha-addon` layer. Hardware
-detection must probe at runtime and fall back gracefully; do not assume a
-Linux-only host (e.g. POSIX-only signals must degrade elsewhere).
-
-## Layout
-
-- `bin/cli.js` — CLI entry; resolves `ffmpegBin` (uses `--ffmpeg-bin` if given,
-  else bundled ffmpeg-static, else PATH `ffmpeg`).
-- `server.js` — Fastify setup; detects the video encoder at startup
-  (`detectVideoEncoder`) and passes it to `HlsSessionManager`.
-- `routes/<path>/<method>.js` — same convention as the server repo.
-  - `routes/stream/get.js` — byte-range torrent file streaming (HTTP 206).
-  - `routes/api/playback-plan/post.js` — codec/container/duration probe result.
-  - `routes/transcode/session-file/get.js` — serves HLS playlist/segments;
-    long-polls while a segment is being produced, returns retryable 503 (never
-    202 — hls.js can't consume it).
-- `services/`:
-  - `demand/` — what anybody wants, in BYTES: `Window` (claimant, file, byte
-    range, urgency), `Urgency` (BLOCKED / NEAR / AHEAD / TAIL / BEHIND),
-    `DemandRegister` (live windows by claimant), `pieces.js` (the one place
-    bytes become piece numbers). No WebTorrent, no piece store, no pieces.
-  - `download/` — `SwarmSelection`, the ONLY thing that calls `select`,
-    `deselect` or `critical`, and `registry.js`, which holds one per torrent and
-    owns the cross-torrent rule that withholds the speculative levels while
-    anything urgent is missing anywhere. See `docs/download-architecture.md`.
-  - `container/` — domain layer: `Container` (abstract, RFC 9559 / ISO 14496-12),
-    `MatroskaContainer` / `Mp4Container` / `AviContainer`, `ContainerFactory`
-    (sniff 16 bytes → precise subclass). See `docs/container-architecture.md`.
-  - `tracks/` — domain layer: `ContainerTrack` (base: TrackNumber, declaredIndex,
-    language/BCP47, isEnabled/isDefault) → `VideoTrack` / `AudioTrack` /
-    `SubtitleTrack` → `TextSubtitleTrack` / `ImageSubtitleTrack`,
-    `ExternalSubtitleFile`. Spec-accurate flags (FlagForced only on subtitles per
-    RFC 9559 §5.1.4.1, FlagOriginal/Commentary only on audio, tkhd
-    track_enabled / alternate_group, elng BCP47).
-  - `orchestrators/` — application layer: `ContainerOrchestrator` (detect + per-file
-    cache, `getTracks`/`getKeyframeIndex`), `SubtitleOrchestrator` (wraps
-    `torrent-worker/subtitle-cues.js` cluster walk + `Container` tracks, warm/push).
-  - `controllers/` — interface layer: `PlaybackController` / `SubtitleController`
-    (thin adapters over orchestrators; routes depend on controllers, not services).
-    `routes/*` are now thin HTTP translators.
-  - `container-index/` — legacy readers (ebml-reader, matroska/mp4/avi keyframe and
-    subtitle tables) — used internally by `container/*`, deprecated as direct import.
-  - `docs/download-architecture.md` — the two axes of downloading: what is
-    wanted (`demand/`) against what the swarm is told (`download/`), why urgency
-    is not a number given to the library, and why the speculative levels are
-    withdrawn rather than lowered.
-  - `docs/logs.md` — where to find logs (HA `docker logs` + `/data/proxy.log`, DO
-    `infra-server-1` with forwarded frontend `POST /api/client-logs`). Browser
-    console not needed.
-  - `playback-planner.js` — single ffmpeg probe returns audioCodec, videoCodec,
-    container, durationSeconds. `mode` is advisory; the browser decides.
-  - `hls-session-manager.js` — one ffmpeg per (source, file, settings). Serves a
-    synthetic full-duration VOD playlist; produces segments on demand; restarts
-    ffmpeg at the requested segment for server-side seeking. Short idle TTL.
-    Uses the detected `videoEncoder` for video re-encode (copy otherwise).
-  - `hwaccel.js` — detect best H.264 encoder (NVENC/QSV/VAAPI/V4L2M2M) with a
-    STRICT startup test: encode `testsrc2` through the real HLS pipeline, then
-    verify each segment decodes independently (catches non-IDR/corrupted hw
-    output). Falls back to software libx264. Runtime fallback to software if a
-    hw encode later fails. v4l2m2m is gated by this test (fails on HA Yellow).
-  - `data-channel-handler.js` — forwards WebRTC data-channel requests to the
-    local HTTP server (loopback), so the same routes serve both transports.
-
-## Gotchas
-
-- Do NOT use `-hls_playlist_type event` — it breaks duration/seek. VOD only.
-- A transitive dep (`ip-set`, via webtorrent) ships a hostile
-  `preinstall: npx only-allow pnpm` that breaks `npm install`. The addon works
-  around it with `--ignore-scripts` + a targeted rebuild of `node-datachannel`;
-  if you ever change install flow, keep that in mind.
-
-## Planned: public reachability (remote access)
-
-Decided direction — full plan in the parent `../CLAUDE.md`. Proxy-side pieces:
-
-- **Auto port mapping** — IMPLEMENTED (`services/port-mapper.js`, changelog
-  2.9.16). UPnP IGD / NAT-PMP via `@silentbot1/nat-api` (now a direct dep; the
-  same lib WebTorrent uses for the torrent port). Maps TCP 9090 with a 2 h
-  auto-renewed lease, removed on shutdown (lease expiry covers hard kills).
-  Best-effort + start/stop timeouts; `--no-port-mapping` opts out;
-  `getMappedEndpoint()` exposes the external endpoint. NOT yet done: mapping the
-  **UDP** port WebRTC actually uses (it binds ephemeral UDP ports, so this TCP
-  mapping does not yet help WebRTC — roadmap step 3 in the parent CLAUDE.md).
-  Also pending (next iteration): a success log line in `port-mapper.js` `stop()`
-  (`removed mapping for TCP <port>`) — today stop() only logs on failure, so a
-  clean unmap on shutdown is silent.
-- **Report endpoint to server** — ✅ DONE (proxy 2.9.17). The mapped endpoint
-  is sent over the tunnel (`tunnel-client.sendEndpoint` → `proxy-endpoint`) on
-  mapping success and on every tunnel (re)connect; the server dial-back-verifies
-  reachability (server 0.8.22, roadmap step 2).
-- **HTTPS listener**: serve the existing routes over TLS with a per-proxy
-  certificate delivered by the server through the tunnel (persist cert+key
-  locally; ~90-day renewals are pushed the same way). Add CORS headers for the
-  web-app origin so hls.js / `<video>` can fetch cross-origin.
-- Plain HTTPS becomes the preferred video transport; WebRTC data channel stays
-  as fallback for hosts where no port could be opened.
-- **Later roadmap steps** (single staged roadmap in parent `../CLAUDE.md`,
-  WebRTC-first ordering): step 3 map the WebRTC UDP port (fixed
-  `portRangeBegin`/`End` + UPnP-map UDP); step 4 birthday-paradox port
-  prediction (open ~256 UDP sockets, inject predicted-port ICE candidates) for
-  symmetric NAT; step 5 IPv6-first (audit the candidate filter — do not drop
-  *global* v6) + STUN NAT pre-classification reported to the registry; then
-  the DNS+TLS path (steps 6–7); step 8 relay-then-upgrade (deferred).
-- Future: ed25519 proxy identity (sign announcements), BEP 44 endpoint
-  announcements via the `bittorrent-dht` already bundled with WebTorrent.
-
-All of this must stay deployment-agnostic (HA addon, bare npm, Docker).
-
-## Disk hygiene (open item — torrent data is NOT cleaned up today)
-
-HLS segments are handled (`hls-session-manager.js`: idle TTL, `disposeSession`,
-`disposeAll`). Torrent data is **partially** handled: shutdown cleanup is done
-(`TorrentPool.destroyAll()` with `destroyStore: true`, wired into the `onClose`
-hook — proxy 2.9.15), but `deselect()` only stops further download and nothing
-removes a torrent's data **while the proxy keeps running**, nor sweeps orphans
-left by a previous hard kill at startup.
-
-Level 1 — remaining: `client.remove(torrent, { destroyStore: true })` on last-
-file refcount 0 + idle TTL (mirror the HLS session model); startup sweep of
-orphaned store dirs under `os.tmpdir()`; global disk cap with LRU eviction of
-whole torrents. (Shutdown teardown ✅ done.)
-Level 2 (research): sliding-window chunk store. Full rationale in the parent
-`../CLAUDE.md` "Disk hygiene" section.
-
-## Cloud proxy
-
-The same proxy code also runs as the company-hosted fallback when the user
-pool can't serve a viewer. Keep the proxy host-agnostic so it runs unchanged on
-rented infra (flat-rate/unmetered bandwidth — Hetzner dedicated / OVH; NOT
-metered-egress clouds). Provider/economics analysis in the parent
-`../CLAUDE.md` "Cloud proxy" section.
-
-## Changelog
-
-Every behavioural change must be recorded in `CHANGELOG.md` — add an entry under
-a new `## <version>` heading at the top, following the existing
-`- **New**/**Fix**/**Chore**:` format.
-
-**Do NOT edit `package.json` version.** `npm run patch`/`minor` runs `npm
-version …` which bumps it. Write the CHANGELOG entry at the version that bump
-will produce: **current `package.json` version + 1 patch** (or + 1 minor).
-Accumulate bullets into that single pending entry until it's published. See the
-parent `../CLAUDE.md`.
-
-## Release
-
-`npm run patch` (publishes to npm + pushes tags). The HA addon then needs its
-own version bump to pull the new package. Publish proxy BEFORE bumping the addon.
-
-**Any proxy change requires bumping the ha-addon version** (`ha-addon/torrent_tv_proxy/config.yaml`). The addon installs the proxy from npm at build time and the build is cached; without a version bump the plugin will NOT update and keeps running the old proxy. So after `npm run patch`, always bump the addon `config.yaml` version, push, and update the addon.
+# proxy — @torrent-tv/proxy (WebTorrent + ffmpeg)
+
+Downloads a torrent and streams the chosen file to the browser, transcoding to
+HLS only when needed. See the parent `../CLAUDE.md` for the overall architecture
+and release process.
+
+## Deployment-agnostic — important
+
+The HA addon is only ONE way to run this; bare npm and Docker are planned. Keep
+all code free of Home-Assistant assumptions. Anything host-specific (GPU
+devices, ffmpeg build, CLI flags) belongs in the `ha-addon` layer. Hardware
+detection must probe at runtime and fall back gracefully; do not assume a
+Linux-only host (e.g. POSIX-only signals must degrade elsewhere).
+
+## Layout
+
+- `bin/cli.js` — CLI entry; resolves `ffmpegBin` (uses `--ffmpeg-bin` if given,
+  else bundled ffmpeg-static, else PATH `ffmpeg`).
+- `server.js` — Fastify setup; detects the video encoder at startup
+  (`detectVideoEncoder`) and passes it to `HlsSessionManager`.
+- `routes/<path>/<method>.js` — same convention as the server repo.
+  - `routes/stream/get.js` — byte-range torrent file streaming (HTTP 206).
+  - `routes/api/playback-plan/post.js` — codec/container/duration probe result.
+  - `routes/transcode/session-file/get.js` — serves HLS playlist/segments;
+    long-polls while a segment is being produced, returns retryable 503 (never
+    202 — hls.js can't consume it).
+- `services/`:
+  - `demand/` — what anybody wants, in BYTES: `Window` (claimant, file, byte
+    range, urgency), `Urgency` (BLOCKED / NEAR / AHEAD / TAIL / BEHIND),
+    `DemandRegister` (live windows by claimant), `pieces.js` (the one place
+    bytes become piece numbers). No WebTorrent, no piece store, no pieces.
+  - `download/` — `SwarmSelection`, the ONLY thing that calls `select`,
+    `deselect` or `critical`, and `registry.js`, which holds one per torrent and
+    owns the cross-torrent rule that withholds the speculative levels while
+    anything urgent is missing anywhere. See `docs/download-architecture.md`.
+  - `container/` — domain layer: `Container` (abstract, RFC 9559 / ISO 14496-12),
+    `MatroskaContainer` / `Mp4Container` / `AviContainer`, `ContainerFactory`
+    (sniff 16 bytes → precise subclass). See `docs/container-architecture.md`.
+  - `tracks/` — domain layer: `ContainerTrack` (base: TrackNumber, declaredIndex,
+    language/BCP47, isEnabled/isDefault) → `VideoTrack` / `AudioTrack` /
+    `SubtitleTrack` → `TextSubtitleTrack` / `ImageSubtitleTrack`,
+    `ExternalSubtitleFile`. Spec-accurate flags (FlagForced only on subtitles per
+    RFC 9559 §5.1.4.1, FlagOriginal/Commentary only on audio, tkhd
+    track_enabled / alternate_group, elng BCP47).
+  - `orchestrators/` — application layer: `ContainerOrchestrator` (detect + per-file
+    cache, `getTracks`/`getKeyframeIndex`), `SubtitleOrchestrator` (wraps
+    `torrent-worker/subtitle-cues.js` + `Container` tracks, warm/push). The walk
+    itself is `MatroskaContainer.walkHeldClusters` / `Mp4Container.readHeldSamples`;
+    `subtitle-cues.js` supplies the torrent's read policy and keeps the cursor.
+  - `controllers/` — interface layer: `PlaybackController` / `SubtitleController`
+    (thin adapters over orchestrators; routes depend on controllers, not services).
+    `routes/*` are now thin HTTP translators.
+  - `container-index/` — what is not specific to one media kind: EBML element
+    walking and the Matroska/MP4/AVI keyframe tables. Used internally by
+    `container/*`, deprecated as a direct import. Everything a container states
+    about its own SUBTITLES — track table, Cues, blocks in a cluster, sample
+    table, the walk of what is downloaded — lives in the container class.
+  - `docs/download-architecture.md` — the two axes of downloading: what is
+    wanted (`demand/`) against what the swarm is told (`download/`), why urgency
+    is not a number given to the library, and why the speculative levels are
+    withdrawn rather than lowered.
+  - `docs/logs.md` — where to find logs (HA `docker logs` + `/data/proxy.log`, DO
+    `infra-server-1` with forwarded frontend `POST /api/client-logs`). Browser
+    console not needed.
+  - `playback-planner.js` — single ffmpeg probe returns audioCodec, videoCodec,
+    container, durationSeconds. `mode` is advisory; the browser decides.
+  - `hls-session-manager.js` — one ffmpeg per (source, file, settings). Serves a
+    synthetic full-duration VOD playlist; produces segments on demand; restarts
+    ffmpeg at the requested segment for server-side seeking. Short idle TTL.
+    Uses the detected `videoEncoder` for video re-encode (copy otherwise).
+  - `hwaccel.js` — detect best H.264 encoder (NVENC/QSV/VAAPI/V4L2M2M) with a
+    STRICT startup test: encode `testsrc2` through the real HLS pipeline, then
+    verify each segment decodes independently (catches non-IDR/corrupted hw
+    output). Falls back to software libx264. Runtime fallback to software if a
+    hw encode later fails. v4l2m2m is gated by this test (fails on HA Yellow).
+  - `data-channel-handler.js` — forwards WebRTC data-channel requests to the
+    local HTTP server (loopback), so the same routes serve both transports.
+
+## Gotchas
+
+- Do NOT use `-hls_playlist_type event` — it breaks duration/seek. VOD only.
+- A transitive dep (`ip-set`, via webtorrent) ships a hostile
+  `preinstall: npx only-allow pnpm` that breaks `npm install`. The addon works
+  around it with `--ignore-scripts` + a targeted rebuild of `node-datachannel`;
+  if you ever change install flow, keep that in mind.
+
+## Planned: public reachability (remote access)
+
+Decided direction — full plan in the parent `../CLAUDE.md`. Proxy-side pieces:
+
+- **Auto port mapping** — IMPLEMENTED (`services/port-mapper.js`, changelog
+  2.9.16). UPnP IGD / NAT-PMP via `@silentbot1/nat-api` (now a direct dep; the
+  same lib WebTorrent uses for the torrent port). Maps TCP 9090 with a 2 h
+  auto-renewed lease, removed on shutdown (lease expiry covers hard kills).
+  Best-effort + start/stop timeouts; `--no-port-mapping` opts out;
+  `getMappedEndpoint()` exposes the external endpoint. NOT yet done: mapping the
+  **UDP** port WebRTC actually uses (it binds ephemeral UDP ports, so this TCP
+  mapping does not yet help WebRTC — roadmap step 3 in the parent CLAUDE.md).
+  Also pending (next iteration): a success log line in `port-mapper.js` `stop()`
+  (`removed mapping for TCP <port>`) — today stop() only logs on failure, so a
+  clean unmap on shutdown is silent.
+- **Report endpoint to server** — ✅ DONE (proxy 2.9.17). The mapped endpoint
+  is sent over the tunnel (`tunnel-client.sendEndpoint` → `proxy-endpoint`) on
+  mapping success and on every tunnel (re)connect; the server dial-back-verifies
+  reachability (server 0.8.22, roadmap step 2).
+- **HTTPS listener**: serve the existing routes over TLS with a per-proxy
+  certificate delivered by the server through the tunnel (persist cert+key
+  locally; ~90-day renewals are pushed the same way). Add CORS headers for the
+  web-app origin so hls.js / `<video>` can fetch cross-origin.
+- Plain HTTPS becomes the preferred video transport; WebRTC data channel stays
+  as fallback for hosts where no port could be opened.
+- **Later roadmap steps** (single staged roadmap in parent `../CLAUDE.md`,
+  WebRTC-first ordering): step 3 map the WebRTC UDP port (fixed
+  `portRangeBegin`/`End` + UPnP-map UDP); step 4 birthday-paradox port
+  prediction (open ~256 UDP sockets, inject predicted-port ICE candidates) for
+  symmetric NAT; step 5 IPv6-first (audit the candidate filter — do not drop
+  *global* v6) + STUN NAT pre-classification reported to the registry; then
+  the DNS+TLS path (steps 6–7); step 8 relay-then-upgrade (deferred).
+- Future: ed25519 proxy identity (sign announcements), BEP 44 endpoint
+  announcements via the `bittorrent-dht` already bundled with WebTorrent.
+
+All of this must stay deployment-agnostic (HA addon, bare npm, Docker).
+
+## Disk hygiene (open item — torrent data is NOT cleaned up today)
+
+HLS segments are handled (`hls-session-manager.js`: idle TTL, `disposeSession`,
+`disposeAll`). Torrent data is **partially** handled: shutdown cleanup is done
+(`TorrentPool.destroyAll()` with `destroyStore: true`, wired into the `onClose`
+hook — proxy 2.9.15), but `deselect()` only stops further download and nothing
+removes a torrent's data **while the proxy keeps running**, nor sweeps orphans
+left by a previous hard kill at startup.
+
+Level 1 — remaining: `client.remove(torrent, { destroyStore: true })` on last-
+file refcount 0 + idle TTL (mirror the HLS session model); startup sweep of
+orphaned store dirs under `os.tmpdir()`; global disk cap with LRU eviction of
+whole torrents. (Shutdown teardown ✅ done.)
+Level 2 (research): sliding-window chunk store. Full rationale in the parent
+`../CLAUDE.md` "Disk hygiene" section.
+
+## Cloud proxy
+
+The same proxy code also runs as the company-hosted fallback when the user
+pool can't serve a viewer. Keep the proxy host-agnostic so it runs unchanged on
+rented infra (flat-rate/unmetered bandwidth — Hetzner dedicated / OVH; NOT
+metered-egress clouds). Provider/economics analysis in the parent
+`../CLAUDE.md` "Cloud proxy" section.
+
+## Changelog
+
+Every behavioural change must be recorded in `CHANGELOG.md` — add an entry under
+a new `## <version>` heading at the top, following the existing
+`- **New**/**Fix**/**Chore**:` format.
+
+**Do NOT edit `package.json` version.** `npm run patch`/`minor` runs `npm
+version …` which bumps it. Write the CHANGELOG entry at the version that bump
+will produce: **current `package.json` version + 1 patch** (or + 1 minor).
+Accumulate bullets into that single pending entry until it's published. See the
+parent `../CLAUDE.md`.
+
+## Release
+
+`npm run patch` (publishes to npm + pushes tags). The HA addon then needs its
+own version bump to pull the new package. Publish proxy BEFORE bumping the addon.
+
+**Any proxy change requires bumping the ha-addon version** (`ha-addon/torrent_tv_proxy/config.yaml`). The addon installs the proxy from npm at build time and the build is cached; without a version bump the plugin will NOT update and keeps running the old proxy. So after `npm run patch`, always bump the addon `config.yaml` version, push, and update the addon.