@torrent-tv/proxy 2.89.16 → 2.89.18

package/docs/encode-run-state.md

@@ -1,96 +0,0 @@
-<!-- GENERATED from services/encode/encode-run-state.js by scripts/render-run-graph.js.
-     Do not edit by hand: change the table and run `npm run graph`. -->
-
-# The encoder run — states and transitions
-
-One run of one ffmpeg inside one transcode session. The table this is drawn
-from is executed by `services/encode/EncodeRuns.js`; every transition a real
-run makes is logged as state, event and target, so a run that takes an edge
-absent here is a violation the log names.
-
-```mermaid
-stateDiagram-v2
-    state RUN {
-        [*] --> IDLE
-        state WORKING {
-            state ALIVE {
-                STARTING
-                PRODUCING
-                SUSPENDED
-            }
-            RETRY_WAIT
-        }
-        IDLE
-        STOPPED
-        ENDED_COMPLETE
-        ENDED_FAILED
-    }
-
-    RUN --> STARTING : SPAWNED
-    WORKING --> STOPPED : STOP_ORDERED
-    ALIVE --> SUSPENDED : SUSPEND_ORDERED
-    ALIVE --> ENDED_COMPLETE : EXITED_COMPLETE
-    ALIVE --> ENDED_FAILED : EXITED_SHORT
-    ALIVE --> RETRY_WAIT : EXITED_INPUT_LOST
-    ALIVE --> ENDED_FAILED : EXITED_FAILED
-    STARTING --> PRODUCING : FIRST_SEGMENT
-    SUSPENDED --> PRODUCING : RESUME_ORDERED
-    RETRY_WAIT --> IDLE : RETRY_DUE
-```
-
-## States
-
-| state | means |
-|---|---|
-| `IDLE` | No process, and one is expected — before the first run, or after a retry timer fired. |
-| `STARTING` | Spawned; this run has produced nothing servable yet. |
-| `PRODUCING` | This run has produced at least one servable segment. |
-| `SUSPENDED` | SIGSTOP delivered, process alive — and nothing is reading the input. |
-| `RETRY_WAIT` | The input went away; a restart is timed. Requests are held, not refused. |
-| `STOPPED` | Stopped on purpose with no replacement — a rung the viewer switched away from. |
-| `ENDED_COMPLETE` | Ran through the last segment of the file. Nothing is owed. |
-| `ENDED_FAILED` | Terminal for this target: requests are answered as failures. |
-
-## Events
-
-| event | means |
-|---|---|
-| `SPAWNED` | A process was spawned for this session. |
-| `FIRST_SEGMENT` | The first servable segment of this run was served. |
-| `SUSPEND_ORDERED` | SIGSTOP was delivered. |
-| `RESUME_ORDERED` | SIGCONT was sent. |
-| `STOP_ORDERED` | The run was stopped with no replacement. |
-| `EXITED_COMPLETE` | Exit 0, having produced through the last segment. |
-| `EXITED_SHORT` | Exit 0, short of the last segment — the input dried up. |
-| `EXITED_INPUT_LOST` | Died because the input was not there. Recoverable. |
-| `EXITED_FAILED` | Died for any other reason, or could not be spawned. |
-| `RETRY_DUE` | The input-retry timer fired. |
-
-## What each state answers
-
-Outputs depend on the state alone — computed here by calling the same
-functions the session manager calls.
-
-| state | reads its input | can be signalled | a missing segment | on the wire | may restart |
-|---|---|---|---|---|---|
-| `IDLE` | no | no | hold | `starting` | yes |
-| `STARTING` | yes | yes | hold | `running` | yes |
-| `PRODUCING` | yes | yes | hold | `running` | yes |
-| `SUSPENDED` | no | yes | hold | `running` | yes |
-| `RETRY_WAIT` | no | no | hold | `starting` | yes |
-| `STOPPED` | no | no | hold | `running` | yes |
-| `ENDED_COMPLETE` | no | no | hold | `ready` | no |
-| `ENDED_FAILED` | no | no | fail | `failed` | yes |
-
-## Edges that must never exist
-
-The machine's real content: a near-complete digraph asserts nothing.
-
-| from | event | must not reach | because |
-|---|---|---|---|
-| `SUSPENDED` | `FIRST_SEGMENT` | `PRODUCING` | a segment request must not release a suspended encoder — 2.9.93, where any request did, and the run sawtoothed from 155 s to 922 s ahead of the viewer in three minutes |
-| `ENDED_FAILED` | `FIRST_SEGMENT` | `PRODUCING` | a dead run is not a producing one — 2.9.93, where the handle pointed at a corpse and every later seek was waved through as already covered, so the session answered 500 for ever |
-| `ENDED_FAILED` | `RESUME_ORDERED` | `PRODUCING` | there is no process to continue; only a spawn leads out of a failure |
-| `IDLE` | `FIRST_SEGMENT` | `PRODUCING` | nothing produces before a process exists |
-| `RETRY_WAIT` | `FIRST_SEGMENT` | `PRODUCING` | a run waiting for its input back has no process; only a spawn resumes production |
-| `STOPPED` | `RESUME_ORDERED` | `PRODUCING` | a rung the viewer switched away from must not be revived by its own held requests — the host has one encoder's worth of capacity and the rung on screen needs it |

