@torrent-tv/proxy 2.89.16 → 2.89.18

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 (299) hide show
  1. package/README.md +14 -3
  2. package/package.json +10 -2
  3. package/routes/api/client-logs/post.js +9 -2
  4. package/server.js +0 -11
  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 -2373
  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 -138
  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/coalesce.test.js +0 -39
  97. package/test/completed-files.test.js +0 -115
  98. package/test/concurrent-cost.test.js +0 -148
  99. package/test/container-media-info.test.js +0 -228
  100. package/test/contention.test.js +0 -76
  101. package/test/core-dumps.test.js +0 -57
  102. package/test/coverage-follows-the-disk.test.js +0 -233
  103. package/test/coverage-map.test.js +0 -195
  104. package/test/cue-push-carries-what-the-walk-found.test.js +0 -58
  105. package/test/cut-times-timeline.test.js +0 -65
  106. package/test/cuts-follow-published-grid.test.js +0 -109
  107. package/test/data-channel-frame.test.js +0 -63
  108. package/test/data-channel-viewer-lifecycle.test.js +0 -193
  109. package/test/dead-torrent-handle.test.js +0 -52
  110. package/test/declared-rates.test.js +0 -116
  111. package/test/declared-tracks.test.js +0 -43
  112. package/test/decode-cost-fit.test.js +0 -202
  113. package/test/decode-cost.test.js +0 -475
  114. package/test/delivery-probe-field.test.js +0 -173
  115. package/test/delivery-probe.test.js +0 -382
  116. package/test/demand-register.test.js +0 -206
  117. package/test/dht-bootstrap.test.js +0 -72
  118. package/test/drain-threat.test.js +0 -65
  119. package/test/duplicate-add.test.js +0 -48
  120. package/test/encode-admission.test.js +0 -170
  121. package/test/encode-cost.test.js +0 -275
  122. package/test/encode-exit.test.js +0 -111
  123. package/test/encode-orchestrator.test.js +0 -426
  124. package/test/encode-plan-viewers.test.js +0 -725
  125. package/test/encode-plan.test.js +0 -545
  126. package/test/encode-run-state.test.js +0 -314
  127. package/test/encode-run.test.js +0 -248
  128. package/test/encode-slope.test.js +0 -46
  129. package/test/encoded-output.test.js +0 -39
  130. package/test/encoder-kinds.test.js +0 -122
  131. package/test/encoder-readings.test.js +0 -68
  132. package/test/episode-naming.test.js +0 -131
  133. package/test/every-claimant-is-told-its-share.test.js +0 -152
  134. package/test/failed-encoder-still-serves-what-exists.test.js +0 -354
  135. package/test/failed-start-breaker.test.js +0 -202
  136. package/test/fastest-wires.test.js +0 -143
  137. package/test/ffmpeg-stream-counts.test.js +0 -101
  138. package/test/file-edges.test.js +0 -191
  139. package/test/files-in-use.test.js +0 -34
  140. package/test/fixtures/audio-frame-boundary.json +0 -1
  141. package/test/fixtures/refused-audio-20261002.json +0 -10
  142. package/test/fmp4-presentation-clock.test.js +0 -148
  143. package/test/fmp4-self-contained.test.js +0 -80
  144. package/test/fmp4-timestamps.test.js +0 -140
  145. package/test/fmp4-track-completeness.test.js +0 -41
  146. package/test/format-keyed-outputs.test.js +0 -78
  147. package/test/health-metrics.test.js +0 -36
  148. package/test/held-read-ownership.test.js +0 -77
  149. package/test/held-request-width.test.js +0 -157
  150. package/test/helpers/encode-run.js +0 -248
  151. package/test/helpers/held-file.js +0 -77
  152. package/test/helpers/manager.js +0 -62
  153. package/test/helpers/matroska-file.js +0 -296
  154. package/test/helpers/output-spec.js +0 -63
  155. package/test/host-load.test.js +0 -68
  156. package/test/index-accuracy-is-about-the-file.test.js +0 -128
  157. package/test/init-compat.test.js +0 -219
  158. package/test/input-lost-quiets-the-plan.test.js +0 -261
  159. package/test/input-unavailable.test.js +0 -48
  160. package/test/installation-id.test.js +0 -39
  161. package/test/keeping-period.test.js +0 -83
  162. package/test/keyframe-index-accuracy.test.js +0 -188
  163. package/test/keyframe-table-budget.test.js +0 -123
  164. package/test/keyframes-belong-to-the-file.test.js +0 -249
  165. package/test/learned-median.test.js +0 -37
  166. package/test/letting-go-asks-who-is-watching.test.js +0 -191
  167. package/test/limit-row-by-area.test.js +0 -60
  168. package/test/link-budget.test.js +0 -111
  169. package/test/link-probe.test.js +0 -56
  170. package/test/local-encoding-data.test.js +0 -273
  171. package/test/logger-repeats.test.js +0 -134
  172. package/test/look-ahead-coverage.test.js +0 -56
  173. package/test/manager-surface.test.js +0 -291
  174. package/test/matroska-blocks.test.js +0 -0
  175. package/test/matroska-cluster-discovery.test.js +0 -323
  176. package/test/matroska-cues-track.test.js +0 -192
  177. package/test/media-time.test.js +0 -62
  178. package/test/memory-budget.test.js +0 -390
  179. package/test/move-cost.test.js +0 -216
  180. package/test/mp4-composition-times.test.js +0 -0
  181. package/test/mp4-subtitles.test.js +0 -173
  182. package/test/one-authority.test.js +0 -285
  183. package/test/one-budget.test.js +0 -149
  184. package/test/one-output-one-session.test.js +0 -273
  185. package/test/one-resource-divided.test.js +0 -185
  186. package/test/one-serving-output-per-height.test.js +0 -458
  187. package/test/orchestrator-wired.test.js +0 -207
  188. package/test/output-catalog.test.js +0 -39
  189. package/test/output-shape.test.js +0 -21
  190. package/test/output-spec.test.js +0 -251
  191. package/test/output-speed.test.js +0 -92
  192. package/test/outputs-being-prepared.test.js +0 -40
  193. package/test/packet-witness-ring.test.js +0 -236
  194. package/test/packet-witness.test.js +0 -148
  195. package/test/piece-completeness.test.js +0 -78
  196. package/test/piece-disk-store.test.js +0 -401
  197. package/test/piece-from-whole-file.test.js +0 -129
  198. package/test/piece-lru.test.js +0 -319
  199. package/test/piece-reader.test.js +0 -162
  200. package/test/piece-selection-offset.test.js +0 -85
  201. package/test/piece-store-eviction.test.js +0 -595
  202. package/test/piece-store-never-refuses.test.js +0 -153
  203. package/test/piece-store-reservations.test.js +0 -403
  204. package/test/piece-store-slow-disk.test.js +0 -159
  205. package/test/piece-tail.test.js +0 -97
  206. package/test/plan-host-timings.test.js +0 -68
  207. package/test/plan-is-steady.test.js +0 -225
  208. package/test/playback-readiness.test.js +0 -518
  209. package/test/playback-start-regressions.test.js +0 -101
  210. package/test/priority-map-download.test.js +0 -174
  211. package/test/priority-map-emptied.test.js +0 -204
  212. package/test/priority-map-per-output.test.js +0 -215
  213. package/test/priority-map.test.js +0 -163
  214. package/test/probe-wedge-certainty.test.js +0 -60
  215. package/test/produced-copy-choice.test.js +0 -213
  216. package/test/published-timeline.test.js +0 -83
  217. package/test/quality-offer.test.js +0 -160
  218. package/test/quality-variants.test.js +0 -1274
  219. package/test/rate-control-in-the-output.test.js +0 -181
  220. package/test/read-survives-withdrawal.test.js +0 -164
  221. package/test/read-window.test.js +0 -365
  222. package/test/reads-not-yet-arrived.test.js +0 -218
  223. package/test/resume-warm.test.js +0 -39
  224. package/test/run-graph-drift.test.js +0 -37
  225. package/test/run-inputs.test.js +0 -80
  226. package/test/run-intervals.test.js +0 -100
  227. package/test/run-position-follows-published-grid.test.js +0 -89
  228. package/test/run-progress.test.js +0 -64
  229. package/test/same-height-switch.test.js +0 -663
  230. package/test/seek-frees-the-viewers-requests.test.js +0 -217
  231. package/test/seek-landing.test.js +0 -109
  232. package/test/seek-target-not-superseded.test.js +0 -195
  233. package/test/segment-closed-on-both-branches.test.js +0 -114
  234. package/test/segment-cut-times.test.js +0 -63
  235. package/test/segment-demand.test.js +0 -80
  236. package/test/segment-hold-supersede.test.js +0 -91
  237. package/test/segment-judged-by-its-own-header.test.js +0 -222
  238. package/test/segment-serve-wiring.test.js +0 -481
  239. package/test/segment-store-eviction.test.js +0 -247
  240. package/test/segment-store.test.js +0 -352
  241. package/test/segment-true-start.test.js +0 -86
  242. package/test/segments-are-shared.test.js +0 -176
  243. package/test/send-chunk-bytes.test.js +0 -86
  244. package/test/serving-existing-output.test.js +0 -111
  245. package/test/serving-output.test.js +0 -102
  246. package/test/shared-piece-store.test.js +0 -310
  247. package/test/sidecar-naming.test.js +0 -142
  248. package/test/soundtrack-rate-bound.test.js +0 -289
  249. package/test/source-file.test.js +0 -133
  250. package/test/source-files-route.test.js +0 -113
  251. package/test/source-registry.test.js +0 -18
  252. package/test/split-a-stretch.test.js +0 -139
  253. package/test/stale-request-after-seek.test.js +0 -158
  254. package/test/startup-readings.test.js +0 -124
  255. package/test/stream-route.test.js +0 -237
  256. package/test/subtitle-cue-framing.test.js +0 -200
  257. package/test/subtitle-cue-source.test.js +0 -102
  258. package/test/subtitle-cue-walk.test.js +0 -385
  259. package/test/subtitle-cursor.test.js +0 -63
  260. package/test/subtitle-defaults.test.js +0 -118
  261. package/test/subtitle-language.test.js +0 -252
  262. package/test/subtitle-metadata.test.js +0 -15
  263. package/test/subtitle-plan-waits.test.js +0 -125
  264. package/test/subtitle-track-numbering.test.js +0 -391
  265. package/test/supply-margin.test.js +0 -190
  266. package/test/swarm-follows-readers.test.js +0 -174
  267. package/test/swarm-reach.test.js +0 -130
  268. package/test/swarm-selection.test.js +0 -220
  269. package/test/tail-duplication.test.js +0 -167
  270. package/test/the-channel-has-both-ends.test.js +0 -91
  271. package/test/the-torrent-thread-serves-bytes.test.js +0 -107
  272. package/test/thread-pool.test.js +0 -53
  273. package/test/timeline.test.js +0 -84
  274. package/test/torrent-contents.test.js +0 -235
  275. package/test/torrent-cost.test.js +0 -71
  276. package/test/torrent-files.test.js +0 -221
  277. package/test/torrent-naming.test.js +0 -255
  278. package/test/tracks-begin-together.test.js +0 -209
  279. package/test/tunnel-renewal.test.js +0 -167
  280. package/test/two-viewers-one-picture.test.js +0 -508
  281. package/test/upload-hurry.test.js +0 -186
  282. package/test/usrsctp-state.test.js +0 -131
  283. package/test/video-facts.test.js +0 -102
  284. package/test/viewer-assignments.test.js +0 -143
  285. package/test/viewer-outputs.test.js +0 -285
  286. package/test/viewer-presence.test.js +0 -116
  287. package/test/viewer-requests-admission.test.js +0 -92
  288. package/test/viewer-starts-on-map.test.js +0 -27
  289. package/test/viewer-states.test.js +0 -192
  290. package/test/viewer-subtitle-subscription.test.js +0 -96
  291. package/test/viewer.test.js +0 -139
  292. package/test/viewing-generations.test.js +0 -390
  293. package/test/visible-rung.test.js +0 -37
  294. package/test/wait-ledger.test.js +0 -100
  295. package/test/webrtc-shim.test.js +0 -149
  296. package/test/wedge-certainty.test.js +0 -131
  297. package/test/whole-file-held-read.test.js +0 -30
  298. package/test/withdraw-piece-claim.test.js +0 -212
  299. 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
- });