@torrent-tv/proxy 2.74.1 → 2.76.0

package/CLAUDE.md

@@ -33,6 +33,14 @@ Linux-only host (e.g. POSIX-only signals must degrade elsewhere).
     `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`.
+  - `output/` — domain layer: `OutputSpec`, `VideoOutput`, `AudioOutput`,
+    `CutGrid`. What a session PRODUCES — which tracks, in what form, cut how,
+    packaged how — and therefore its identity: two outputs whose parameters
+    agree ARE the same output, and the encoded result is reused by definition.
+    Nothing about a VIEWER appears in it (not the consumer id, not where they
+    started, not their viewport), and nothing about the request that does not
+    change a byte of the result. `hls-session-manager` builds one and keys the
+    session on it.
   - `container/` — domain layer: `Container` (abstract, RFC 9559 / ISO 14496-12),
     `MatroskaContainer` / `Mp4Container` / `AviContainer`, `ContainerFactory`
     (sniff 16 bytes → precise subclass). See `docs/container-architecture.md`.
@@ -43,18 +51,23 @@ Linux-only host (e.g. POSIX-only signals must degrade elsewhere).
     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
+    cache, `getTracks`/`getMediaInfo`/`getKeyframeIndex` — the keyframe table is
+    a property of immutable bytes like the other two, memoized on the container
+    and read once per file by whoever asks), `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.
+  - Everything a container states about ITSELF lives in its own class: the
+    track table, the Cues, the keyframe times they name, the cluster positions,
+    the blocks inside a cluster, the MP4 sample table, and the walk of what is
+    downloaded. `services/container-index/` is gone; `container/ebml-reader.js`
+    is the format's byte-level grammar, not its statements, and is the only
+    piece kept apart. `ContainerFactory` is the ONE place that decides what a
+    file is — by sniffing the header, since that is what the muxer wrote — and
+    it also answers `readKeyframeIndex`.
   - `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

package/biome.json

@@ -17,5 +17,186 @@
 				"noPrivateImports": "error"
 			}
 		}
-	}
+	},
+	"overrides": [
+		{
+			"includes": [
+				"services/demand/**",
+				"services/piece-store/**",
+				"services/segment-formats/**",
+				"services/tracks/**",
+				"services/output/**",
+				"services/viewer/**",
+				"services/encode/**",
+				"services/source/**",
+				"services/torrent/**"
+			],
+			"linter": {
+				"rules": {
+					"style": {
+						"noRestrictedImports": {
+							"level": "error",
+							"options": {
+								"patterns": [
+									{
+										"group": ["../**"],
+										"message": "This layer states facts and imports nothing above itself. Anything it needs from outside — a logger, a clock, a way to read bytes — is passed in."
+									}
+								]
+							}
+						}
+					}
+				}
+			}
+		},
+		{
+			"includes": ["services/download/**"],
+			"linter": {
+				"rules": {
+					"style": {
+						"noRestrictedImports": {
+							"level": "error",
+							"options": {
+								"patterns": [
+									{
+										"group": [
+											"../*",
+											"../container/**",
+											"../controllers/**",
+											"../encode/**",
+											"../orchestrators/**",
+											"../output/**",
+											"../segment-formats/**",
+											"../torrent-worker/**",
+											"../tracks/**",
+											"../viewer/**"
+										],
+										"message": "What the swarm is told is decided from what is wanted (demand/) and what is held (piece-store/), and from nothing else."
+									}
+								]
+							}
+						}
+					}
+				}
+			}
+		},
+		{
+			"includes": ["services/container/**"],
+			"linter": {
+				"rules": {
+					"style": {
+						"noRestrictedImports": {
+							"level": "error",
+							"options": {
+								"patterns": [
+									{
+										"group": [
+											"../*",
+											"../controllers/**",
+											"../demand/**",
+											"../download/**",
+											"../encode/**",
+											"../orchestrators/**",
+											"../output/**",
+											"../piece-store/**",
+											"../segment-formats/**",
+											"../torrent-worker/**",
+											"../viewer/**"
+										],
+										"message": "A container answers for itself and hands out tracks/. It knows nothing of torrents, encoders or viewers: the four functions it is built with are its whole outside world."
+									}
+								]
+							}
+						}
+					}
+				}
+			}
+		},
+		{
+			"includes": ["services/orchestrators/**"],
+			"linter": {
+				"rules": {
+					"style": {
+						"noRestrictedImports": {
+							"level": "error",
+							"options": {
+								"patterns": [
+									{
+										"group": [
+											"../*",
+											"../controllers/**",
+											"../demand/**",
+											"../download/**",
+											"../output/**",
+											"../piece-store/**",
+											"../segment-formats/**",
+											"../viewer/**"
+										],
+										"message": "An orchestrator composes the layers below it. Reaching sideways into serving or downloading is what put a scenario in two places before."
+									}
+								]
+							}
+						}
+					}
+				}
+			}
+		},
+		{
+			"includes": ["services/controllers/**"],
+			"linter": {
+				"rules": {
+					"style": {
+						"noRestrictedImports": {
+							"level": "error",
+							"options": {
+								"patterns": [
+									{
+										"group": [
+											"../*",
+											"../demand/**",
+											"../download/**",
+											"../encode/**",
+											"../output/**",
+											"../piece-store/**",
+											"../segment-formats/**",
+											"../torrent-worker/**",
+											"../viewer/**"
+										],
+										"message": "A controller translates a request for an orchestrator. Every layer below the orchestrator is reached through it, never around it."
+									}
+								]
+							}
+						}
+					}
+				}
+			}
+		},
+		{
+			"includes": ["services/torrent-worker/**"],
+			"linter": {
+				"rules": {
+					"style": {
+						"noRestrictedImports": {
+							"level": "error",
+							"options": {
+								"patterns": [
+									{
+										"group": [
+											"../hls-session-manager.js",
+											"../controllers/**",
+											"../encode/**",
+											"../output/**",
+											"../viewer/**",
+											"../segment-formats/**"
+										],
+										"message": "The torrent thread serves bytes. What is produced from them, and for whom, is decided in the main thread and never asked of this one."
+									}
+								]
+							}
+						}
+					}
+				}
+			}
+		}
+	]
 }