package/docs/logs.md

@@ -1,138 +0,0 @@
-# Logs — where to look
-
-No browser console copy-paste is needed: the page forwards its own log. But it
-lands in TWO places depending on the phase of the session — the registry server
-and the proxy — see "Browser logs are in TWO places" below before concluding
-anything from a half-session.
-
-## Where the proxy writes its log, by how it is started
-
-The proxy is deployment-agnostic: the Home Assistant addon is one way to run it,
-npm and Docker on Linux, macOS or Windows are others. Where its log goes is
-decided by one start parameter, `--log-file <path>`, and nothing else:
-
-- **With `--log-file`**: every line goes to the console AND to that file
-  (appended, rotated to `<path>.1` past 1 GiB), and the browser's lines go to
-  one file per viewing session in the same directory (see "The files on the
-  proxy" below). The directory of the file must exist.
-- **Without it**: everything goes to the console only, the browser's lines
-  included, each prefixed `client <sessionId:8>`. Before torrent-tv/meta#96 the
-  browser's lines were dropped in this case. The console is kept by whatever
-  started the process, and only as long as that keeps it.
-
-| How it is started | Log | Browser lines | Survives |
-|---|---|---|---|
-| Home Assistant addon | `/data/proxy.log` (`run.sh` passes `--log-file /data/proxy.log`) | `/data/client-*.log` | restarts and addon updates |
-| npm / `npx`, any OS, no `--log-file` | the terminal | the terminal | nothing |
-| npm under systemd, no `--log-file` | the unit's journal: `journalctl -u <unit>` | the same journal | restarts, within journald's limits |
-| npm with `--log-file`, e.g. `/var/log/torrent-tv-proxy/proxy.log`, `~/Library/Logs/torrent-tv/proxy.log`, `%LOCALAPPDATA%\torrent-tv\proxy.log` | that file | `client-*.log` beside it | restarts and updates |
-| Docker, no `--log-file` | `docker logs <container>` | the same | only the container's life: recreating it deletes the log |
-| Docker with a volume and `--log-file`, e.g. `-v ttv-proxy-logs:/logs … --log-file /logs/proxy.log` | the file in the volume | `client-*.log` in the volume | recreating the container |
-
-So on any host where the log matters, pass `--log-file` and point it at a
-directory that outlives the process — which is what the addon does.
-
-## HA proxy (aarch64, addon `b34a1737_torrent_tv_proxy`)
-
-Image `b34a1737/aarch64-addon-torrent_tv_proxy:<version>` = `@torrent-tv/proxy` `<version>` (see `ha-addon/torrent_tv_proxy/config.yaml`).
-
-- Console + file are the same: the proxy logs to both `stdout` and `/data/proxy.log` on start (`logging to /data/proxy.log as well as the console`).
-- **Since 2.71.0 that is true of the torrent thread too, and it was not before.**
-  A worker thread loads its own instance of every module, so the logger's file
-  handle — set once, on the main thread — was null in the worker for the life of
-  the process. Measured over a whole 49 938-line file: zero lines from the piece
-  reader (`read "…"`, `supply "…"`, every wait and its cause) and zero from the
-  torrent pool, against 52 and 36 of them in `docker logs`, which every release
-  destroys. The worker now sends its lines to the main thread, which is the only
-  writer; a line from there reads `torrent-worker: …`.
-- Via container:
-  ```bash
-  ssh ha "sudo docker logs app_b34a1737_torrent_tv_proxy --tail 200"
-  ssh ha "sudo docker exec app_b34a1737_torrent_tv_proxy cat /data/proxy.log | tail -n 300"
-  ```
-- Filter by session: every transcode session logs its id, e.g. `003ed2fd-7c9b-4cd5-9d05-ff875ff2be23`, `hold segment-00068.mp4 failed`, `encode-run failed`, `EXITED_*`.
-- Host file `/data/proxy.log` survives `docker logs` rotation; `core dumps: 1 present` line shows kept dump under `/data`.
-
-SSH to HA requires `MACs hmac-sha2-256-etm@openssh.com,hmac-sha2-512-etm@openssh.com,umac-128-etm@openssh.com` — server `OpenSSH_10.3` on `homeassistant.local` offers only `*-etm` (`Unable to negotiate` / `Corrupted MAC` otherwise). Already in `~/.ssh/config` `Host ha`.
-
-## DO server (webauth.courses, `infra-server-1`)
-
-- Server is `infra-server-1` (`ghcr.io/torrent-tv/server`) on `do` (`206.189.97.152`).
-- Every container there logs to the host journal, and rsyslog writes one file per
-  source to `/var/log/torrent-tv/`; the files and the journal survive the
-  deployments that recreate the containers (`infra` README, "Logs";
-  torrent-tv/meta#96):
-  - `server.log` — the server's own lines;
-  - `client.log` — browser lines the server received, prefixed
-    `[client <tag> <id> sig=<webrtcSessionId>]`
-    (`server/routes/api/client-logs/post.js`);
-  - `nginx.log`, `doco-cd.log`.
-- Frontend logs reach the droplet only in the phases the proxy cannot be reached
-  in — see "Browser logs are in TWO places" below.
-- Reading:
-  ```bash
-  ssh do "tail -n 300 /var/log/torrent-tv/client.log"
-  # filter a single viewing:
-  ssh do "grep 003ed2fd /var/log/torrent-tv/client.log /var/log/torrent-tv/server.log"
-  ssh do "journalctl -t torrent-tv-server --since '-1h' -o short-iso-precise"
-  ```
-- `docker logs infra-server-1` shows only the CURRENT container's lines — a
-  deployment gives it a new container. Use the files or `journalctl -t`.
-- No need to open eruda or copy the browser console on a phone — it is forwarded.
-
-## Browser logs are in TWO places, split by phase — read both
-
-Until 2026-09-13 the page's whole log went to the droplet's standard output,
-which every release of the server destroys. A viewer reported a desync and a
-frozen picture that day and the analysis ran on half the evidence, so the log
-moved to the proxy — beside the proxy's own, on the same durable directory.
-
-The split is by PHASE, and neither half is the whole session:
-
-1. **Before a transport exists** — the page opening, the proxy being chosen, a
-   connection failing — there is nowhere else to send it, so it goes to the
-   SERVER (`/var/log/torrent-tv/client.log` on the droplet);
-2. **From the moment the data channel is up**, the page's logger is given a
-   proxy sink (`loading.js`, `setProxySink`) and every batch goes to the PROXY
-   over that channel. This is the bulk of a viewing;
-3. **At unload** it goes to the server again: `navigator.sendBeacon` is the only
-   thing a page that is going away can use, and a data channel is not;
-4. **A batch that cannot reach the proxy** falls back to the server.
-
-So a session that failed while connecting is on the droplet, a session that
-failed while playing is on the addon host, and a complete reading of a long
-failure needs both.
-
-### The files on the proxy
-
-When the proxy was started with `--log-file`: one file per viewing session, in
-the proxy log's own directory (`/data` on the addon host), named so the two
-halves join without guessing. Without `--log-file` the same lines are in the
-proxy's console, prefixed `client <sessionId:8>`.
-
-```
-client-<YYYYMMDD-HHMMSS UTC of the session start>-<sessionId:8>-<torrent name:60>-<infoHash:8>.log
-```
-
-A session that has not chosen a torrent yet writes `no-torrent-yet` in that
-last part — the file is keyed by the session id, not by the name, so choosing a
-torrent later does NOT start a second file. Rotated at 16 MB to `<name>.log.1`.
-
-```bash
-ssh ha "sudo docker exec app_b34a1737_torrent_tv_proxy sh -c 'ls -la /data/client-*.log'"
-ssh ha "sudo docker exec app_b34a1737_torrent_tv_proxy sh -c 'cat /data/client-20260913-*.log'"
-```
-
-Implementation: `utils/client-log-file.js`, route `routes/api/client-logs/post.js`.
-
-## Quick triage
-
-- Rewind/seek bug (hold 0ms → 500): HA `hold ... failed after 0ms → 500` + `encode-run` lines for the same `<sessionId>`, and DO `client.log` `[client ...] fragLoadError / levelLoadError 500` for same `sn`.
-- Cushion / link budget: HA `memory: rss=... anon=...` and `cushion` lines; DO `[eta]` / `[cushion]` from client.
-- Update check: `ssh ha "sudo docker exec hassio_cli ha apps info b34a1737_torrent_tv_proxy | grep version"` and `ssh ha "sudo docker ps --filter name=app_b34a1737_torrent_tv_proxy"`.
-
-## Related
-
-- `ha-addon/CLAUDE.md` — addon build/update detour via `hassio_cli`, cache-bust via `config.yaml` version.
-- `docs/container-architecture.md` — what container/track classes log and where.
-- `routes/api/client-logs/post.js` and `server/routes/api/client-logs/post.js` — the two receivers; both sanitize the same way (control chars → space, `MAX_LINES`, `MAX_MSG_LEN`).

package/docs/playback-start-forecast.md

@@ -1,113 +0,0 @@
-# Playback start forecast
-
-For resource r, measured service is S_r(t) = rate_r * t. New observations
-replace the conditional future rate; polling cannot invent acceleration,
-exponential recovery or a new physical measurement.
-
-Source work uses the file's measured byte density, missing local byte ranges
-and the observed torrent download rate. Shared input ranges are downloaded
-once. Files on the same torrent share a queue; distinct torrents use distinct
-observed services. Local input reading is included in effective processing
-speed, rather than charged again as a separate disk or memory delay.
-
-Each output's remaining processing work subtracts progress only within its
-actual live run intervals. Initial video rates use existing codec/size/encoder
-calibration. Initial audio rates use short packaged per-codec measurements and
-sample work (encoding) or encoded bytes (copying). Actual output progress
-replaces these initial rates. That rate is the run's processing speed: film
-made over the run's own working time, with the time its input waited for the
-swarm and the time it was stopped taken out (`RunClock`, fed by the stream
-route, which marks each wait of a run's input read). The download is charged
-once, by the source service, and not a second time inside the processing rate. Startup is charged once, separately from processing
-throughput, and disappears once actual run progress establishes processing.
-
-Input arrival and processing overlap. With arrival time D(m), processing rate
-e and previous completion C, completion for an interval [a,b] is
-
-    max(C + (b-a)/e, sup_m(D(m) + (b-m)/e)).
-
-Between service boundaries these functions are linear, so only endpoints are
-needed. Client delivery follows production and shares the observed link queue.
-Measured client ranges and prepared media establish each track's deadlines.
-
-The minimum start delay for this conditional trajectory is
-
-    max(0, max_j(completion_j - presentation_deadline_j)).
-
-This covers the remaining finite movie, including rates below real time. Slow
-positive service gives a finite preproduction delay; it is not rejected by a
-browser-capacity threshold or a capped search. Observed supply-interruption
-coverage is held in prepared proxy media and client media, without requiring
-the browser to hold it all.
-
-Critical review: future rates can change, average byte density is an initial
-mapping rather than an exact packet index, initial audio sample-work scaling
-does not model every decoder's nonlinear cost, and client receive/append time
-is not separately measured. These are approximation limits, not hidden weights.
-Actual progress, segment sizes and link observations refine the prediction.
-The client countdown uses elapsed local monotonic time; expiration cannot
-authorize playback. Only the proxy's readiness and real track coverage can.
-
-Zero service, missing media facts and a genuine timestamp gap remain explicit
-noncomputable states. The UI reports their causes instead of an estimating
-placeholder or a fabricated duration.
-
-## Continuity is decided in exact time
-
-The forecast lives in the viewer component (`services/viewer/`), because what
-it predicts is how the viewer's browser will play; the request operation
-(`ViewerRequests`) is handed it by `wire-outputs.js`.
-
-1. **The file states integers.** A piece's media is read as presentation
-   intervals in the integer ticks of each track's timescale
-   (`readPresentationRanges`, `services/encode/segment-formats/mp4-boxes.js`).
-   Intervals are joined there only where they touch or overlap; the format
-   states what the samples say and nothing about browsers.
-2. **One function places a piece.** The position written into `tfdt` when a
-   piece is served and the position its coverage is read at both come from
-   `readTrackEdits`, which converts the movie-timescale edit into track ticks
-   with one stated rounding. The reader and the writer cannot disagree.
-3. **Seconds from the page are exact fractions.** A buffered range, a position
-   or a cut time arrives as a JavaScript number, which is a binary fraction;
-   `services/viewer/media-time.js` converts it to that fraction exactly. No unit
-   is chosen. A buffered range is widened by `REPORTED_TIME_ERROR`, the bound of
-   Chromium's three truncations to whole microseconds, so that it denotes every
-   exact time the report can stand for.
-4. **The join rule holds in every engine.** The Media Source specification
-   leaves the threshold to the implementation, so a gap counts as joined only
-   when Chromium, Gecko and WebKit all join it: twice the gap within the two
-   ranges' longest frames since a keyframe (Gecko's fuzz), and the gap within
-   2002/24000 s (WebKit's `timeFudgeFactor`). Chromium's own bound follows from
-   the first. Old iOS without Media Source plays HLS in a closed player, and
-   nothing is derived for it.
-
-Seconds appear again only for rates, schedules and the answer.
-
-## A piece is finished when its frames reach its cut
-
-A closed non-final fragment is reusable only if the end of its last frame, on
-every track, reaches its muxer's cut less `SEGMENT_CUT_TIME_DELTA_SECONDS`,
-the delta the muxer is configured with. That is a fact of production, so no
-browser frame allowance is used to decide completeness. For explicit cuts the
-closure channel is CSV: its reference packet end has not lost the fraction of
-a movie tick that MP4's empty edit loses. The first reference packet's time is
-recovered from that end minus the first piece's exact sample span (the first
-CSV start is zero even after a seek), and is added to the relative cut times
-handed to FFmpeg. Comparisons use integer microseconds, as FFmpeg's segment
-muxer does. A stored piece without this closure reading carries the upper
-uncertainty of its empty edit, read from the movie and track timescales.
-
-The last frame must still reach the cut on every track. No playable media, a
-missing full frame, or a failed rename remains a publication failure. Such a
-failure stops the run, records that cause and releases its claimed interval;
-the existing repeated-start failure limit applies to subsequent attempts. A
-refused file cannot stay claimed while the encoder finishes the whole film.
-
-The encoding decides completeness
-(`encode/piece-completeness.js`): `EncodeRuns` judges a closed file before it is
-published, and judges a stored piece left by an earlier process when the
-forecast asks for it, taking a short one off the disk. The segment store keeps
-the bytes and the media intervals read from them and judges nothing. Interrupted
-fragments are therefore never served or counted, so the production schedule
-treats their media as unfinished work. The final fragment uses its actual media
-end rather than the container's approximate duration.

package/docs/socks5-egress-research.md

@@ -1,114 +0,0 @@
-# SOCKS5 torrent egress — feasibility research (NOT implemented)
-
-Research only (2026-07-10), no code. Question: can the proxy route its
-**torrent** traffic (peers, trackers, DHT) through an owner-configured SOCKS5
-endpoint (e.g. a VPN provider's) to hide the owner's home IP from the swarm,
-while WebRTC to the viewer stays direct? Roadmap item 8 in the root
-`CLAUDE.md`.
-
-Stack: WebTorrent 2.8.5, Node. Verified against
-`node_modules/webtorrent/lib/*.js` and `index.js`.
-
-## What "torrent traffic" actually is (and which parts can be SOCKS5'd)
-
-SOCKS5 forwards a connection through a relay so the destination sees the
-relay's IP, not ours. It supports TCP (CONNECT) and, in theory, UDP (UDP
-ASSOCIATE) — but UDP-ASSOCIATE is rarely usable from Node libraries that bind
-their own UDP sockets. So per traffic type:
-
-| Traffic | Transport | Where in WebTorrent | SOCKS5? |
-|---|---|---|---|
-| Peer wire (outgoing) | TCP | `torrent.js` `net.connect(opts)` (~L2112) | **Yes** (TCP CONNECT) |
-| Peer wire (outgoing) | µTP (UDP) | `torrent.js` `utp.connect()` (~L2110) | No (UDP, own socket) → **disable** |
-| HTTP/HTTPS trackers | TCP | `bittorrent-tracker` (HTTP agent) | **Yes** (agent) |
-| WSS trackers | TCP (WebSocket) | `bittorrent-tracker` (ws agent) | **Yes** (agent) |
-| UDP trackers (`udp://`) | UDP | `bittorrent-tracker` | No → **drop** (filter announce list) |
-| DHT | UDP | `bittorrent-dht` | No → **disable** (`dht:false`) |
-| LSD (local peer discovery) | UDP multicast | conn-pool | LAN-only leak → **disable** (`lsd:false`) |
-| Incoming peers | TCP/µTP listener | conn-pool | N/A (inbound; see note) |
-
-Conclusion: a clean, leak-free config is **TCP-only through the SOCKS5 relay**
-with every UDP path turned OFF. This is the standard "torrent proxy" model and
-its standard caveat: you lose µTP peers, UDP trackers, and DHT peer discovery —
-peer counts drop, but HTTP/WSS-tracker swarms (like the rutracker trackers our
-test torrents use) still work, and TCP peers are plentiful.
-
-WebTorrent already exposes the needed off-switches (verified in `index.js`):
-`utp: false` (L82), `dht: false` (L127), `lsd: false` (L76), `webSeeds`
-(L161). Announce-list filtering to `http(s)://`/`wss://` is ours to do.
-
-## The hard part: no dialer hook for TCP peers
-
-WebTorrent has **no public option** to supply a custom socket/dialer for
-outgoing peer connections — it calls `net.connect(opts)` directly inside
-`torrent.js`. Three ways around it:
-
-### Approach A — userland, scoped monkeypatch of `net.connect` (+ disable UDP)
-Wrap `net.connect` so that for a **peer destination** it returns a socket
-tunneled through SOCKS5 (via the already-present `socks` package —
-`SocksClient.createConnection({ proxy, command:'connect', destination })`),
-and for everything else (our loopback HTTP server, the signalling tunnel,
-ffmpeg's `127.0.0.1` fetch, DNS) it calls the real `net.connect`.
-- The `socks` dep is ALREADY in `node_modules` (currently transitive) — would
-  become a direct dependency.
-- Shim detail: `net.connect` returns a socket synchronously and connects
-  async; `SocksClient.createConnection` is Promise-based. Need a small adapter
-  that returns a `net.Socket`-like duplex immediately and attaches the real
-  tunneled socket once the SOCKS handshake resolves (or emits `error`). The
-  `socks` package's event API supports this.
-- Scoping rule: SOCKS only for non-local IPv4/IPv6 destinations; NEVER for
-  `127.0.0.1`/`::1`/the tunnel host — otherwise we'd route our own control
-  plane through the VPN.
-- Trackers/webseeds (HTTP/WSS): pass a `socks-proxy-agent` as the HTTP/ws
-  agent to `bittorrent-tracker` / webseed fetches (need to confirm WebTorrent
-  threads an `agent` option through; may need a small patch).
-- Pros: no fork, no build-chain changes, deployment-agnostic. Cons: global
-  monkeypatch is delicate; must be airtight on the scoping rule.
-
-### Approach B — patch/fork WebTorrent to add a `createConnection` hook
-Add an option so `torrent.js` uses `opts.createConnection ?? net.connect`.
-Cleaner and explicit, but a fork to maintain (or an upstream PR — issue
-webtorrent#807 "SOCKS Proxy Support" is open and unresolved, so upstream is
-unlikely soon). More correct long-term if A proves too fragile.
-
-### Approach C — network-level (VPN container / namespace), NOT in-proxy
-Run the whole proxy process behind a VPN with a kill-switch (e.g. a `gluetun`
-sidecar container, or a Linux network namespace bound to the VPN). Catches
-ALL traffic — TCP, µTP, DHT, UDP trackers — leak-proof, zero proxy code.
-Trade-off: not per-app (the whole proxy egresses via VPN, including the
-signalling tunnel unless split), heavier ops, and awkward for the HA addon
-(`host_network: true`). This is the ROBUST alternative to document alongside;
-for a bare-Docker/npm operator it may actually be the better answer than
-in-proxy SOCKS5.
-
-## Kill-switch (fail-closed) — mandatory for the feature to mean anything
-If the SOCKS5 relay is down, torrent traffic must NOT silently fall back to a
-direct connection (that leaks the exact IP we set out to hide). With Approach
-A this is natural: a failed SOCKS handshake fails the peer connection with no
-direct retry, AND all UDP paths are already disabled, so nothing bypasses the
-relay. Must add a startup connectivity self-test + a clear log line
-(BitPlay's "test proxy" pattern), and surface "proxy down → torrent paused"
-rather than leaking.
-
-## Recommended direction (when we build it)
-1. Primary: **Approach A** — `socks` for TCP peers via a scoped `net.connect`
-   shim + `socks-proxy-agent` for HTTP/WSS trackers + webseeds, with
-   `utp:false`, `dht:false`, `lsd:false`, and announce-list filtered to
-   TCP-based trackers. Fail-closed by construction.
-2. Document **Approach C** (VPN container) in the addon/deployment docs as the
-   leak-proof alternative for operators who prefer it.
-3. Approach B only if A's monkeypatch proves too fragile in practice.
-
-## Open questions to resolve at build time (not now)
-- Does WebTorrent 2.8.x thread an `agent`/proxy option to `bittorrent-tracker`
-  and webseed fetches, or is a small patch needed there too?
-- `socks` socket-shim: cleanest way to present a pre-connect `net.Socket`
-  (custom Duplex vs a paused real socket) without confusing
-  `bittorrent-protocol`'s wire setup.
-- Incoming peers: with UDP off and outbound via SOCKS, do we still accept
-  inbound TCP peers directly (that inbound listener exposes the home IP to
-  connecting peers)? For full hiding, inbound may need to be disabled too
-  (accept that peer discovery becomes outbound-only) — decide per privacy goal.
-- Interaction with the UPnP port mapping / WebRTC UDP port (those are for the
-  viewer transport, NOT torrent egress — must stay direct; confirm the shim's
-  scoping never touches them).