@torrent-tv/proxy 2.89.17 → 2.89.19

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (300) hide show
  1. package/README.md +14 -3
  2. package/package.json +10 -2
  3. package/server.js +0 -11
  4. package/utils/client-log-file.js +147 -42
  5. package/.claude/commands/opsx/apply.md +0 -155
  6. package/.claude/commands/opsx/archive.md +0 -160
  7. package/.claude/commands/opsx/explore.md +0 -174
  8. package/.claude/commands/opsx/propose.md +0 -109
  9. package/.claude/commands/opsx/sync.md +0 -143
  10. package/.claude/skills/openspec-apply-change/SKILL.md +0 -159
  11. package/.claude/skills/openspec-archive-change/SKILL.md +0 -117
  12. package/.claude/skills/openspec-explore/SKILL.md +0 -289
  13. package/.claude/skills/openspec-propose/SKILL.md +0 -113
  14. package/.claude/skills/openspec-sync-specs/SKILL.md +0 -147
  15. package/.dockerignore +0 -5
  16. package/AGENTS.md +0 -363
  17. package/CHANGELOG.md +0 -2377
  18. package/Dockerfile +0 -30
  19. package/biome.json +0 -412
  20. package/corpus.tmp.json +0 -1
  21. package/docs/browser-proxy-contract.md +0 -155
  22. package/docs/container-architecture.md +0 -273
  23. package/docs/download-architecture.md +0 -261
  24. package/docs/encode-architecture.md +0 -765
  25. package/docs/encode-run-state.md +0 -96
  26. package/docs/logs.md +0 -151
  27. package/docs/playback-start-forecast.md +0 -113
  28. package/docs/socks5-egress-research.md +0 -114
  29. package/docs/storage-architecture.md +0 -273
  30. package/knip.json +0 -14
  31. package/main2.cpuprofile +0 -1
  32. package/openspec/changes/adaptive-bitrate/.openspec.yaml +0 -0
  33. package/openspec/changes/adaptive-bitrate/design.md +0 -92
  34. package/openspec/changes/adaptive-bitrate/proposal.md +0 -56
  35. package/openspec/changes/adaptive-bitrate/specs/adaptive-bitrate/spec.md +0 -51
  36. package/openspec/changes/adaptive-bitrate/tasks.md +0 -40
  37. package/openspec/changes/binary-distribution/.openspec.yaml +0 -2
  38. package/openspec/changes/binary-distribution/proposal.md +0 -53
  39. package/openspec/changes/chunked-request-bodies/design.md +0 -81
  40. package/openspec/changes/chunked-request-bodies/proposal.md +0 -53
  41. package/openspec/changes/chunked-request-bodies/specs/chunked-request-bodies/spec.md +0 -30
  42. package/openspec/changes/chunked-request-bodies/tasks.md +0 -40
  43. package/openspec/changes/cold-start/design.md +0 -98
  44. package/openspec/changes/cold-start/proposal.md +0 -62
  45. package/openspec/changes/cold-start/specs/cold-start/spec.md +0 -47
  46. package/openspec/changes/cold-start/tasks.md +0 -48
  47. package/openspec/changes/disk-cap/.openspec.yaml +0 -2
  48. package/openspec/changes/disk-cap/proposal.md +0 -37
  49. package/openspec/changes/disk-cap/specs/disk-cap/spec.md +0 -25
  50. package/openspec/changes/disk-cap/tasks.md +0 -19
  51. package/openspec/changes/proxy-observability/.openspec.yaml +0 -2
  52. package/openspec/changes/proxy-observability/design.md +0 -38
  53. package/openspec/changes/proxy-observability/proposal.md +0 -49
  54. package/openspec/changes/proxy-observability/specs/observability/spec.md +0 -33
  55. package/openspec/changes/proxy-observability/tasks.md +0 -21
  56. package/openspec/changes/seek-debounce/.openspec.yaml +0 -0
  57. package/openspec/changes/seek-debounce/design.md +0 -118
  58. package/openspec/changes/seek-debounce/proposal.md +0 -59
  59. package/openspec/changes/seek-debounce/specs/seek-debounce/spec.md +0 -41
  60. package/openspec/changes/seek-debounce/tasks.md +0 -33
  61. package/openspec/changes/subtitle-language/.openspec.yaml +0 -2
  62. package/openspec/changes/subtitle-language/proposal.md +0 -50
  63. package/openspec/changes/subtitle-language/specs/subtitle-language/spec.md +0 -34
  64. package/openspec/changes/subtitle-language/tasks.md +0 -26
  65. package/openspec/changes/track-selection/.openspec.yaml +0 -2
  66. package/openspec/changes/track-selection/design.md +0 -47
  67. package/openspec/changes/track-selection/proposal.md +0 -45
  68. package/openspec/changes/track-selection/specs/track-selection/spec.md +0 -41
  69. package/openspec/changes/track-selection/tasks.md +0 -20
  70. package/openspec/changes/transcode-quality/.openspec.yaml +0 -2
  71. package/openspec/changes/transcode-quality/proposal.md +0 -51
  72. package/openspec/changes/transcode-quality/specs/transcode-quality/spec.md +0 -139
  73. package/openspec/changes/transcode-quality/tasks.md +0 -63
  74. package/openspec/config.yaml +0 -38
  75. package/public/.well-known/appspecific/com.chrome.devtools.json +0 -1
  76. package/research/delivery-wedge-stand-ladder-2026-09-13.md +0 -329
  77. package/research/double-spawn-2026-09-10.md +0 -171
  78. package/research/handover-2026-09-13.md +0 -209
  79. package/research/handover-reader-claims-removal-2026-09-12.md +0 -166
  80. package/research/piece-withdrawn-but-still-claimed-2026-09-12.md +0 -175
  81. package/research/preset-benchmark-size-scaling-2026-08-22.md +0 -55
  82. package/research/priority-map-is-the-truth-2026-09-12.md +0 -225
  83. package/research/valgrind-replica-2026-08-27/logs.tar.gz +0 -0
  84. package/scripts/build-audio-samples.mjs +0 -31
  85. package/scripts/render-run-graph.js +0 -173
  86. package/test/asset-paths.test.js +0 -28
  87. package/test/audio-buffer-continuity.test.js +0 -77
  88. package/test/audio-calibration.test.js +0 -23
  89. package/test/audio-inventory.test.js +0 -212
  90. package/test/audio-track-bitrate.test.js +0 -40
  91. package/test/audio-warm-recorded.test.js +0 -63
  92. package/test/auto-quality-step.test.js +0 -762
  93. package/test/available-share.test.js +0 -76
  94. package/test/background-fill.test.js +0 -190
  95. package/test/client-log-file.test.js +0 -126
  96. package/test/client-logs-route.test.js +0 -34
  97. package/test/coalesce.test.js +0 -39
  98. package/test/completed-files.test.js +0 -115
  99. package/test/concurrent-cost.test.js +0 -148
  100. package/test/container-media-info.test.js +0 -228
  101. package/test/contention.test.js +0 -76
  102. package/test/core-dumps.test.js +0 -57
  103. package/test/coverage-follows-the-disk.test.js +0 -233
  104. package/test/coverage-map.test.js +0 -195
  105. package/test/cue-push-carries-what-the-walk-found.test.js +0 -58
  106. package/test/cut-times-timeline.test.js +0 -65
  107. package/test/cuts-follow-published-grid.test.js +0 -109
  108. package/test/data-channel-frame.test.js +0 -63
  109. package/test/data-channel-viewer-lifecycle.test.js +0 -193
  110. package/test/dead-torrent-handle.test.js +0 -52
  111. package/test/declared-rates.test.js +0 -116
  112. package/test/declared-tracks.test.js +0 -43
  113. package/test/decode-cost-fit.test.js +0 -202
  114. package/test/decode-cost.test.js +0 -475
  115. package/test/delivery-probe-field.test.js +0 -173
  116. package/test/delivery-probe.test.js +0 -382
  117. package/test/demand-register.test.js +0 -206
  118. package/test/dht-bootstrap.test.js +0 -72
  119. package/test/drain-threat.test.js +0 -65
  120. package/test/duplicate-add.test.js +0 -48
  121. package/test/encode-admission.test.js +0 -170
  122. package/test/encode-cost.test.js +0 -275
  123. package/test/encode-exit.test.js +0 -111
  124. package/test/encode-orchestrator.test.js +0 -426
  125. package/test/encode-plan-viewers.test.js +0 -725
  126. package/test/encode-plan.test.js +0 -545
  127. package/test/encode-run-state.test.js +0 -314
  128. package/test/encode-run.test.js +0 -248
  129. package/test/encode-slope.test.js +0 -46
  130. package/test/encoded-output.test.js +0 -39
  131. package/test/encoder-kinds.test.js +0 -122
  132. package/test/encoder-readings.test.js +0 -68
  133. package/test/episode-naming.test.js +0 -131
  134. package/test/every-claimant-is-told-its-share.test.js +0 -152
  135. package/test/failed-encoder-still-serves-what-exists.test.js +0 -354
  136. package/test/failed-start-breaker.test.js +0 -202
  137. package/test/fastest-wires.test.js +0 -143
  138. package/test/ffmpeg-stream-counts.test.js +0 -101
  139. package/test/file-edges.test.js +0 -191
  140. package/test/files-in-use.test.js +0 -34
  141. package/test/fixtures/audio-frame-boundary.json +0 -1
  142. package/test/fixtures/refused-audio-20261002.json +0 -10
  143. package/test/fmp4-presentation-clock.test.js +0 -148
  144. package/test/fmp4-self-contained.test.js +0 -80
  145. package/test/fmp4-timestamps.test.js +0 -140
  146. package/test/fmp4-track-completeness.test.js +0 -41
  147. package/test/format-keyed-outputs.test.js +0 -78
  148. package/test/health-metrics.test.js +0 -36
  149. package/test/held-read-ownership.test.js +0 -77
  150. package/test/held-request-width.test.js +0 -157
  151. package/test/helpers/encode-run.js +0 -248
  152. package/test/helpers/held-file.js +0 -77
  153. package/test/helpers/manager.js +0 -62
  154. package/test/helpers/matroska-file.js +0 -296
  155. package/test/helpers/output-spec.js +0 -63
  156. package/test/host-load.test.js +0 -68
  157. package/test/index-accuracy-is-about-the-file.test.js +0 -128
  158. package/test/init-compat.test.js +0 -219
  159. package/test/input-lost-quiets-the-plan.test.js +0 -261
  160. package/test/input-unavailable.test.js +0 -48
  161. package/test/installation-id.test.js +0 -39
  162. package/test/keeping-period.test.js +0 -83
  163. package/test/keyframe-index-accuracy.test.js +0 -188
  164. package/test/keyframe-table-budget.test.js +0 -123
  165. package/test/keyframes-belong-to-the-file.test.js +0 -249
  166. package/test/learned-median.test.js +0 -37
  167. package/test/letting-go-asks-who-is-watching.test.js +0 -191
  168. package/test/limit-row-by-area.test.js +0 -60
  169. package/test/link-budget.test.js +0 -111
  170. package/test/link-probe.test.js +0 -56
  171. package/test/local-encoding-data.test.js +0 -273
  172. package/test/logger-repeats.test.js +0 -134
  173. package/test/look-ahead-coverage.test.js +0 -56
  174. package/test/manager-surface.test.js +0 -291
  175. package/test/matroska-blocks.test.js +0 -0
  176. package/test/matroska-cluster-discovery.test.js +0 -323
  177. package/test/matroska-cues-track.test.js +0 -192
  178. package/test/media-time.test.js +0 -62
  179. package/test/memory-budget.test.js +0 -390
  180. package/test/move-cost.test.js +0 -216
  181. package/test/mp4-composition-times.test.js +0 -0
  182. package/test/mp4-subtitles.test.js +0 -173
  183. package/test/one-authority.test.js +0 -285
  184. package/test/one-budget.test.js +0 -149
  185. package/test/one-output-one-session.test.js +0 -273
  186. package/test/one-resource-divided.test.js +0 -185
  187. package/test/one-serving-output-per-height.test.js +0 -458
  188. package/test/orchestrator-wired.test.js +0 -207
  189. package/test/output-catalog.test.js +0 -39
  190. package/test/output-shape.test.js +0 -21
  191. package/test/output-spec.test.js +0 -251
  192. package/test/output-speed.test.js +0 -92
  193. package/test/outputs-being-prepared.test.js +0 -40
  194. package/test/packet-witness-ring.test.js +0 -236
  195. package/test/packet-witness.test.js +0 -148
  196. package/test/piece-completeness.test.js +0 -78
  197. package/test/piece-disk-store.test.js +0 -401
  198. package/test/piece-from-whole-file.test.js +0 -129
  199. package/test/piece-lru.test.js +0 -319
  200. package/test/piece-reader.test.js +0 -162
  201. package/test/piece-selection-offset.test.js +0 -85
  202. package/test/piece-store-eviction.test.js +0 -595
  203. package/test/piece-store-never-refuses.test.js +0 -153
  204. package/test/piece-store-reservations.test.js +0 -403
  205. package/test/piece-store-slow-disk.test.js +0 -159
  206. package/test/piece-tail.test.js +0 -97
  207. package/test/plan-host-timings.test.js +0 -68
  208. package/test/plan-is-steady.test.js +0 -225
  209. package/test/playback-readiness.test.js +0 -518
  210. package/test/playback-start-regressions.test.js +0 -101
  211. package/test/priority-map-download.test.js +0 -174
  212. package/test/priority-map-emptied.test.js +0 -204
  213. package/test/priority-map-per-output.test.js +0 -215
  214. package/test/priority-map.test.js +0 -163
  215. package/test/probe-wedge-certainty.test.js +0 -60
  216. package/test/produced-copy-choice.test.js +0 -213
  217. package/test/published-timeline.test.js +0 -83
  218. package/test/quality-offer.test.js +0 -160
  219. package/test/quality-variants.test.js +0 -1274
  220. package/test/rate-control-in-the-output.test.js +0 -181
  221. package/test/read-survives-withdrawal.test.js +0 -164
  222. package/test/read-window.test.js +0 -365
  223. package/test/reads-not-yet-arrived.test.js +0 -218
  224. package/test/resume-warm.test.js +0 -39
  225. package/test/run-graph-drift.test.js +0 -37
  226. package/test/run-inputs.test.js +0 -80
  227. package/test/run-intervals.test.js +0 -100
  228. package/test/run-position-follows-published-grid.test.js +0 -89
  229. package/test/run-progress.test.js +0 -64
  230. package/test/same-height-switch.test.js +0 -663
  231. package/test/seek-frees-the-viewers-requests.test.js +0 -217
  232. package/test/seek-landing.test.js +0 -109
  233. package/test/seek-target-not-superseded.test.js +0 -195
  234. package/test/segment-closed-on-both-branches.test.js +0 -114
  235. package/test/segment-cut-times.test.js +0 -63
  236. package/test/segment-demand.test.js +0 -80
  237. package/test/segment-hold-supersede.test.js +0 -91
  238. package/test/segment-judged-by-its-own-header.test.js +0 -222
  239. package/test/segment-serve-wiring.test.js +0 -481
  240. package/test/segment-store-eviction.test.js +0 -247
  241. package/test/segment-store.test.js +0 -352
  242. package/test/segment-true-start.test.js +0 -86
  243. package/test/segments-are-shared.test.js +0 -176
  244. package/test/send-chunk-bytes.test.js +0 -86
  245. package/test/serving-existing-output.test.js +0 -111
  246. package/test/serving-output.test.js +0 -102
  247. package/test/shared-piece-store.test.js +0 -310
  248. package/test/sidecar-naming.test.js +0 -142
  249. package/test/soundtrack-rate-bound.test.js +0 -289
  250. package/test/source-file.test.js +0 -133
  251. package/test/source-files-route.test.js +0 -113
  252. package/test/source-registry.test.js +0 -18
  253. package/test/split-a-stretch.test.js +0 -139
  254. package/test/stale-request-after-seek.test.js +0 -158
  255. package/test/startup-readings.test.js +0 -124
  256. package/test/stream-route.test.js +0 -237
  257. package/test/subtitle-cue-framing.test.js +0 -200
  258. package/test/subtitle-cue-source.test.js +0 -102
  259. package/test/subtitle-cue-walk.test.js +0 -385
  260. package/test/subtitle-cursor.test.js +0 -63
  261. package/test/subtitle-defaults.test.js +0 -118
  262. package/test/subtitle-language.test.js +0 -252
  263. package/test/subtitle-metadata.test.js +0 -15
  264. package/test/subtitle-plan-waits.test.js +0 -125
  265. package/test/subtitle-track-numbering.test.js +0 -391
  266. package/test/supply-margin.test.js +0 -190
  267. package/test/swarm-follows-readers.test.js +0 -174
  268. package/test/swarm-reach.test.js +0 -130
  269. package/test/swarm-selection.test.js +0 -220
  270. package/test/tail-duplication.test.js +0 -167
  271. package/test/the-channel-has-both-ends.test.js +0 -91
  272. package/test/the-torrent-thread-serves-bytes.test.js +0 -107
  273. package/test/thread-pool.test.js +0 -53
  274. package/test/timeline.test.js +0 -84
  275. package/test/torrent-contents.test.js +0 -235
  276. package/test/torrent-cost.test.js +0 -71
  277. package/test/torrent-files.test.js +0 -221
  278. package/test/torrent-naming.test.js +0 -255
  279. package/test/tracks-begin-together.test.js +0 -209
  280. package/test/tunnel-renewal.test.js +0 -167
  281. package/test/two-viewers-one-picture.test.js +0 -508
  282. package/test/upload-hurry.test.js +0 -186
  283. package/test/usrsctp-state.test.js +0 -131
  284. package/test/video-facts.test.js +0 -102
  285. package/test/viewer-assignments.test.js +0 -143
  286. package/test/viewer-outputs.test.js +0 -285
  287. package/test/viewer-presence.test.js +0 -116
  288. package/test/viewer-requests-admission.test.js +0 -92
  289. package/test/viewer-starts-on-map.test.js +0 -27
  290. package/test/viewer-states.test.js +0 -192
  291. package/test/viewer-subtitle-subscription.test.js +0 -96
  292. package/test/viewer.test.js +0 -139
  293. package/test/viewing-generations.test.js +0 -390
  294. package/test/visible-rung.test.js +0 -37
  295. package/test/wait-ledger.test.js +0 -100
  296. package/test/webrtc-shim.test.js +0 -149
  297. package/test/wedge-certainty.test.js +0 -131
  298. package/test/whole-file-held-read.test.js +0 -30
  299. package/test/withdraw-piece-claim.test.js +0 -212
  300. package/test/worker-channel.test.js +0 -158