package/docs/container-architecture.md

@@ -162,17 +162,38 @@ flowchart TB
 ## Orchestrators & Controllers
 
 - `ContainerFactory.create({readRange,fileSize})` — sniffs 16 bytes, returns precise `Container` subclass. No torrent knowledge.
-- `ContainerOrchestrator` — per-file cache (`sourceKey:fileIndex`), `getTracks()` / `getKeyframeIndex()`. Transport-agnostic.
+- `ContainerOrchestrator` — per-file cache (`sourceKey:fileIndex`), `getTracks()` / `getMediaInfo()` / `getKeyframeIndex()`. Transport-agnostic.
+- **The keyframe table is read once per file**, like the other two. `Container.readKeyframeIndex` memoizes and each format implements `parseKeyframeIndex`, so the wait belongs to the FILE: two sessions created in the same moment join one read rather than making two, which is exactly what two viewers opening one film do. A read that THREW is not remembered — the bytes it needed may simply not have arrived. Who asks: `torrent-worker/container-tracks.js` `containerKeyframesOf`, over the torrent, reached from the session manager by the `container-keyframes` command. The manager's own HTTP read remains for a manager wired without that path (every unit test).
 - `SubtitleOrchestrator` — wraps `torrent-worker/subtitle-cues.js` (`planFor`, `cuesHeldFor`, `warmSubtitleCues`) behind the `ContainerTrack` abstraction. Routes depend on this, not on the worker directly. The reading itself is the containers' — that module supplies the torrent's read policy and keeps the cursor.
 - `PlaybackController` / `SubtitleController` — thin interface adapters; `routes/api/*` delegate to them, handle HTTP headers (`X-Subtitle-Language`, `X-Subtitle-Cursor`) only.
 
 ## Legacy
 
-`services/container-index/` holds what is NOT specific to one media kind: EBML
-element walking, and the Matroska/MP4/AVI keyframe tables. Everything a container
-states about its own subtitles — the track table, the Cues, the blocks in a
-cluster, the sample table — is in the container class itself. Direct imports from
-routes are deprecated — use `orchestrators/` and `controllers/` instead.
+Everything a container states about ITSELF is in its own class: the track table,
+the Cues, the keyframe times they name, the cluster positions, the blocks inside
+a cluster, the MP4 sample table. `services/container-index/` no longer exists.
+What was kept apart is `container/ebml-reader.js` — EBML element walking is the
+format's grammar rather than any of its statements.
+
+`ContainerFactory` is the one place that decides what a file IS. It sniffs the
+header, because that is what the muxer wrote while a name is what somebody
+typed, and it answers `readKeyframeIndex` for the same reason: doing it anywhere
+else meant a third place making that decision. `ContainerFactory.byName` exists
+for the one path that cannot sniff — the cue walk asks the swarm for nothing, so
+a file whose head is not downloaded has only its name.
+
+**Two readings of one file, and which answers.** ffmpeg's `-i` banner and the
+container's own table both describe a file's tracks, and the rule is stated once
+per media kind on `Container`. `alignWithBanner` lines them up by position and
+CHECKS each pair on language or title; one pair agreeing on neither, or a length
+that differs, drops the container reading whole, because a wrong flag is worse
+than a missing one. `mergeSubtitleFlags`, `mergeAudioFlags` and
+`mergeVideoFacts` then say which side answers for which field: flags the banner
+cannot express come from the container; the coded size and frame rate come from
+the probe, because the encoder receives what the decoder produced.
+
+Direct imports from routes are deprecated — use `orchestrators/` and
+`controllers/` instead.
 
 ## Flags matrix
 

package/docs/encode-run-state.md

@@ -1,4 +1,4 @@
-<!-- GENERATED from services/encode-run-state.js by scripts/render-run-graph.js.
+<!-- 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

package/knip.json

@@ -0,0 +1,14 @@
+{
+  "$schema": "https://unpkg.com/knip@6/schema.json",
+  "entry": [
+    "test/*.test.js"
+  ],
+  "project": [
+    "bin/**/*.js",
+    "routes/**/*.js",
+    "services/**/*.js",
+    "utils/**/*.js",
+    "server.js",
+    "test/**/*.js"
+  ]
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@torrent-tv/proxy",
-  "version": "2.74.1",
+  "version": "2.76.0",
   "description": "Torrent proxy client that exposes webseed-like HTTP stream endpoint.",
   "license": "GPL-3.0-or-later",
   "publishConfig": {

package/routes/api/sources/warm/post.js

@@ -3,7 +3,7 @@ import {
   countVideoFiles,
   matchSidecarFiles,
   TEXT_SUBTITLE_SIDECAR_EXTENSIONS
-} from "../../../../services/sidecar-files.js";
+} from "../../../../services/torrent/files.js";
 
 /**
  * Start fetching a source before anyone asks to play it.