@torrent-tv/proxy 2.57.0 → 2.57.1

package/package.json

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

package/services/container-index/matroska-subtitles.js

@@ -34,6 +34,29 @@ const ID_CODEC_PRIVATE = 0x63a2;
 const ID_LANGUAGE = 0x22b59c;
 const ID_NAME = 0x536e;
 const ID_FLAG_DEFAULT = 0x88;
+/**
+ * The rest of what a TrackEntry says about itself, RFC 9559 §5.1.4.1. Read
+ * because the file states them and a releaser's own wording in `Name` is the
+ * only thing we had before: "fors" and "SDH" in a menu were whatever text
+ * someone happened to type.
+ *
+ * `FlagEnabled` defaults to 1 and means "the track is usable"; a track that
+ * says 0 is counted but not offered. `FlagForced` applies only to subtitles and
+ * defaults to 0. `FlagHearingImpaired` is set "if and only if the track is
+ * suitable for users with hearing impairments". `FlagVisualImpaired`,
+ * `FlagOriginal` and `FlagCommentary` bear on the AUDIO choice and are read
+ * with that work, not here — see roadmap item 55.
+ */
+const ID_FLAG_ENABLED = 0xb9;
+const ID_FLAG_FORCED = 0x55aa;
+const ID_FLAG_HEARING_IMPAIRED = 0x55ab;
+/**
+ * The language as RFC 5646 writes it. The specification is a MUST: "If this
+ * element is used, then any Language elements used in the same TrackEntry MUST
+ * be ignored" — so where both are present, this one is the answer and the
+ * three-letter code is not.
+ */
+const ID_LANGUAGE_BCP47 = 0x22b59d;
 const ID_CUES = 0x1c53bb6b;
 const ID_CUE_POINT = 0xbb;
 const ID_CUE_TRACK_POSITIONS = 0xb7;
@@ -69,9 +92,18 @@ const TEXT_CODECS = new Set(["S_TEXT/UTF8", "S_TEXT/ASS", "S_TEXT/SSA"]);
  *   ever names. Text tracks alone are not a numbering: a file whose PGS track
  *   comes first would have every text track one lower here than in the browser.
  * @property {string} codecId
- * @property {string} language - The three-letter code the file declares.
+ * @property {string} language - The language the file declares: its RFC 5646
+ *   tag where it writes one, and the three-letter code otherwise. The
+ *   specification requires that order — where `LanguageBCP47` is present, the
+ *   `Language` element MUST be ignored.
+ * @property {string} languageBcp47 - The RFC 5646 tag alone, or "".
  * @property {string} name - What the file calls the track, if anything.
  * @property {boolean} isDefault
+ * @property {boolean} isForced - `FlagForced`: the track carries what a viewer
+ *   needs even when they asked for no subtitles — signs, and dialogue in
+ *   another language. It does NOT carry the film's own dialogue.
+ * @property {boolean} isHearingImpaired - `FlagHearingImpaired`: suitable for
+ *   viewers who cannot hear, so it carries non-speech sound as well as speech.
  * @property {string} codecPrivate - The ASS/SSA header, base64, or "".
  * @property {number[]} clusterPositions - File offsets of clusters whose cue
  *   points name this track, ascending. Empty when the file indexes only its
