@blockcast/mmt-container 0.1.0 → 0.3.0-main.0bde85f7082f

package/dist/repair-fetch.js

@@ -0,0 +1,381 @@
+// src/block-policy.ts
+import { deriveFecInterleaveDepth } from "@blockcast/mmt-fec";
+function repairPriorityForClass(blockClass) {
+  switch (blockClass) {
+    case "keyframe":
+    case "unknown":
+      return 0;
+    case "audio":
+      return 1;
+    case "delta":
+      return 2;
+  }
+}
+
+// ../mmt-alta-parse/dist/index.js
+var MPU_HEADER_SIZE = 8;
+var MPU_LENGTH_FIELD_SIZE = 2;
+var MPU_HEADER_REMAINDER_SIZE = MPU_HEADER_SIZE - MPU_LENGTH_FIELD_SIZE;
+
+// ../mmt-base/dist/mmtp.js
+var MPU_HEADER_SIZE2 = 8;
+var MPU_LENGTH_FIELD_SIZE2 = 2;
+var MPU_HEADER_REMAINDER_SIZE2 = MPU_HEADER_SIZE2 - MPU_LENGTH_FIELD_SIZE2;
+
+// ../mmt-base/dist/ntp-short.js
+var NTP_SHORT_BITS = 32;
+var NTP_SHORT_MODULUS = 2 ** NTP_SHORT_BITS;
+var NTP_SHORT_HALF_RANGE = 2 ** (NTP_SHORT_BITS - 1);
+
+// ../mmt-base/dist/fec-block-profile.js
+var FEC_BLOCK_PROFILES = Object.freeze([
+  "k-padded-v1",
+  "iso-ssbg1-v1"
+]);
+
+// src/repair-layers.ts
+var REPAIR_PRIORITY_MIN = 192;
+
+// src/repair-fetch.ts
+var MOQT_PRIORITY_MAX = 255;
+var SOURCE_MEDIA_PRIORITY_MAX = REPAIR_PRIORITY_MIN - 1;
+function isMoqtPriority(value) {
+  return Number.isSafeInteger(value) && value >= 0 && value <= MOQT_PRIORITY_MAX;
+}
+function repairFetchSubscriberPriority(blockClass, target) {
+  if (repairPriorityForClass(blockClass) === 0) {
+    const source = target.sourcePriority;
+    if (source === null) return { kind: "omit", reason: "source-priority-absent" };
+    if (!isMoqtPriority(source)) return { kind: "omit", reason: "source-priority-invalid" };
+    return { kind: "carry", subscriberPriority: Math.min(source, SOURCE_MEDIA_PRIORITY_MAX) };
+  }
+  const repair = target.repairPriority;
+  if (repair === null) return { kind: "decline", reason: "repair-priority-absent" };
+  if (!isMoqtPriority(repair)) return { kind: "decline", reason: "repair-priority-invalid" };
+  return { kind: "carry", subscriberPriority: Math.max(repair, REPAIR_PRIORITY_MIN) };
+}
+function wireRepairFetch(mc, opts) {
+  if (!Number.isSafeInteger(opts.attemptLimit) || opts.attemptLimit < 1) {
+    throw new Error(
+      `[RepairFetch] attemptLimit=${String(opts.attemptLimit)} must be a positive integer`
+    );
+  }
+  if (typeof opts.reliableRttMs !== "function") {
+    throw new Error("[RepairFetch] reliableRttMs is required: repair admission needs the measured reliable-path RTT");
+  }
+  if (typeof opts.presentationDelayMs !== "function") {
+    throw new Error("[RepairFetch] presentationDelayMs is required: a repair FETCH is due by the block's presentation deadline");
+  }
+  const entries = /* @__PURE__ */ new Map();
+  const warnedNoTarget = /* @__PURE__ */ new Set();
+  let disposed = false;
+  let enqueueOrder = 0;
+  const requestKey = (sbn, packetId, catalogTrackName) => JSON.stringify([packetId, catalogTrackName ?? null, sbn]);
+  const noTargetKey = (packetId, catalogTrackName) => JSON.stringify([packetId, catalogTrackName ?? null]);
+  const clearRepair = (sbn, packetId, catalogTrackName) => {
+    if (catalogTrackName === void 0) mc.clearRepairForBlock(sbn, packetId);
+    else mc.clearRepairForBlock(sbn, packetId, catalogTrackName);
+  };
+  const note = (type, entry) => {
+    mc.noteRepairScheduling(type, entry.sbn, entry.packetId, entry.catalogTrackName);
+  };
+  const releaseHold = (entry) => {
+    if (entry.catalogTrackName === void 0) mc.fecManager.releaseRepairHold(entry.sbn, entry.packetId);
+    else mc.fecManager.releaseRepairHold(entry.sbn, entry.packetId, entry.catalogTrackName);
+  };
+  const stop = (entry, reason) => {
+    const run = entry.running;
+    if (!run) return;
+    entry.running = null;
+    run.stopped = reason;
+    run.controller.abort();
+    if (reason === "preempted") releaseHold(entry);
+  };
+  const readRtt = () => {
+    try {
+      const rtt = opts.reliableRttMs();
+      return Number.isFinite(rtt) && rtt > 0 ? rtt : null;
+    } catch {
+      return null;
+    }
+  };
+  const admit = (entry, now) => {
+    const budgetMs = entry.deadlineAt - now;
+    const rttMs = readRtt();
+    if (rttMs !== null && rttMs < budgetMs) return true;
+    retire(entry);
+    releaseHold(entry);
+    clearRepair(entry.sbn, entry.packetId, entry.catalogTrackName);
+    mc.noteRepairSkipped(
+      rttMs === null ? "rtt-unmeasured" : "rtt-exceeds-budget",
+      { rttMs, budgetMs },
+      entry.sbn,
+      entry.packetId,
+      entry.catalogTrackName
+    );
+    return false;
+  };
+  const retire = (entry) => {
+    if (entries.get(entry.key) === entry) entries.delete(entry.key);
+  };
+  const urgentOutstanding = () => {
+    for (const entry of entries.values()) {
+      if (entry.priority < 2) return true;
+    }
+    return false;
+  };
+  const preemptDeltas = () => {
+    for (const entry of entries.values()) {
+      if (entry.priority !== 2 || !entry.running) continue;
+      stop(entry, "preempted");
+      note("repair-preempted", entry);
+    }
+  };
+  const wirePriority = (entry, blockClass) => {
+    const derived = repairFetchSubscriberPriority(blockClass, entry.target);
+    if (derived.kind === "carry") return { subscriberPriority: derived.subscriberPriority };
+    mc.noteRepairPriority(
+      derived.kind === "omit" ? "omitted" : "declined",
+      derived.reason,
+      blockClass,
+      entry.sbn,
+      entry.packetId,
+      entry.catalogTrackName
+    );
+    return derived.kind === "omit" ? { subscriberPriority: void 0 } : null;
+  };
+  const start = (entry, counted = true) => {
+    if (!admit(entry, performance.now())) return;
+    if (counted) entry.attempts++;
+    const run = { controller: new AbortController(), stopped: null };
+    entry.running = run;
+    mc.fecManager.holdBlockForRepair(
+      entry.sbn,
+      entry.packetId,
+      entry.catalogTrackName,
+      entry.deadlineAt
+    );
+    void execute(entry, run);
+  };
+  const dispatch = () => {
+    if (disposed) return;
+    const now = performance.now();
+    const queued = [];
+    for (const entry of [...entries.values()]) {
+      if (entry.running) {
+        if (entry.deadlineAt <= now) {
+          stop(entry, "expired");
+          retire(entry);
+          clearRepair(entry.sbn, entry.packetId, entry.catalogTrackName);
+        }
+        continue;
+      }
+      if (entry.deadlineAt <= now) {
+        retire(entry);
+        if (entry.priority === 2 && entry.attempts === 0) note("repair-deferred", entry);
+        clearRepair(entry.sbn, entry.packetId, entry.catalogTrackName);
+        continue;
+      }
+      queued.push(entry);
+    }
+    for (const entry of queued) {
+      if (entry.priority < 2) start(entry);
+    }
+    if (urgentOutstanding()) return;
+    queued.filter((entry) => entry.priority === 2).sort((a, b) => a.deadlineAt - b.deadlineAt || a.order - b.order).forEach((entry) => start(entry));
+  };
+  const finish = (entry, run, fed, error) => {
+    if (run.stopped !== null || entry.running !== run || entries.get(entry.key) !== entry) {
+      return;
+    }
+    entry.running = null;
+    if (error === void 0) {
+      retire(entry);
+      if (fed === 0) {
+        releaseHold(entry);
+        clearRepair(entry.sbn, entry.packetId, entry.catalogTrackName);
+      }
+      dispatch();
+      return;
+    }
+    const retryable = fed === 0 && entry.attempts < opts.attemptLimit && entry.deadlineAt > performance.now() && opts.shouldRetry?.(error) === true;
+    if (retryable) {
+      dispatch();
+      return;
+    }
+    retire(entry);
+    if (fed === 0) releaseHold(entry);
+    clearRepair(entry.sbn, entry.packetId, entry.catalogTrackName);
+    console.warn(
+      `[RepairFetch] fetch failed pid=${entry.packetId} sbn=${entry.sbn} track=${entry.repairTrack}:`,
+      error
+    );
+    dispatch();
+  };
+  const blockProfileOf = (packetId) => {
+    const profile = mc.fecManager.blockProfileForPacket(packetId);
+    if (profile === void 0) {
+      throw new Error(`[RepairFetch] packetId=${packetId} has no configured fec.blockProfile`);
+    }
+    return profile;
+  };
+  const execute = async (entry, run) => {
+    let fed = 0;
+    try {
+      for await (const packet of opts.transport({
+        repairTrack: entry.repairTrack,
+        sbn: entry.sbn,
+        blockProfile: entry.blockProfile,
+        packetId: entry.packetId,
+        signal: run.controller.signal,
+        subscriberPriority: entry.subscriberPriority
+      })) {
+        if (run.stopped !== null || entry.running !== run) break;
+        fed++;
+        if (entry.catalogTrackName === void 0) {
+          mc.processRepairFromMoQ(packet, entry.packetId);
+        } else {
+          mc.processRepairFromMoQ(packet, entry.packetId, entry.catalogTrackName);
+        }
+      }
+      finish(entry, run, fed, void 0);
+    } catch (error) {
+      finish(entry, run, fed, error ?? new Error("repair transport rejected"));
+    }
+  };
+  const removeResetObserver = mc.addTrackResetObserver((packetId, catalogTrackName) => {
+    for (const entry of [...entries.values()]) {
+      if (entry.packetId !== packetId || entry.catalogTrackName !== catalogTrackName) continue;
+      retire(entry);
+      stop(entry, "reset");
+    }
+    warnedNoTarget.delete(noTargetKey(packetId, catalogTrackName));
+    dispatch();
+  });
+  const removeLifecycleObserver = mc.addRepairLifecycleObserver((event) => {
+    if (disposed) return;
+    if (event.type === "reclassified") {
+      const entry2 = entries.get(
+        requestKey(event.block.sbn, event.block.packetId, event.block.catalogTrackName ?? void 0)
+      );
+      if (!entry2 || entry2.priority !== 2) return;
+      const promoted = repairPriorityForClass(event.to);
+      if (promoted >= entry2.priority) return;
+      const wire = wirePriority(entry2, event.to);
+      if (wire === null) return;
+      entry2.priority = promoted;
+      entry2.subscriberPriority = wire.subscriberPriority;
+      if (entry2.running) {
+        stop(entry2, "reprioritized");
+        start(entry2, false);
+      }
+      preemptDeltas();
+      dispatch();
+      return;
+    }
+    if (event.type !== "recovered" && event.type !== "failed") return;
+    const entry = entries.get(
+      requestKey(event.block.sbn, event.block.packetId, event.block.catalogTrackName ?? void 0)
+    );
+    if (!entry) return;
+    retire(entry);
+    if (entry.running) stop(entry, "resolved");
+    else if (entry.priority === 2 && entry.attempts === 0) note("repair-deferred", entry);
+    dispatch();
+  });
+  const presentationDeadlineAt = (sbn, packetId, catalogTrackName, now) => {
+    const waitDeadlineAt = now + mc.fecManager.repairFetchTimeoutMsForBlock(sbn, packetId, catalogTrackName);
+    const anchor = mc.fecManager.blockAnchorAtMs(sbn, packetId, catalogTrackName);
+    if (anchor === void 0) return waitDeadlineAt;
+    let delayMs;
+    try {
+      delayMs = opts.presentationDelayMs(packetId, catalogTrackName);
+    } catch {
+      return null;
+    }
+    if (!(Number.isFinite(delayMs) && delayMs > 0)) return null;
+    const ceilingAt = anchor + mc.fecManager.terminalRetentionMsForPacket(packetId);
+    return Math.max(waitDeadlineAt, Math.min(anchor + delayMs, ceilingAt));
+  };
+  mc.onRepairSubscribe((sbn, packetId, catalogTrackName, blockClass) => {
+    if (disposed) {
+      clearRepair(sbn, packetId, catalogTrackName);
+      return;
+    }
+    const blockProfile = blockProfileOf(packetId);
+    const target = opts.resolveTarget(packetId, catalogTrackName);
+    if (!target) {
+      const warnKey = noTargetKey(packetId, catalogTrackName);
+      if (!warnedNoTarget.has(warnKey)) {
+        warnedNoTarget.add(warnKey);
+        console.warn(
+          `[RepairFetch] no repair target for pid=${packetId} sbn=${sbn}${catalogTrackName === void 0 ? "" : ` track=${catalogTrackName}`}; releasing without a fetch`
+        );
+      }
+      clearRepair(sbn, packetId, catalogTrackName);
+      return;
+    }
+    const key = requestKey(sbn, packetId, catalogTrackName);
+    const previous = entries.get(key);
+    if (previous) {
+      retire(previous);
+      stop(previous, "reset");
+    }
+    const identity = {
+      target,
+      sbn,
+      packetId,
+      ...catalogTrackName === void 0 ? {} : { catalogTrackName }
+    };
+    const wire = wirePriority(identity, blockClass);
+    if (wire === null) {
+      clearRepair(sbn, packetId, catalogTrackName);
+      return;
+    }
+    const now = performance.now();
+    const deadlineAt = presentationDeadlineAt(sbn, packetId, catalogTrackName, now);
+    if (deadlineAt === null) {
+      clearRepair(sbn, packetId, catalogTrackName);
+      mc.noteRepairSkipped(
+        "presentation-delay-unavailable",
+        { rttMs: readRtt(), budgetMs: 0 },
+        sbn,
+        packetId,
+        catalogTrackName
+      );
+      return;
+    }
+    const entry = {
+      key,
+      ...identity,
+      repairTrack: target.repairTrack,
+      blockProfile,
+      priority: repairPriorityForClass(blockClass),
+      subscriberPriority: wire.subscriberPriority,
+      deadlineAt,
+      order: enqueueOrder++,
+      attempts: 0,
+      running: null
+    };
+    entries.set(key, entry);
+    if (entry.priority < 2) preemptDeltas();
+    dispatch();
+  });
+  return () => {
+    disposed = true;
+    removeResetObserver();
+    removeLifecycleObserver();
+    for (const entry of [...entries.values()]) {
+      clearRepair(entry.sbn, entry.packetId, entry.catalogTrackName);
+      if (entry.running) releaseHold(entry);
+      stop(entry, "disposed");
+    }
+    entries.clear();
+  };
+}
+export {
+  SOURCE_MEDIA_PRIORITY_MAX,
+  repairFetchSubscriberPriority,
+  wireRepairFetch
+};
+//# sourceMappingURL=repair-fetch.js.map