@torrent-tv/proxy 2.87.10 → 2.87.12

package/docs/encode-run-state.md

@@ -1,96 +1,96 @@
-<!-- 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 encoding component (`EncodeRuns`) 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 |
+<!-- 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 encoding component (`EncodeRuns`) 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,97 +1,97 @@
-# 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, and `docker logs` is
-only one of them — see "Browser logs are in TWO places" below before concluding
-anything from a half-session.
-
-## 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:latest`) on `do` (`206.189.97.152`).
-- Frontend logs reach here only in the phases the proxy cannot be reached in — see "Browser logs are in TWO places" below. When they do, the server `console.log`s them with the prefix `[client <tag> <id> sig=<webrtcSessionId>]` (`server/routes/api/client-logs/post.js`), in the same container as its own lines.
-- Via container:
-  ```bash
-  ssh do "docker logs infra-server-1 --tail 200 | cat"
-  # filter a single viewing:
-  ssh do "docker logs infra-server-1 --tail 500 | grep 003ed2fd"
-  ssh do "docker logs infra-server-1 --tail 500 | grep '\[client'"
-  ```
-- 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 (`infra-server-1`);
-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
-
-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:
-
-```
-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 ...] 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`).
+# 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, and `docker logs` is
+only one of them — see "Browser logs are in TWO places" below before concluding
+anything from a half-session.
+
+## 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:latest`) on `do` (`206.189.97.152`).
+- Frontend logs reach here only in the phases the proxy cannot be reached in — see "Browser logs are in TWO places" below. When they do, the server `console.log`s them with the prefix `[client <tag> <id> sig=<webrtcSessionId>]` (`server/routes/api/client-logs/post.js`), in the same container as its own lines.
+- Via container:
+  ```bash
+  ssh do "docker logs infra-server-1 --tail 200 | cat"
+  # filter a single viewing:
+  ssh do "docker logs infra-server-1 --tail 500 | grep 003ed2fd"
+  ssh do "docker logs infra-server-1 --tail 500 | grep '\[client'"
+  ```
+- 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 (`infra-server-1`);
+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
+
+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:
+
+```
+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 ...] 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/socks5-egress-research.md

@@ -1,114 +1,114 @@
-# 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).
+# 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).