@@ -156,6 +188,12 @@ export async function readSubtitlePlan(readRange, fileSize) {
     // amounts to, and whether the file said anything at all.
     let isDefault = true;
     let declaresDefault = false;
+    // Defaults straight from RFC 9559: a track is usable and not forced unless
+    // the file says otherwise, and the impaired flags are absent until claimed.
+    let isEnabled = true;
+    let isForced = false;
+    let isHearingImpaired = false;
+    let languageBcp47 = "";
     for (const field of iterateElements(head, entry.dataOffset, entryEnd)) {
       if (field.id === ID_TRACK_NUMBER) {
         trackNumber = readUint(head, field.dataOffset, field.size);
@@ -165,11 +203,23 @@ export async function readSubtitlePlan(readRange, fileSize) {
         codecId = readString(head, field);
       } else if (field.id === ID_LANGUAGE) {
         language = readString(head, field);
+      } else if (field.id === ID_LANGUAGE_BCP47) {
+        languageBcp47 = readString(head, field);
       } else if (field.id === ID_NAME) {
         name = readString(head, field);
       } else if (field.id === ID_FLAG_DEFAULT) {
         isDefault = readUint(head, field.dataOffset, field.size) === 1;
         declaresDefault = true;
+      } else if (field.id === ID_FLAG_ENABLED) {
+        // An element written with zero length carries its default, which for
+        // this one is 1 — so an empty element must not read as "unusable", and
+        // neither must a value outside the declared 0-1 range. Only an explicit
+        // zero takes a track away.
+        isEnabled = field.size === 0 || readUint(head, field.dataOffset, field.size) !== 0;
+      } else if (field.id === ID_FLAG_FORCED) {
+        isForced = field.size > 0 && readUint(head, field.dataOffset, field.size) !== 0;
+      } else if (field.id === ID_FLAG_HEARING_IMPAIRED) {
+        isHearingImpaired = field.size > 0 && readUint(head, field.dataOffset, field.size) !== 0;
       } else if (field.id === ID_CODEC_PRIVATE) {
         codecPrivate = head.toString("base64", field.dataOffset, field.dataOffset + field.size);
       }
@@ -177,17 +227,46 @@ export async function readSubtitlePlan(readRange, fileSize) {
     if (type !== TRACK_TYPE_SUBTITLE || trackNumber === null) {
       continue;
     }
-    declared.push({ trackNumber, codecId, language, name, isDefault, declaresDefault });
-    if (!TEXT_CODECS.has(codecId)) {
+    // A track the file marks unusable is still COUNTED. FlagEnabled says "the
+    // track is usable", and a player should not offer it — but ffmpeg does not
+    // drop it: `matroskadec.c` parses `MATROSKA_ID_TRACKFLAGENABLED` as
+    // `EBML_NONE`, reading the element and keeping nothing, so the stream is
+    // created and numbered like any other. Leaving it out of this list would
+    // therefore shift `declaredIndex` off ffmpeg's `0:s:N` for every track
+    // after it, which is the numbering defect this file was fixed for a day
+    // earlier. It is counted here and refused where it is offered instead.
+    //
+    // `language` here stays the three-letter code, because this list exists to
+    // be lined up against ffmpeg's banner, which prints that code. The RFC 5646
+    // tag rides beside it for whoever displays the track.
+    declared.push({
+      trackNumber,
+      codecId,
+      language,
+      languageBcp47,
+      name,
+      isDefault,
+      declaresDefault,
+      isEnabled,
+      isForced,
+      isHearingImpaired
+    });
+    if (!TEXT_CODECS.has(codecId) || !isEnabled) {
       continue;
     }
     tracks.push({
       trackNumber,
       declaredIndex: declared.length - 1,
       codecId,
-      language,
+      // This list is ours and is not compared with ffmpeg's, so it carries the
+      // language the file states most precisely: where RFC 5646 is written, the
+      // three-letter code MUST be ignored.
+      language: languageBcp47 || language,
+      languageBcp47,
       name,
       isDefault,
+      isForced,
+      isHearingImpaired,
       codecPrivate,
       clusterPositions: []
     });

package/services/delivery-probe.js

@@ -58,16 +58,33 @@ export const PROBE_INTERVAL_MS = 500;
  * bytes away. Add one round trip for the echo to come back. A probe is behind
  * only when it is later than that.
  *
- * @param {{ queuedBytes: number, bytesPerSecond: number, rttMs: number, intervalMs?: number }} state
+ * There is a third term, and leaving it out made this worse than the constant
+ * it replaced. The browser answers on ITS own schedule, not ours: it batches
+ * what it has seen and echoes on a timer, and that timer is throttled to about
+ * once a second whenever the tab is hidden. So with an empty queue the
+ * allowance collapsed to one probe and the bound to half a second, while echoes
+ * legitimately arrived every second - measured 2026-08-27, 67 `association-
+ * stopped` and 66 `reverse-direction-gone` against 84 `flowing` on a connection
+ * carrying 3.4 MB/s with every queue at zero. The peer's own cadence is
+ * measurable on the same connection, so it is measured and added rather than
+ * assumed.
+ *
+ * @param {{ queuedBytes: number, bytesPerSecond: number, rttMs: number, echoIntervalMs?: number, intervalMs?: number }} state
  * @returns {number | null} Probes that may legitimately be outstanding, or null
  *   when no rate has been measured yet and nothing can be said.
  */
-export function allowedGap({ queuedBytes, bytesPerSecond, rttMs, intervalMs = PROBE_INTERVAL_MS }) {
+export function allowedGap({
+  queuedBytes,
+  bytesPerSecond,
+  rttMs,
+  echoIntervalMs = 0,
+  intervalMs = PROBE_INTERVAL_MS
+}) {
   if (!(bytesPerSecond > 0) || !(intervalMs > 0)) {
     return null;
   }
   const drainMs = (Math.max(queuedBytes, 0) / bytesPerSecond) * 1000;
-  const waitMs = drainMs + Math.max(rttMs, 0);
+  const waitMs = drainMs + Math.max(rttMs, 0) + Math.max(echoIntervalMs, 0);
   // At least one: a probe sent and not yet echoed is the ordinary state.
   return Math.max(1, Math.ceil(waitMs / intervalMs));
 }
@@ -231,7 +248,13 @@ export function createDeliveryProbe({ log, intervalMs = PROBE_INTERVAL_MS, readD
       } catch {
         queuedBytes = 0;
       }
-      const allowance = allowedGap({ queuedBytes, bytesPerSecond, rttMs, intervalMs });
+      const allowance = allowedGap({
+        queuedBytes,
+        bytesPerSecond,
+        rttMs,
+        echoIntervalMs: connection.echoIntervalMs,
+        intervalMs
+      });
       // Several channels can carry one label only in malformed cases; the
       // larger allowance is the safer of the two.
       const held = allowed.get(label);
@@ -252,7 +275,9 @@ export function createDeliveryProbe({ log, intervalMs = PROBE_INTERVAL_MS, readD
       echoes: connection.echoes,
       echoAgeMs: connection.echoAt === 0 ? null : now - connection.echoAt,
       allowed,
-      echoStaleMs: widest > 0 ? widest * intervalMs + rttMs : 0
+      // Same arithmetic for the echo's own age: the peer cannot answer sooner
+      // than its own cadence allows, and a hidden tab's is about a second.
+      echoStaleMs: widest > 0 ? widest * intervalMs + rttMs + connection.echoIntervalMs : 0
     });
     if (verdict !== connection.verdict || now - connection.reportedAt >= REPORT_INTERVAL_MS) {
       connection.verdict = verdict;
@@ -268,6 +293,10 @@ export function createDeliveryProbe({ log, intervalMs = PROBE_INTERVAL_MS, readD
         connection = {
           id: sessionId,
           tag,
+          // The longest this peer has ever taken between two echoes. Its own
+          // schedule, measured rather than assumed - a hidden tab answers
+          // about once a second because the browser throttles the timer.
+          echoIntervalMs: 0,
           channels: new Map(),
           seq: 0,
           sentAt: 0,
@@ -321,7 +350,14 @@ export function createDeliveryProbe({ log, intervalMs = PROBE_INTERVAL_MS, readD
           }
         }
       }
-      connection.echoAt = Date.now();
+      const now = Date.now();
+      if (connection.echoAt !== 0) {
+        const sinceLast = now - connection.echoAt;
+        if (sinceLast > connection.echoIntervalMs) {
+          connection.echoIntervalMs = sinceLast;
+        }
+      }
+      connection.echoAt = now;
       connection.echoes += 1;
     },
 

package/services/subtitle-defaults.js

@@ -95,7 +95,20 @@ export function mergeContainerSubtitleFlags(bannerTracks, declared) {
   const banner = Array.isArray(bannerTracks) ? bannerTracks : [];
   const container = Array.isArray(declared) ? declared : [];
   const undecided = () => ({
-    tracks: banner.map((track) => ({ ...track, declaresDefault: false }))
+    // The container reading could not be lined up, so nothing of it is used —
+    // including the flags, which would otherwise be attributed to the wrong
+    // track.
+    tracks: banner.map((track) => ({
+      ...track,
+      declaresDefault: false,
+      isForced: false,
+      isHearingImpaired: false,
+      // Not "the container says this track is unusable" — nothing of the
+      // container is being used here. A track is offered unless it was read to
+      // say otherwise.
+      isEnabled: true,
+      languageBcp47: ""
+    }))
   });
   if (container.length === 0) {
     return { ...undecided(), aligned: false, reason: "the container declares no subtitle track" };
@@ -123,7 +136,20 @@ export function mergeContainerSubtitleFlags(bannerTracks, declared) {
     tracks: banner.map((track, order) => ({
       ...track,
       isDefault: container[order].isDefault === true,
-      declaresDefault: container[order].declaresDefault === true
+      declaresDefault: container[order].declaresDefault === true,
+      // Read from the file rather than guessed from the track's name. Both are
+      // stated by the container itself (RFC 9559 §5.1.4.1) and neither reaches
+      // ffmpeg's `-i` banner, which is where every other field here comes from.
+      isForced: container[order].isForced === true,
+      isHearingImpaired: container[order].isHearingImpaired === true,
+      // FlagEnabled, so the browser can leave an unusable track out of the
+      // menu. It stays in this list and keeps its number: ffmpeg creates a
+      // stream for it either way.
+      isEnabled: container[order].isEnabled !== false,
+      // The RFC 5646 tag, where the file writes one. Kept beside the code
+      // rather than replacing it: what this list is aligned against is ffmpeg's
+      // banner, which prints the three-letter form.
+      languageBcp47: typeof container[order].languageBcp47 === "string" ? container[order].languageBcp47 : ""
     })),
     aligned: true,
     reason: ""

package/test/delivery-probe.test.js

@@ -122,3 +122,37 @@ test("a burst big enough to explain the lag is not called a stopped association"
   );
   assert.equal(verdict, "flowing");
 });
+
+test("the peer's own answering cadence counts toward the allowance", () => {
+  // Field case 2026-08-27: queues empty, 3.4 MB/s crossing, tab hidden so the
+  // browser echoed about once a second. Without the peer's cadence the
+  // allowance is one probe and every other line read `association-stopped`.
+  const withoutCadence = allowedGap({
+    queuedBytes: 0,
+    bytesPerSecond: 3.4 * 1024 * 1024,
+    rttMs: 9
+  });
+  assert.equal(withoutCadence, 1);
+  const withCadence = allowedGap({
+    queuedBytes: 0,
+    bytesPerSecond: 3.4 * 1024 * 1024,
+    rttMs: 9,
+    echoIntervalMs: 1000
+  });
+  assert.ok(withCadence >= 3, `a second of cadence must allow more than ${withCadence}`);
+  const allowed = Object.fromEntries(ALL.map((label) => [label, withCadence]));
+  const { verdict } = readProbeState(
+    state({ proxy: 98, "proxy-control": 98, "proxy-fast": 98 }, { allowed, echoAgeMs: 977 })
+  );
+  assert.equal(verdict, "flowing");
+});
+
+test("a stale echo is judged against the peer's cadence, not a fixed half second", () => {
+  // The same numbers with the cadence unknown must still be able to say the
+  // reverse direction is gone — the bound rises with the cadence, it does not
+  // disappear.
+  const { verdict } = readProbeState(
+    state({ proxy: 99, "proxy-control": 99, "proxy-fast": 99 }, { echoAgeMs: 60_000, echoStaleMs: 2000 })
+  );
+  assert.equal(verdict, "reverse-direction-gone");
+});

package/test/subtitle-track-numbering.test.js

@@ -37,6 +37,10 @@ const ID_TRACK_NUMBER = 0xd7;
 const ID_TRACK_TYPE = 0x83;
 const ID_CODEC_ID = 0x86;
 const ID_LANGUAGE = 0x22b59c;
+const ID_LANGUAGE_BCP47 = 0x22b59d;
+const ID_FLAG_ENABLED = 0xb9;
+const ID_FLAG_FORCED = 0x55aa;
+const ID_FLAG_HEARING_IMPAIRED = 0x55ab;
 const ID_CUES = 0x1c53bb6b;
 const ID_CUE_POINT = 0xbb;
 const ID_CUE_TIME = 0xb3;
@@ -95,13 +99,26 @@ function uint32Element(id, value) {
   return element(id, payload);
 }
 
-function trackEntry({ number, type, codecId, language }) {
-  return element(ID_TRACK_ENTRY, Buffer.concat([
+function trackEntry({ number, type, codecId, language, flags = {}, languageBcp47 = null }) {
+  const parts = [
     uintElement(ID_TRACK_NUMBER, number),
     uintElement(ID_TRACK_TYPE, type),
     stringElement(ID_CODEC_ID, codecId),
     stringElement(ID_LANGUAGE, language)
-  ]));
+  ];
+  if (languageBcp47 !== null) {
+    parts.push(stringElement(ID_LANGUAGE_BCP47, languageBcp47));
+  }
+  for (const [id, value] of [
+    [ID_FLAG_ENABLED, flags.enabled],
+    [ID_FLAG_FORCED, flags.forced],
+    [ID_FLAG_HEARING_IMPAIRED, flags.hearingImpaired]
+  ]) {
+    if (value !== undefined) {
+      parts.push(uintElement(id, value ? 1 : 0));
+    }
+  }
+  return element(ID_TRACK_ENTRY, Buffer.concat(parts));
 }
 
 /**
@@ -260,3 +277,94 @@ test("two walks of one file at the same time read each cluster once", async () =
   );
   forgetSubtitles(sourceKey);
 });
+
+/**
+ * A file whose subtitle tracks carry the flags RFC 9559 defines for them: one
+ * forced, one for viewers who cannot hear, one the file marks unusable, and one
+ * writing its language as RFC 5646 alongside the three-letter code.
+ *
+ * @returns {Buffer}
+ */
+function fileWithFlags() {
+  const info = element(ID_INFO, uintElement(ID_TIMESTAMP_SCALE, 1_000_000));
+  const tracks = element(ID_TRACKS, Buffer.concat([
+    trackEntry({ number: 1, type: 1, codecId: "V_MPEG4/ISO/AVC", language: "und" }),
+    trackEntry({ number: 2, type: 17, codecId: "S_TEXT/UTF8", language: "rus", flags: { forced: true } }),
+    trackEntry({ number: 3, type: 17, codecId: "S_TEXT/UTF8", language: "eng", flags: { hearingImpaired: true } }),
+    trackEntry({ number: 4, type: 17, codecId: "S_TEXT/UTF8", language: "fre", flags: { enabled: false } }),
+    trackEntry({ number: 5, type: 17, codecId: "S_TEXT/ASS", language: "por", languageBcp47: "pt-BR" })
+  ]));
+  const seekEntry = (targetId, position) => element(ID_SEEK, Buffer.concat([
+    element(ID_SEEK_ID, idBytes(targetId)),
+    uint32Element(ID_SEEK_POSITION, position)
+  ]));
+  const seekHeadWith = (infoAt, tracksAt) => element(ID_SEEK_HEAD, Buffer.concat([
+    seekEntry(ID_INFO, infoAt),
+    seekEntry(ID_TRACKS, tracksAt)
+  ]));
+  const headLength = seekHeadWith(0, 0).length;
+  const segmentPayload = Buffer.concat([
+    seekHeadWith(headLength, headLength + info.length),
+    info,
+    tracks
+  ]);
+  const ebml = element(ID_EBML, Buffer.from([0x42, 0x86, 0x81, 0x01]));
+  return Buffer.concat([ebml, element(ID_SEGMENT, segmentPayload)]);
+}
+
+test("the flags the file states about a track are read, not guessed from its name", async () => {
+  const plan = await readSubtitlePlan(readerOver(fileWithFlags()), fileWithFlags().length);
+
+  const forced = plan.tracks.find((track) => track.trackNumber === 2);
+  assert.equal(forced.isForced, true, "FlagForced 0x55AA");
+  assert.equal(forced.isHearingImpaired, false);
+
+  const sdh = plan.tracks.find((track) => track.trackNumber === 3);
+  assert.equal(sdh.isHearingImpaired, true, "FlagHearingImpaired 0x55AB");
+  assert.equal(sdh.isForced, false);
+});
+
+test("a track the file marks unusable is not offered, but is still counted", async () => {
+  // FlagEnabled (0xB9): "Set to 1 if the track is usable." Track 4 says 0, so
+  // it is not offered — but it KEEPS its place in the numbering, because ffmpeg
+  // keeps it: `matroskadec.c` parses MATROSKA_ID_TRACKFLAGENABLED as EBML_NONE,
+  // reading the element and storing nothing, so the stream is created and gets
+  // its own `0:s:N`. Dropping it here would shift every track after it.
+  const plan = await readSubtitlePlan(readerOver(fileWithFlags()), fileWithFlags().length);
+
+  assert.equal(plan.tracks.some((track) => track.trackNumber === 4), false, "not offered for extraction");
+  const counted = plan.declared.find((track) => track.trackNumber === 4);
+  assert.ok(counted, "still declared, so the numbering does not move");
+  assert.equal(counted.isEnabled, false);
+});
+
+test("an unusable track keeps its place, so the tracks after it keep theirs", async () => {
+  const plan = await readSubtitlePlan(readerOver(fileWithFlags()), fileWithFlags().length);
+
+  // s:0 forced, s:1 SDH, s:2 the unusable one, s:3 the Brazilian track.
+  assert.deepEqual(
+    plan.tracks.map((track) => [track.trackNumber, track.declaredIndex]),
+    [[2, 0], [3, 1], [5, 3]]
+  );
+});
+
+test("the list ffmpeg is lined up against still speaks ffmpeg's language codes", async () => {
+  // `declared` exists to be paired with the `-i` banner, which prints the
+  // three-letter code; reporting "pt-BR" there would break the pairing and cost
+  // the FlagDefault reading with it.
+  const plan = await readSubtitlePlan(readerOver(fileWithFlags()), fileWithFlags().length);
+
+  const declared = plan.declared.find((track) => track.trackNumber === 5);
+  assert.equal(declared.language, "por");
+  assert.equal(declared.languageBcp47, "pt-BR");
+});
+
+test("where the file writes RFC 5646, that is the language", async () => {
+  // "If this element is used, then any Language elements used in the same
+  // TrackEntry MUST be ignored."
+  const plan = await readSubtitlePlan(readerOver(fileWithFlags()), fileWithFlags().length);
+
+  const track = plan.tracks.find((entry) => entry.trackNumber === 5);
+  assert.equal(track.language, "pt-BR", "not the three-letter por");
+  assert.equal(track.languageBcp47, "pt-BR");
+});