@torrent-tv/proxy 2.80.10 → 2.80.12

package/CLAUDE.md

@@ -72,6 +72,12 @@ Linux-only host (e.g. POSIX-only signals must degrade elsewhere).
     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/encode-architecture.md` — who decides where encoders go, and the
+    answer is one authority: `EncodePlan`, from what is made, what is being
+    made, what is wanted and what the host can hold. Why no viewer reaches it,
+    why the priority map is read at two scopes (per FILE for the swarm, per
+    OUTPUT for the encoders), and what each of the eight other places that used
+    to place or kill an encoder now states instead.
   - `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.

package/docs/download-architecture.md

@@ -37,10 +37,12 @@ flowchart TB
   end
 
   subgraph Claimants["who states needs"]
-    PR[piece-reader<br/>four bands per read]
+    PM[priority map<br/>where the viewers are, per FILE]
+    PR[piece-reader<br/>the piece it is stopped on]
     BF[torrent-pool<br/>background fill, per file]
   end
 
+  PM -->|state / withdraw| R
   PR -->|state / withdraw| R
   BF -->|state / withdraw| R
   W --> R
@@ -51,6 +53,25 @@ flowchart TB
   S -->|the only caller| WT[(WebTorrent)]
 ```
 
+## Who the claimants are, and what each of them knows
+
+**The priority map** states what should be downloaded AHEAD of the viewers, once
+per file, built in `services/priority/` from where they are and from nothing
+else. It is the same map the encoding reads — the encoding reads it per OUTPUT
+and in segment numbers, this layer reads it per FILE and in bytes, and both
+scopes are right for what asks them (`encode-architecture.md`).
+
+**A read** states only the piece it is STOPPED ON. That is not a forecast but the
+fact that somebody is waiting there, and it is what keeps working for the reads
+the viewers' map does not cover: a container header at open, the subtitle walk, a
+soundtrack being fetched whole. Until 2026-09-02 each read built four bands
+around its own head instead, so fifteen reads were fifteen forecasts on a store
+holding sixteen pieces, half of all evictions took a piece a reader had said it
+wanted, and two thirds of reads came back from disk.
+
+**The background fill** states one file at a time — a soundtrack pulled whole
+once the cushion is full, and no further.
+
 ## The five levels
 
 | level | what it is | stated |

package/docs/encode-architecture.md

@@ -0,0 +1,150 @@
+# Encode architecture — who decides where encoders go
+
+One question, one answer, and the answer is arithmetic.
+
+> Viewers are always independent and always reuse what can be reused. The
+> number of encoders is however many are needed; how many are needed follows
+> from which sets of output parameters are wanted and where the viewers stand
+> inside each. Segments produced by ANY encoder are available to ANY viewer, and
+> which viewer asked never enters the question.
+
+## The one authority
+
+`services/encode/EncodePlan.js` decides. Nothing else places an encoder,
+nothing else takes one away for scheduling reasons, and there is exactly one
+call to `#startEncodeRun` in the whole proxy — the one the plan asks through.
+
+It decides from four things and no others:
+
+| what | where it comes from |
+|---|---|
+| what is already made | the segment store, asked afresh before every decision |
+| what is being made | the coverage map's live claims |
+| what is wanted | the priority map of that output |
+| how many the machine can hold | `run-budget.js`, from measurements of this host |
+
+**No viewer reaches it.** `services/encode/` and
+`services/orchestrators/EncodeOrchestrator.js` do not import the viewer layer,
+name a consumer id, or hold a person. What crosses is a priority map: zones of
+segment numbers with a rank and a real time, and nobody's name on it.
+
+## Viewers become a map, and that is the whole crossing
+
+```mermaid
+flowchart TB
+  subgraph V["services/viewer — where people are"]
+    VW[Viewer<br/>position, playing, buffered, chosen track]
+    VS[Viewers<br/>the relation, indexed from both ends]
+  end
+
+  subgraph P["services/priority — one fact, two scopes"]
+    PM[PriorityMap<br/>seconds of film to a rank]
+    PO[PriorityOrchestrator<br/>merge, publish, keep]
+  end
+
+  subgraph E["services/encode — where encoders go"]
+    CM[CoverageMap<br/>ready / making / free]
+    EP[EncodePlan<br/>argmin over arrangements]
+    RB[run-budget<br/>what this host can hold]
+    ER[EncodeRun<br/>one process, one interval]
+  end
+
+  subgraph D["services/demand + download — what the swarm is told"]
+    DR[DemandRegister]
+    SS[SwarmSelection]
+  end
+
+  VW --> VS
+  VS -->|"positions, presence"| PO
+  PM --> PO
+  PO -->|"per FILE, in bytes"| DR
+  DR --> SS
+  PO -->|"per OUTPUT, in segments"| EO[EncodeOrchestrator]
+  EO --> EP
+  CM --> EP
+  RB --> EP
+  EP -->|"start / stop / move"| ER
+  ST[(SegmentStore<br/>the disk)] -->|"what is ready"| CM
+```
+
+## Two scopes of one map, and both are right
+
+The map is built from where the viewers are, once, and read at two scopes.
+
+**Per FILE, for the swarm.** The picture, a quality step and a soundtrack of one
+film read the same bytes, so every viewer of any of them wants that file's
+bytes. This is what `PriorityOrchestrator.mapFor(sourceKey, fileIndex)`
+answers, and what is published to the download layer.
+
+**Per OUTPUT, for the encoders.** A person watching 480p wants nothing of the
+1080p output at all. This is `mapForOutput(address)`.
+
+One map for both was the second authority over encoders. Handed the film's map,
+the plan wanted an encoder on every output of the film; what actually stopped
+the ones nobody was watching was the session manager killing them by its own
+judgement — and since a viewer moving between steps announces itself, the plan
+started them again on the very next pass. Two parties answering "should this
+encoder exist" by different rules, several times a second.
+
+An output nobody is on gets a map with **nothing in it**, which is a statement
+and not an absence: the walk writes one for every output a session exists for,
+including the ones everybody has left. That is how the plan is told to stop what
+is on it.
+
+## Which output a person is consuming
+
+A person holds a record on more outputs than they are consuming. The picture is
+where their record lives — the browser addresses it, their chosen soundtrack is
+written on it, their position is read from it — so they are never let go of it;
+but the moment they step down to 480p, the 1080p output is producing for nobody.
+
+That distinction is answered where the two facts meet, and neither layer is
+handed the other:
+
+- **which step is on their screen** is a fact about a PERSON, read off the
+  viewer as one field;
+- **which output a step supersedes** is a fact about the FILM'S SHAPE, answered
+  by `LiveOutputs.supersededBy(session, stepOnScreen)`, which takes a plain id
+  and has never seen a viewer.
+
+A step, a soundtrack, and a step being warmed are consumed by whoever is
+registered on them — everywhere but the picture, a person who stops watching is
+let go of, so being known to an output is consuming it. Through a warm-up both
+the step on screen and the step being made ready are genuinely produced, which
+is the price of the switch not being visible.
+
+## What each of the eight other places used to do
+
+Before 2026-09-08 the plan was one opinion among nine. Each of these placed or
+killed encoders by a rule of its own; each now states the fact it knows.
+
+| it knows | it used to do | it now says |
+|---|---|---|
+| a session was created | start a run at the viewer's position, worked out again | the viewer is placed; the plan reads that |
+| a viewer joined further in | start a run there if nothing was being made | as above |
+| a step or soundtrack is being warmed | point that session at the switch and start it | this person is at N seconds on it |
+| a step was switched to | stop the one left, point the new one | this person is on this step now |
+| a step or track was abandoned | stop its encoder | this person has left that output |
+| the hardware encoder failed | start a run at the dead one's start | what this host encodes with has changed |
+| the input came back | start a run at the last requested segment | decide again |
+| the cut table was corrected | restart the members at the measured instant | this run is producing in the wrong place; the instant is in the file's table |
+| the bitrate cap changed | restart at where the encoder had got to | this run's arguments are stale |
+
+A **seek** is not in that list because it was already reduced to one thing: it
+puts the viewer where they are. The settle timer behind it, its cooldown and its
+one-segment backoff are gone — a second debounce on a signal the browser had
+already debounced, and every millisecond of it was dead time in front of the
+viewer.
+
+## What is checked
+
+`test/one-authority.test.js` holds the shape: one caller of `#startEncodeRun`,
+no encoder stopped for being unwatched, the settle machinery absent, each output
+reading its own map, and the soundtrack's start instant read off the table
+rather than handed in.
+
+`test/priority-map-per-output.test.js` holds the two scopes, over the real
+viewer registry, the real `LiveOutputs` and the real `PriorityOrchestrator`.
+
+`test/encode-plan.test.js` holds the arithmetic, including that every encoder
+stops when nobody is watching the output.