@@ -1,595 +0,0 @@
1
- /**
2
- * Eviction under concurrency.
3
- *
4
- * Pieces arrive from several peers at once, so `put` runs concurrently by
5
- * nature. Choosing a victim and releasing it either side of the spill write
6
- * therefore let two claims pick the SAME victim and receive the SAME slot, at
7
- * which point two pieces overwrite each other, both fail their hash, and the
8
- * torrent re-downloads them without end — which looks from outside exactly like
9
- * a seek that never completes while the download runs at full speed.
10
- */
11
-
12
- import test from "node:test";
13
- import assert from "node:assert/strict";
14
- import fs from "node:fs/promises";
15
- import os from "node:os";
16
- import path from "node:path";
17
- import { SharedPieceStore } from "../services/storage/piece-store/shared-piece-store.js";
18
-
19
- const PIECE = 1024;
20
-
21
- /**
22
- * @param {number} capacityPieces
23
- * @returns {Promise<{ store: SharedPieceStore, directory: string }>}
24
- */
25
- async function makeStore(capacityPieces) {
26
- const directory = await fs.mkdtemp(path.join(os.tmpdir(), "piece-store-test-"));
27
- const store = new SharedPieceStore(PIECE, {
28
- length: PIECE * 64,
29
- memoryBytes: PIECE * capacityPieces,
30
- path: directory,
31
- name: "eviction-test"
32
- });
33
- return { store, directory };
34
- }
35
-
36
- /**
37
- * @param {number} index
38
- * @returns {Buffer} A piece whose every byte identifies it.
39
- */
40
- const pieceOf = (index) => Buffer.alloc(PIECE, index % 251);
41
-
42
- /**
43
- * @param {SharedPieceStore} store
44
- * @param {number} index
45
- * @param {Buffer} bytes
46
- * @returns {Promise<void>}
47
- */
48
- const put = (store, index, bytes) =>
49
- new Promise((resolve, reject) => {
50
- store.put(index, bytes, (error) => (error ? reject(error) : resolve()));
51
- });
52
-
53
- /**
54
- * @param {SharedPieceStore} store
55
- * @param {number} index
56
- * @returns {Promise<Buffer>}
57
- */
58
- const get = (store, index) =>
59
- new Promise((resolve, reject) => {
60
- store.get(index, (error, bytes) => (error ? reject(error) : resolve(bytes)));
61
- });
62
-
63
- test("concurrent puts past capacity never hand two pieces the same slot", async () => {
64
- const capacity = 4;
65
- const { store, directory } = await makeStore(capacity);
66
- try {
67
- const total = 24;
68
-
69
- // All at once — the interleaving that a sequential test never produces.
70
- await Promise.all(
71
- Array.from({ length: total }, (unused, index) => put(store, index, pieceOf(index)))
72
- );
73
-
74
- // Every piece must read back as itself, from memory or from disk. A shared
75
- // slot shows up here as one piece carrying another's bytes.
76
- for (let index = 0; index < total; index += 1) {
77
- const bytes = await get(store, index);
78
- assert.equal(bytes.length, PIECE, `piece ${index} came back the wrong length`);
79
- assert.ok(
80
- bytes.equals(pieceOf(index)),
81
- `piece ${index} came back as piece ${bytes[0]} — two pieces shared a slot`
82
- );
83
- }
84
-
85
- const stats = store.stats();
86
- assert.ok(
87
- stats.resident <= stats.capacity,
88
- `resident ${stats.resident} exceeds capacity ${stats.capacity}: slots were handed out twice`
89
- );
90
- } finally {
91
- await store.destroy();
92
- await fs.rm(directory, { recursive: true, force: true, maxRetries: 10, retryDelay: 20 });
93
- }
94
- });
95
-
96
- test("a piece caught mid-spill is waited for, not reported missing", async () => {
97
- const { store, directory } = await makeStore(2);
98
- try {
99
- await put(store, 0, pieceOf(0));
100
- await put(store, 1, pieceOf(1));
101
-
102
- // Forces piece 0 out while piece 0 is asked for in the same tick.
103
- const evicting = put(store, 2, pieceOf(2));
104
- const reading = get(store, 0);
105
-
106
- await evicting;
107
- const bytes = await reading;
108
- assert.ok(bytes.equals(pieceOf(0)), "piece 0 came back wrong while being spilled");
109
- } finally {
110
- await store.destroy();
111
- await fs.rm(directory, { recursive: true, force: true, maxRetries: 10, retryDelay: 20 });
112
- }
113
- });
114
-
115
- test("pinned pieces are never evicted, and the pin count is reported", async () => {
116
- const { store, directory } = await makeStore(2);
117
- try {
118
- await put(store, 0, pieceOf(0));
119
- store.pin(0);
120
- assert.equal(store.stats().pinned, 1, "pin is not reflected in the stats");
121
-
122
- await put(store, 1, pieceOf(1));
123
- await put(store, 2, pieceOf(2));
124
-
125
- // Piece 0 is pinned, so it must still be the one in memory, not on disk.
126
- assert.ok(store.locate(0), "a pinned piece was evicted");
127
-
128
- store.unpin(0);
129
- assert.equal(store.stats().pinned, 0, "unpin is not reflected in the stats");
130
- } finally {
131
- await store.destroy();
132
- await fs.rm(directory, { recursive: true, force: true, maxRetries: 10, retryDelay: 20 });
133
- }
134
- });
135
-
136
- test("the store says why it spills: what is asked of it, what it had to take, how soon it came back", async () => {
137
- const capacity = 4;
138
- const { store, directory } = await makeStore(capacity);
139
- try {
140
- // A reader declaring more than the store may hold. This is the shape the
141
- // field session of 2026-09-02 is suspected of — 88 slots against an
142
- // encoder running 120-380 s ahead of a viewer, half the reads missing —
143
- // and nothing recorded it (roadmap item 9).
144
- store.protectRange("video", 0, 9);
145
- for (let index = 0; index < 10; index += 1) {
146
- await put(store, index, pieceOf(index));
147
- }
148
-
149
- const asked = store.stats();
150
- assert.equal(asked.demand.readers, 1);
151
- assert.equal(asked.demand.unionPieces, 10);
152
- assert.equal(asked.demand.capacity, capacity);
153
- assert.ok(
154
- asked.demand.unionPieces > asked.demand.capacity,
155
- "a reader asking for more than the store holds is arithmetic, not a policy fault"
156
- );
157
- // And it no longer has to take a declared piece to make room. The reader
158
- // asked for ten pieces of a store that holds four, and the arrivals that
159
- // will be wanted LATER than what is already resident are written straight
160
- // to disk instead of displacing what will be wanted sooner. Before
161
- // 2026-09-02 every one of them displaced something and was read back
162
- // moments later: 233 evictions against 119 completed writes in a minute.
163
- assert.equal(asked.evictedProtected, 0, "a nearer piece was pushed out for a further one");
164
- assert.equal(asked.spills, 0, "nothing had to be written out to make room on admission");
165
- assert.ok(asked.admittedToDisk > 0, "the further arrivals were supposed to go to disk");
166
-
167
- // Read back the pieces that were spilled: each one comes home, and the
168
- // store says how long it had been away.
169
- for (let index = 0; index < 10; index += 1) {
170
- const bytes = await get(store, index);
171
- assert.ok(bytes.equals(pieceOf(index)), `piece ${index} came back changed`);
172
- }
173
-
174
- const after = store.stats();
175
- // Reading them back does evict, and that is ordinary: a piece brought into
176
- // memory has to displace one. What the change of 2026-09-02 removed is the
177
- // eviction on ADMISSION — `asked.spills` above is zero, where before it all
178
- // six arrivals displaced a nearer piece and were read back moments later.
179
- assert.ok(after.fromDisk > 0, "the pieces that went to disk were read back from it");
180
- // Through the reader's own entry point, which is the one that populates
181
- // memory. `get` is the torrent client's, and since 2026-09-11 it answers
182
- // from disk without taking a block: a peer asks for kilobytes of a piece
183
- // that is megabytes, and reviving the whole of it for that was how an
184
- // upload capped at 512 KB/s produced 49 696 revivals in one session.
185
- await store.reside(9);
186
- assert.ok(store.stats().revivals > 0, "a read for playback brings the piece into memory");
187
- // No age to report, and that is right rather than missing: an age measures
188
- // how long an EVICTED piece stayed away, and these were never resident —
189
- // they were written on arrival and read back once.
190
- assert.equal(after.revivalAgeSamples, 0);
191
- assert.equal(after.revivalAgeMedianMs, null);
192
-
193
- store.releaseProtection("video");
194
- assert.equal(store.stats().demand.readers, 0, "a reader that ends stops being counted");
195
- } finally {
196
- store.destroy(() => undefined);
197
- await fs.rm(directory, { recursive: true, force: true, maxRetries: 10, retryDelay: 20 });
198
- }
199
- });
200
-
201
- test("a piece nobody has declared does not push out one that is being read", async () => {
202
- const capacity = 4;
203
- const { store, directory } = await makeStore(capacity);
204
- try {
205
- // A reader declares the pieces it will need, and they are put in memory.
206
- store.protectRange("video", 0, 3);
207
- for (let index = 0; index < 4; index += 1) {
208
- await put(store, index, pieceOf(index));
209
- }
210
- assert.equal(store.stats().resident, capacity, "the declared window fills the store");
211
-
212
- // Now pieces arrive that the download fetched ahead of every reader. Before
213
- // 2026-09-02 each of them claimed a slot and evicted one of the four above,
214
- // which was then read back from disk moments later: 6565 spills and 7575
215
- // revivals in 44 minutes, 53.6% of reads served from memory.
216
- for (let index = 100; index < 110; index += 1) {
217
- await put(store, index, pieceOf(index));
218
- }
219
-
220
- const stats = store.stats();
221
- assert.equal(stats.admittedToDisk, 10, "every undeclared arrival went straight to disk");
222
- assert.equal(stats.admittedOutsideWindow, 10);
223
- assert.equal(stats.admittedInsideWindow, 4);
224
- assert.equal(stats.spills, 0, "and nothing had to be pushed out to make room");
225
-
226
- // The declared pieces are still in memory, and every piece reads back as
227
- // itself from whichever tier holds it.
228
- assert.equal(stats.resident, capacity);
229
- for (const index of [0, 1, 2, 3, 100, 105, 109]) {
230
- const bytes = await get(store, index);
231
- assert.ok(bytes.equals(pieceOf(index)), `piece ${index} came back changed`);
232
- }
233
- } finally {
234
- store.destroy(() => undefined);
235
- await fs.rm(directory, { recursive: true, force: true, maxRetries: 10, retryDelay: 20 });
236
- }
237
- });
238
-
239
- test("before any reader has declared anything, an arriving piece still goes to memory", async () => {
240
- const { store, directory } = await makeStore(4);
241
- try {
242
- // No window declared: there is no basis for calling a piece unwanted, so
243
- // the store behaves as it always did. This is the initial download, and the
244
- // warm-up fetches of the header and the tail.
245
- for (let index = 0; index < 8; index += 1) {
246
- await put(store, index, pieceOf(index));
247
- }
248
- const stats = store.stats();
249
- assert.equal(stats.admittedToDisk, 0, "nothing was refused memory on a guess");
250
- assert.equal(stats.admittedOutsideWindow, 8);
251
- assert.ok(stats.spills > 0, "the store filled and evicted, as it did before");
252
- } finally {
253
- store.destroy(() => undefined);
254
- await fs.rm(directory, { recursive: true, force: true, maxRetries: 10, retryDelay: 20 });
255
- }
256
- });
257
-
258
- test("the store asks for what its readers declared, and for a whole window at least", async () => {
259
- const { store, directory } = await makeStore(64);
260
- try {
261
- // With nobody reading, the store asks for a floor — one window's worth,
262
- // and until it has been asked for anything, the minimum. It does NOT ask
263
- // for everything it is allowed: pieces arriving for a reader still on its
264
- // way have the disk.
265
- const idle = store.wantedBytes;
266
- assert.ok(idle > 0 && idle < store.stats().budgetBytes, "an idle store asks for a floor, not its whole allowance");
267
-
268
- // Two readers of one file — picture and sound — overlapping by
269
- // construction. The ask is their union, not their sum.
270
- store.protectRange("video", 10, 29);
271
- store.protectRange("audio", 25, 44);
272
- assert.equal(store.wantedBytes, 35 * PIECE, "10..44 is thirty-five pieces, not forty");
273
-
274
- // One reader with a window wider than the union of nothing else: the ask
275
- // never falls below a single window, or that reader's read cannot complete
276
- // at all — every resident piece ends up pinned and the read returns zero
277
- // bytes.
278
- store.releaseProtection("audio");
279
- store.releaseProtection("video");
280
- store.protectRange("video", 0, 49);
281
- assert.equal(store.wantedBytes, 50 * PIECE);
282
- } finally {
283
- store.destroy(() => undefined);
284
- await fs.rm(directory, { recursive: true, force: true, maxRetries: 10, retryDelay: 20 });
285
- }
286
- });
287
-
288
- test("the floor the ceiling will not fall below is the same union, not the widest reader alone", async () => {
289
- const { store, directory } = await makeStore(64);
290
- try {
291
- // The same two overlapping readers as the ask above: picture and sound,
292
- // 10..44, thirty-five pieces together. The machine now offers far less
293
- // than that (ten pieces) — before this fix the floor here came from
294
- // `widestPieces` (twenty, the wider of the two readers alone), fifteen
295
- // short of what both of them were actually pinning at once. A field
296
- // session with three such readers on one file (video, audio and the
297
- // edge-warming read) reached exactly that shortfall on 2026-09-07: every
298
- // resident piece ended up pinned and WebTorrent destroyed the torrent
299
- // over it.
300
- store.protectRange("video", 10, 29);
301
- store.protectRange("audio", 25, 44);
302
- const revised = store.reviseGrowthCeiling(10 * PIECE);
303
- assert.equal(
304
- revised.ceilingBytes,
305
- 35 * PIECE,
306
- "the floor is the union of both readers, not the wider one alone"
307
- );
308
- } finally {
309
- store.destroy(() => undefined);
310
- await fs.rm(directory, { recursive: true, force: true, maxRetries: 10, retryDelay: 20 });
311
- }
312
- });
313
-
314
- test("a block is re-used instead of a new one being allocated for every piece", async () => {
315
- const capacity = 4;
316
- const { store, directory } = await makeStore(capacity);
317
- try {
318
- // Twenty pieces through a store that may hold four. Before 2026-09-02 that
319
- // was twenty allocations of a piece each, every one of them released only
320
- // when the collector got to it — 7575 of them in 44 minutes in the field,
321
- // and 1.86 GB held while the store's own accounting said 352 MB.
322
- for (let index = 0; index < 20; index += 1) {
323
- await put(store, index, pieceOf(index));
324
- }
325
-
326
- const stats = store.stats();
327
- assert.ok(
328
- stats.blocksAllocated <= capacity,
329
- `the pool never exceeds the allowance: ${stats.blocksAllocated} blocks for ${capacity} slots`
330
- );
331
- assert.equal(stats.committedBytes, stats.blocksAllocated * PIECE);
332
- assert.equal(stats.returnedWhilePinned, 0);
333
- assert.ok(stats.reuseGapMs !== null, "blocks were taken from the free list, not freshly made");
334
-
335
- // And every piece still reads back as itself: a re-used block must not
336
- // carry the last piece's bytes into the next one.
337
- for (let index = 0; index < 20; index += 1) {
338
- const bytes = await get(store, index);
339
- assert.ok(bytes.equals(pieceOf(index)), `piece ${index} came back changed`);
340
- }
341
- } finally {
342
- store.destroy(() => undefined);
343
- await fs.rm(directory, { recursive: true, force: true, maxRetries: 10, retryDelay: 20 });
344
- }
345
- });
346
-
347
- test("a spare block is given up once it has sat longer than the store's own working rhythm", async () => {
348
- const { store, directory } = await makeStore(8);
349
- try {
350
- for (let index = 0; index < 12; index += 1) {
351
- await put(store, index, pieceOf(index));
352
- }
353
- // The allowance falls: pieces are written out and their blocks fall spare.
354
- store.reviseGrowthCeiling(2 * PIECE);
355
- const spare = store.stats().blocksFree;
356
-
357
- // Nothing is given up while the blocks are younger than the longest wait
358
- // this store has actually seen between a block falling free and being
359
- // wanted again.
360
- assert.equal(store.sweepFreeBlocks(Date.now()), 0, "a block in use moments ago is not spare");
361
- assert.equal(store.stats().blocksFree, spare);
362
-
363
- // An hour later they plainly are.
364
- const released = store.sweepFreeBlocks(Date.now() + 3_600_000);
365
- assert.equal(released, spare);
366
- assert.equal(store.stats().blocksFree, 0);
367
- assert.equal(store.stats().blocksReleased, released);
368
- } finally {
369
- store.destroy(() => undefined);
370
- await fs.rm(directory, { recursive: true, force: true, maxRetries: 10, retryDelay: 20 });
371
- }
372
- });
373
-
374
- test("evicting a piece the disk already holds costs no second write", async () => {
375
- const { store, directory } = await makeStore(2);
376
- try {
377
- // Three pieces through two slots: piece 0 is written out.
378
- for (let index = 0; index < 3; index += 1) {
379
- await put(store, index, pieceOf(index));
380
- }
381
- const written = store.stats().spills;
382
- assert.ok(written > 0);
383
- assert.equal(store.stats().spillsSkipped, 0, "the first write of a piece is a real one");
384
-
385
- // Read it back for playback — it returns to memory and the copy stays on
386
- // disk. Evicting it again writes bytes that are already there, byte for
387
- // byte, because only `put` removes the disk copy and no `put` has happened.
388
- assert.ok((await get(store, 0)).equals(pieceOf(0)));
389
- await store.reside(0);
390
- for (let index = 10; index < 13; index += 1) {
391
- await put(store, index, pieceOf(index));
392
- }
393
- assert.ok(store.stats().spillsSkipped > 0, "the second write of the same bytes is skipped");
394
-
395
- // And the piece still comes back correctly from the disk copy.
396
- assert.ok((await get(store, 0)).equals(pieceOf(0)));
397
- } finally {
398
- store.destroy(() => undefined);
399
- await fs.rm(directory, { recursive: true, force: true, maxRetries: 10, retryDelay: 20 });
400
- }
401
- });
402
-
403
- test("a store whose readers have gone asks for nothing, one that never had them keeps its opening", async () => {
404
- const { store, directory } = await makeStore(16);
405
- try {
406
- // Never had a reader: this is the initial download and the warm-up fetches
407
- // of the header and the tail, with a read on its way. Those pieces have the
408
- // disk, so the store asks for the minimum rather than for its opening
409
- // allowance — a torrent nobody has read yet held 4180 MB of a machine's
410
- // memory on 2026-09-11 while the film being watched was allowed 12 MB.
411
- const opening = store.wantedBytes;
412
- assert.ok(opening < store.stats().budgetBytes, "a store nobody has read keeps the minimum");
413
-
414
- store.protectRange("video", 0, 9);
415
- assert.equal(store.wantedBytes, 10 * PIECE);
416
-
417
- // The read ends, and the store keeps room for ONE window — what the next
418
- // read will ask for within seconds. Falling to the minimum here is what
419
- // left a store at three blocks when the viewer switched files on
420
- // 2026-09-11, with the allowance re-derived a minute later and a claim
421
- // giving up after five seconds.
422
- store.releaseProtection("video");
423
- assert.equal(store.wantedBytes, 10 * PIECE, "the floor between readers is the widest window seen");
424
- assert.ok(store.wantedBytes > opening, "which is more than a store nobody has read keeps");
425
- } finally {
426
- store.destroy(() => undefined);
427
- await fs.rm(directory, { recursive: true, force: true, maxRetries: 10, retryDelay: 20 });
428
- }
429
- });
430
-
431
- test("live piece pins set memory demand when no priority-map range is declared", async () => {
432
- const { store, directory } = await makeStore(2);
433
- try {
434
- await put(store, 0, pieceOf(0));
435
- await put(store, 1, pieceOf(1));
436
-
437
- store.pin(0);
438
- store.pin(1);
439
- store.pin(2);
440
-
441
- assert.equal(store.stats().demand.readers, 0, "this read has no priority-map range");
442
- assert.equal(store.stats().pinned, 3, "the three distinct live pieces are measured");
443
- assert.equal(store.capacity, 3, "the active read demand expands capacity immediately");
444
- assert.equal(store.wantedBytes, 3 * PIECE, "the budget owner sees the same measured demand");
445
-
446
- const revised = store.reviseGrowthCeiling(2 * PIECE);
447
- assert.equal(revised.ceilingBytes, 3 * PIECE, "a budget pass preserves pieces in active reads");
448
- assert.equal(revised.belowActiveDemand, true, "the store reports that the machine share was short");
449
-
450
- await put(store, 2, pieceOf(2));
451
- assert.ok(store.locate(0), "the first active piece remains resident");
452
- assert.ok(store.locate(1), "the second active piece remains resident");
453
- assert.ok(store.locate(2), "the pending active piece obtains a memory slot");
454
-
455
- store.unpin(0);
456
- store.unpin(1);
457
- store.unpin(2);
458
- const released = store.reviseGrowthCeiling(2 * PIECE);
459
- assert.equal(released.ceilingBytes, 2 * PIECE, "the measured floor falls after the reads release their pieces");
460
- } finally {
461
- await store.destroy();
462
- await fs.rm(directory, { recursive: true, force: true, maxRetries: 10, retryDelay: 20 });
463
- }
464
- });
465
-
466
- test("the allowance is never cut below one reader's whole window", async () => {
467
- const { store, directory } = await makeStore(16);
468
- try {
469
- store.protectRange("video", 0, 9);
470
- // The machine says this store may have two pieces. Obeying that would leave
471
- // it unable to finish the read it is serving: every resident piece pinned,
472
- // zero bytes returned, and ffmpeg taking that for the end of the file —
473
- // which killed every encoder on that file in the field on 2026-08-15.
474
- const revised = store.reviseGrowthCeiling(2 * PIECE);
475
- assert.equal(revised.ceilingBytes, 10 * PIECE, "one whole window is the floor");
476
- assert.equal(revised.belowActiveDemand, true, "and the store says the share was smaller than that");
477
-
478
- // With no reader there is no window to protect and the share is obeyed.
479
- store.releaseProtection("video");
480
- const obeyed = store.reviseGrowthCeiling(2 * PIECE);
481
- assert.equal(obeyed.ceilingBytes, 2 * PIECE);
482
- assert.equal(obeyed.belowActiveDemand, false);
483
- } finally {
484
- store.destroy(() => undefined);
485
- await fs.rm(directory, { recursive: true, force: true, maxRetries: 10, retryDelay: 20 });
486
- }
487
- });
488
-
489
- test("the pool stays the size it is allowed to be, however many pieces pass through it", async () => {
490
- // The field failure of 2026-09-02, and the case none of the earlier checks
491
- // covered: an allowance far smaller than the number of pieces in flight.
492
- // Both paths that register a piece look first and then await — `put` for a
493
- // slot, a revival for the disk — and in that gap another caller can register
494
- // the same index. Overwriting the entry dropped the previous block without
495
- // returning it, so the pool's count climbed past its ceiling for ever and it
496
- // degenerated into a fresh block per piece. A store holding THREE pieces
497
- // reported 812 MB committed against 68 MB allowed, 739 blocks allocated and
498
- // 676 still alive, and the process was killed at 4.37 GB.
499
- const capacity = 4;
500
- const { store, directory } = await makeStore(capacity);
501
- try {
502
- // Concurrent, because that is what produces the race: several peers deliver
503
- // pieces of one torrent at the same time.
504
- for (let round = 0; round < 6; round += 1) {
505
- await Promise.all(
506
- Array.from({ length: 16 }, (unused, index) => put(store, index, pieceOf(index)))
507
- );
508
- // And read them back, which revives from disk and races registration the
509
- // other way about.
510
- await Promise.all([0, 3, 7, 11, 15].map((index) => get(store, index)));
511
- }
512
-
513
- const stats = store.stats();
514
- assert.equal(stats.blocksBeyondCeiling, 0, "the pool grew past what it is allowed to hold");
515
- assert.ok(
516
- stats.blocksAllocated <= capacity + stats.blocksFree,
517
- `pool of ${stats.blocksAllocated} blocks for ${capacity} slots and ${stats.blocksFree} spare`
518
- );
519
- assert.equal(stats.committedBytes, stats.blocksAllocated * PIECE);
520
-
521
- // Every piece still reads back as itself: a block returned to the pool
522
- // twice, or reused while somebody held it, shows up here as wrong bytes.
523
- for (let index = 0; index < 16; index += 1) {
524
- const bytes = await get(store, index);
525
- assert.ok(bytes.equals(pieceOf(index)), `piece ${index} came back changed`);
526
- }
527
- } finally {
528
- store.destroy(() => undefined);
529
- await fs.rm(directory, { recursive: true, force: true, maxRetries: 10, retryDelay: 20 });
530
- }
531
- });
532
-
533
- test("a piece wanted later than the one it would displace goes to disk instead", async () => {
534
- const capacity = 4;
535
- const { store, directory } = await makeStore(capacity);
536
- try {
537
- // A reader is at the start of the file and the store is full of what it
538
- // wants. Its window is pieces 0-3.
539
- store.protectRange("video", 0, 3);
540
- for (let index = 0; index < capacity; index += 1) {
541
- await put(store, index, pieceOf(index));
542
- }
543
- const before = store.stats().admittedToDisk;
544
-
545
- // A piece arrives from far ahead. It IS inside a window in the field case —
546
- // six readers covered the whole file — but it lies further from every read
547
- // head than the piece the store would have to evict for it. Admitting it
548
- // would write out the nearer piece and read that one back sooner.
549
- store.protectRange("far", 90, 99);
550
- await put(store, 95, pieceOf(95));
551
-
552
- assert.ok(
553
- store.stats().admittedToDisk > before,
554
- "the further piece was admitted to memory and the nearer one written out"
555
- );
556
- // And it still reads back as itself, from the disk it was put on.
557
- assert.ok((await get(store, 95)).equals(pieceOf(95)));
558
- for (let index = 0; index < capacity; index += 1) {
559
- assert.ok((await get(store, index)).equals(pieceOf(index)), `piece ${index} was lost`);
560
- }
561
- } finally {
562
- store.destroy(() => undefined);
563
- await fs.rm(directory, { recursive: true, force: true, maxRetries: 10, retryDelay: 20 });
564
- }
565
- });
566
-
567
- test("a piece the map wants more displaces one it wants less, however far away it is", async () => {
568
- const capacity = 4;
569
- const { store, directory } = await makeStore(capacity);
570
- try {
571
- // The store is full of the tail — wanted, but last of everything wanted.
572
- store.protectRange("map:tail", 0, 3, 3);
573
- for (let index = 0; index < capacity; index += 1) {
574
- await put(store, index, pieceOf(index));
575
- }
576
- const before = store.stats().admittedToDisk;
577
-
578
- // A piece arrives from far ahead in the file, so by distance to a read head
579
- // it loses to everything resident — and it is where a viewer is stopped, so
580
- // by the map it wins. The map decides; the distance separates only pieces
581
- // the map wants equally.
582
- store.protectRange("map:blocked", 90, 99, 0);
583
- await put(store, 95, pieceOf(95));
584
-
585
- assert.equal(
586
- store.stats().admittedToDisk,
587
- before,
588
- "the piece a viewer is stopped on was written to disk to keep the tail in memory"
589
- );
590
- assert.ok((await get(store, 95)).equals(pieceOf(95)));
591
- } finally {
592
- store.destroy(() => undefined);
593
- await fs.rm(directory, { recursive: true, force: true, maxRetries: 10, retryDelay: 20 });
594
- }
595
- });