package/package.json

@@ -1,51 +1,50 @@
-{
-  "name": "@torrent-tv/proxy",
-  "version": "2.80.10",
-  "description": "Torrent proxy client that exposes webseed-like HTTP stream endpoint.",
-  "license": "GPL-3.0-or-later",
-  "publishConfig": {
-    "access": "public"
-  },
-  "type": "module",
-  "engines": {
-    "node": ">=24 <25"
-  },
-  "bin": {
-    "torrent-tv-proxy": "./bin/cli.js"
-  },
-  "scripts": {
-    "patch": "npm whoami && npm version patch && npm publish && git push --follow-tags",
-    "minor": "npm whoami && npm version minor && npm publish && git push --follow-tags",
-    "major": "npm whoami && npm version major && npm publish && git push --follow-tags",
-    "start": "node ./bin/cli.js",
-    "dev": "node --inspect=0 --experimental-network-inspection ./bin/cli.js",
-    "test": "npm run lint && node --test && npm run test:measured",
-    "graph": "node scripts/render-run-graph.js",
-    "lint": "biome lint .",
-    "test:measured": "node --test --test-concurrency=1 test-measured/decode-cost.measured.js test-measured/decode-measurement.measured.js"
-  },
-  "dependencies": {
-    "@fastify/cors": "^11.2.0",
-    "@fastify/helmet": "^13.0.2",
-    "@fastify/static": "^10.1.2",
-    "@silentbot1/nat-api": "^0.4.9",
-    "chalk": "^5.4.1",
-    "commander": "^12.1.0",
-    "fastify": "^5.8.5",
-    "ffmpeg-static": "^5.3.0",
-    "franc": "^6.2.0",
-    "get-port": "^7.1.0",
-    "node-datachannel": "^0.32.0",
-    "parse-torrent": "^11.0.23",
-    "uint8-util": "2.2.6",
-    "webtorrent": "2.8.5",
-    "werift": "^0.24.2",
-    "ws": "^8.18.2"
-  },
-  "devDependencies": {
-    "@biomejs/biome": "^2.5.7"
-  },
-  "overrides": {
-    "utp-native": "npm:@torrent-tv/utp-native@2.5.3-ttv.8"
-  }
-}
+{
+  "name": "@torrent-tv/proxy",
+  "version": "2.80.12",
+  "description": "Torrent proxy client that exposes webseed-like HTTP stream endpoint.",
+  "license": "GPL-3.0-or-later",
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "engines": {
+    "node": ">=24 <25"
+  },
+  "bin": {
+    "torrent-tv-proxy": "./bin/cli.js"
+  },
+  "scripts": {
+    "patch": "npm whoami && npm version patch && npm publish && git push --follow-tags",
+    "minor": "npm whoami && npm version minor && npm publish && git push --follow-tags",
+    "major": "npm whoami && npm version major && npm publish && git push --follow-tags",
+    "start": "node ./bin/cli.js",
+    "dev": "node --inspect=0 --experimental-network-inspection ./bin/cli.js",
+    "test": "npm run lint && node --test",
+    "graph": "node scripts/render-run-graph.js",
+    "lint": "biome lint ."
+  },
+  "dependencies": {
+    "@fastify/cors": "^11.2.0",
+    "@fastify/helmet": "^13.0.2",
+    "@fastify/static": "^10.1.2",
+    "@silentbot1/nat-api": "^0.4.9",
+    "chalk": "^5.4.1",
+    "commander": "^12.1.0",
+    "fastify": "^5.8.5",
+    "ffmpeg-static": "^5.3.0",
+    "franc": "^6.2.0",
+    "get-port": "^7.1.0",
+    "node-datachannel": "^0.32.0",
+    "parse-torrent": "^11.0.23",
+    "uint8-util": "2.2.6",
+    "webtorrent": "2.8.5",
+    "werift": "^0.24.2",
+    "ws": "^8.18.2"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^2.5.7"
+  },
+  "overrides": {
+    "utp-native": "npm:@torrent-tv/utp-native@2.5.3-ttv.8"
+  }
+}