@blockcast/mmt-container 2.0.0 → 2.0.1-main.0f2de6af487b

package/README.md

@@ -277,7 +277,7 @@ per-commit `0.1.0-main.<sha>` prerelease from `stamp-prerelease.mjs`), and a
 > Superseded by BLO-40665. Every package is now bumped in lockstep by a `v*`
 > tag and the sibling ranges move with it, so the objection above no longer
 > applies -- it was an argument against bumping *one* package. The set is at
-> `2.0.0`; see `RELEASES.md`.
+> `2.0.1`; see `RELEASES.md`.
 
 #### Track-role convention (Phase 14)
 

package/dist/browser-runtime.js

@@ -8514,6 +8514,9 @@ var AMTGatewayManager = class {
    */
   async subscribe(config) {
     const { key } = config;
+    if (config.protected) {
+      throw new Error("AMTGatewayManager refuses a protected join: it reports no per-datagram sender (multicast-02 7.2.7)");
+    }
     const keyStr = this.getKeyString(key);
     if (this.subscriptions.has(keyStr)) {
       console.log(`[AMT] Reusing existing subscription to ${keyStr}`);
@@ -21977,7 +21980,6 @@ _RistrettoPoint.Fn = /* @__PURE__ */ (() => Fn)();
 var BCPV2_LEAD_BOUND_MS = 5e3;
 var REPLAY_WINDOW = 64n;
 var BUCKET_DEPTH = 64;
-var BUCKET_RATE_PER_MS = 1;
 var hex = (bytes) => Array.from(bytes, (b) => b.toString(16).padStart(2, "0")).join("");
 function sameBytes(a, b) {
   if (a.byteLength !== b.byteLength)
@@ -22006,6 +22008,10 @@ var BcProvenanceV2Receiver = class {
   verifySig;
   accepted;
   queueLimit;
+  /** Octets a held datagram is charged beyond its payload: the IPv4 or IPv6 plus UDP headers (step 2). */
+  headerOctets;
+  /** Budget refill, tokens per ms: V / 1000 (step 1). */
+  bucketRatePerMs;
   current = null;
   previous = null;
   graceStart = {};
@@ -22051,6 +22057,8 @@ var BcProvenanceV2Receiver = class {
       multicast: this.maxAuthDelayMs * bandwidth / 8e3,
       unicast: (this.maxAuthDelayMs + this.widenMs) * bandwidth / 8e3
     };
+    this.headerOctets = parseBcProvenanceV2Address(cfg.endpoint.groupAddress).byteLength === 16 ? 48 : 28;
+    this.bucketRatePerMs = Math.max(1e3, 1.25 * bandwidth / (8 * 512 * 37)) / 1e3;
     const t = this.now();
     this.buckets = {
       multicast: { tokens: BUCKET_DEPTH, last: t, dropped: 0 },
@@ -22149,7 +22157,7 @@ var BcProvenanceV2Receiver = class {
       arrival: now,
       sent,
       digest: hex(sha2562(bytes)),
-      pairs: record.digests.map((d, i) => ({ digest: hex(d), seq: record.firstSeq + BigInt(i), admitted: false })),
+      pairs: record.digests.map((d, i) => ({ digest: hex(d), epoch, seq: record.firstSeq + BigInt(i), admitted: false })),
       awaitingMulticast: path === "mirror"
     };
     this.verified.set(id, entry);
@@ -22216,12 +22224,12 @@ var BcProvenanceV2Receiver = class {
   digest(datagram) {
     return hex(bcProvenanceV2DatagramDigest(this.cfg.endpoint, datagram));
   }
-  /** Consume the lowest-seq pending entry for `digest`, admitting it. */
+  /** Consume the pending entry for `digest` lowest in (epoch, sequence) order, admitting it. */
   consumePending(digest, now) {
     const list = this.pending.get(digest);
     if (!list?.length)
       return false;
-    list.sort((a, b) => a.pair.seq < b.pair.seq ? -1 : a.pair.seq > b.pair.seq ? 1 : 0);
+    list.sort((a, b) => a.pair.epoch - b.pair.epoch || (a.pair.seq < b.pair.seq ? -1 : a.pair.seq > b.pair.seq ? 1 : 0));
     const hit = list.shift();
     if (list.length === 0)
       this.pending.delete(digest);
@@ -22230,14 +22238,18 @@ var BcProvenanceV2Receiver = class {
     this.admittedUntil.set(digest, now + this.maxAuthDelayMs + this.leadMs);
     return true;
   }
+  /** A held datagram's charge against its queue: payload plus IP and UDP headers. */
+  charge(held) {
+    return held.datagram.byteLength + this.headerOctets;
+  }
   enqueue(held, path, now) {
-    if (this.holdBytes[path] + held.datagram.byteLength > this.queueLimit[path]) {
+    if (this.holdBytes[path] + this.charge(held) > this.queueLimit[path]) {
       return { verdict: "overflow", admitted: [] };
     }
     held.expiry = now + this.maxAuthDelayMs + (path === "unicast" ? this.widenMs : 0);
     held.order = this.order++;
     this.hold[path].push(held);
-    this.holdBytes[path] += held.datagram.byteLength;
+    this.holdBytes[path] += this.charge(held);
     return { verdict: "held", admitted: [] };
   }
   /** Remove and return the oldest held datagram with `digest`, across both queues. */
@@ -22252,7 +22264,7 @@ var BcProvenanceV2Receiver = class {
     if (!best)
       return void 0;
     const [held] = this.hold[best.path].splice(best.index, 1);
-    this.holdBytes[best.path] -= held.datagram.byteLength;
+    this.holdBytes[best.path] -= this.charge(held);
     return held.datagram;
   }
   dropAdmittedHeld() {
@@ -22260,7 +22272,7 @@ var BcProvenanceV2Receiver = class {
       this.hold[path] = this.hold[path].filter((h) => {
         const keep = h.digest === void 0 || !this.admittedUntil.has(h.digest);
         if (!keep)
-          this.holdBytes[path] -= h.datagram.byteLength;
+          this.holdBytes[path] -= this.charge(h);
         return keep;
       });
     }
@@ -22344,7 +22356,7 @@ var BcProvenanceV2Receiver = class {
   }
   take(path, now) {
     const b = this.buckets[path];
-    b.tokens = Math.min(BUCKET_DEPTH, b.tokens + (now - b.last) * BUCKET_RATE_PER_MS);
+    b.tokens = Math.min(BUCKET_DEPTH, b.tokens + (now - b.last) * this.bucketRatePerMs);
     b.last = now;
     if (b.tokens < 1) {
       b.dropped++;
@@ -22358,7 +22370,7 @@ var BcProvenanceV2Receiver = class {
       this.hold[path] = this.hold[path].filter((h) => {
         if (h.expiry > now)
           return true;
-        this.holdBytes[path] -= h.datagram.byteLength;
+        this.holdBytes[path] -= this.charge(h);
         this.expired[path]++;
         return false;
       });
@@ -22635,6 +22647,14 @@ var MmtpRouter = class {
   #packetIdRoles = /* @__PURE__ */ new Map();
   /** Explicit catalog ownership for dedicated repair-track packet IDs. */
   #repairOwnersByPacketId = /* @__PURE__ */ new Map();
+  /** Keyframe-overlay repair PID → the source its FEC instance protects
+   *  (draft-ramadan-mmt-fec-02 7.4.1). Never an owner in
+   *  #repairOwnersByPacketId: the overlay is decoded as its own instance. */
+  #overlayLegs = /* @__PURE__ */ new Map();
+  /** Keyframe-overlay repair track names, which name a leg too: a catalog
+   *  may state no PID for it (learned at subscribe time). */
+  #overlayRepairNames = /* @__PURE__ */ new Map();
+  #overlayStats = { repairDropped: 0, ownerRefused: 0 };
   /** Callback fired when a delta-track FEC block completes or fails. */
   #onDeltaBlockCompleteCb = null;
   // Debug counters
@@ -23153,13 +23173,53 @@ var MmtpRouter = class {
   /** Replace catalog-derived repair ownership before a catalog reconfiguration. */
   clearRepairPacketIdOwners() {
     this.#repairOwnersByPacketId.clear();
+    this.#overlayLegs.clear();
+    this.#overlayRepairNames.clear();
   }
-  /** Bind one dedicated repair-track PID to its authoritative media PID. */
+  /** Bind one dedicated repair-track PID to its authoritative media PID. A
+   *  known keyframe-overlay PID is refused, and counted: its symbols belong to
+   *  the overlay instance, never to the source's base decoder (mmt-02 7.4.4). */
   setRepairPacketIdOwner(repairPacketId, ownerPacketId) {
+    if (this.#overlayLegs.has(repairPacketId)) {
+      this.#overlayStats.ownerRefused++;
+      return;
+    }
     const owners = this.#repairOwnersByPacketId.get(repairPacketId) ?? /* @__PURE__ */ new Set();
     owners.add(ownerPacketId);
     this.#repairOwnersByPacketId.set(repairPacketId, owners);
   }
+  /**
+   * Record a keyframe-overlay repair leg (draft-ramadan-mmt-fec-02 7.4): its
+   * PID, the source it protects, and its repair track name. Either one names
+   * the leg, so a catalog that states no PID (learned at subscribe time) is
+   * covered by the name. Overlay repair is then never resolved to a base
+   * owner, on multicast or MoQ. Cleared with the catalog owners
+   * (`clearRepairPacketIdOwners`).
+   */
+  setKeyframeOverlayLeg(repairPacketId, leg) {
+    if (leg.repairTrackName !== void 0) this.#overlayRepairNames.set(leg.repairTrackName, { ...leg });
+    if (repairPacketId === void 0) return;
+    this.#repairOwnersByPacketId.delete(repairPacketId);
+    this.#overlayLegs.set(repairPacketId, { ...leg });
+  }
+  /** The keyframe-overlay leg registered on `repairPacketId`, if any. */
+  keyframeOverlayLeg(repairPacketId) {
+    return this.#overlayLegs.get(repairPacketId);
+  }
+  /** Overlay repair dropped for want of an overlay instance, and base-owner
+   *  registrations refused on an overlay PID. */
+  get keyframeOverlayStats() {
+    return { ...this.#overlayStats };
+  }
+  #isOverlayRepair(repairPacketId, repairTrackName) {
+    return this.#overlayLegs.has(repairPacketId) || repairTrackName !== void 0 && this.#overlayRepairNames.has(repairTrackName);
+  }
+  /** Overlay repair has no decoder until the overlay instance lands
+   *  (BLO-52077 PR 2): drop it before any base owner, locator or decoder. */
+  #dropOverlayRepair(repairPacketId) {
+    this.#overlayStats.repairDropped++;
+    debugRouter(`[MmtpRouter] Dropping keyframe-overlay repair pid=${repairPacketId}: no overlay instance`);
+  }
   /**
    * Register callback fired when a delta-track FEC block completes or fails.
    *
@@ -23583,6 +23643,10 @@ var MmtpRouter = class {
       return;
     }
     const repairPacketId = header.packetId;
+    if (this.#isOverlayRepair(repairPacketId, repairTrackName)) {
+      this.#dropOverlayRepair(repairPacketId);
+      return;
+    }
     const hintedOwner = ownerPacketIdHint != null && this.#classifyPacketId(ownerPacketIdHint) !== null ? ownerPacketIdHint : null;
     const ownerPacketId = hintedOwner ?? (this.#classifyPacketId(repairPacketId) !== null ? repairPacketId : null);
     if (ownerPacketId === null) {
@@ -23958,6 +24022,13 @@ var MmtpRouter = class {
     this.#packetIdRoles.delete(packetId);
     this.#catalogTrackNamesByPacketId.delete(packetId);
     this.#repairOwnersByPacketId.delete(packetId);
+    this.#overlayLegs.delete(packetId);
+    for (const [repairPacketId, leg] of [...this.#overlayLegs]) {
+      if (leg.sourcePacketId === packetId) this.#overlayLegs.delete(repairPacketId);
+    }
+    for (const [name, leg] of [...this.#overlayRepairNames]) {
+      if (leg.sourcePacketId === packetId) this.#overlayRepairNames.delete(name);
+    }
     delete this.#pidCounts[packetId];
     delete this.#repairPidCounts[packetId];
     delete this.#moqRepairPidCounts[packetId];
@@ -24196,6 +24267,8 @@ var MmtpRouter = class {
     this.#parserDiagnostics.clear();
     this.#catalogTrackNamesByPacketId.clear();
     this.#repairOwnersByPacketId.clear();
+    this.#overlayLegs.clear();
+    this.#overlayRepairNames.clear();
     for (const { receiver } of this.#provenance.values()) receiver.release();
     this.#provenance.clear();
     this.#provenanceStreamFlow.clear();
@@ -24551,6 +24624,10 @@ var MmtpRouter = class {
       }
     }
     if (info.isRepair) {
+      if (this.#isOverlayRepair(info.packetId, catalogTrackNameForPacket(ingress, info.packetId))) {
+        this.#dropOverlayRepair(info.packetId);
+        return;
+      }
       const ownerPacketId = this.#resolveRepairOwnerPacketId(info.packetId, ingress);
       if (ownerPacketId != null && this.#fecManager && hasAmbiguousCatalogTrackName(ingress, ownerPacketId)) return;
       const repair = this.#readRepairObject(
@@ -26069,6 +26146,10 @@ var MulticastTransport = class {
   #acceptedBytesByPacketId = /* @__PURE__ */ new Map();
   #packetIds = null;
   #protected = false;
+  // A protected join's S, and the last sender spelling that matched it, so a
+  // matching sender parses once per spelling rather than per datagram.
+  #protectedSource = void 0;
+  #matchedSource = void 0;
   // The sender S this join's accepted packets came from, once known; see
   // packetsDroppedForeignSender. Cleared by every join and by a silence
   // failback, so a replacement publisher is not locked out.
@@ -26120,6 +26201,11 @@ var MulticastTransport = class {
       return this.#declined(generation, "unavailable");
     }
     let failure = "invalid-request";
+    const protectedSource = config.protected === true ? config.sourceAddress ?? config.senderAddress : void 0;
+    if (config.protected === true && (protectedSource === void 0 || config.atsc3)) {
+      console.warn("[MulticastTransport] protected join refused: the path reports no per-datagram sender to check against S");
+      return this.#declined(generation, "invalid-request");
+    }
     try {
       const packetIds = config.packetIds?.length ? new Set(config.packetIds) : null;
       console.log(
@@ -26155,7 +26241,7 @@ var MulticastTransport = class {
       this.#subscription = subscription;
       const live = () => !this.#disposed && generation === this.#joinGeneration;
       const anySource = !config.sourceAddress && !config.senderAddress && !config.atsc3;
-      const packetListener = !anySource && subscriptionDeliversPacketBatches(subscription) ? {
+      const packetListener = !anySource && protectedSource === void 0 && subscriptionDeliversPacketBatches(subscription) ? {
         type: "packets",
         listener: (event) => {
           if (!live()) return;
@@ -26171,6 +26257,8 @@ var MulticastTransport = class {
       this.#packetListener = packetListener;
       this.#packetIds = packetIds;
       this.#protected = config.protected === true;
+      this.#protectedSource = protectedSource;
+      this.#matchedSource = void 0;
       this.#providerFilter = {
         acknowledged: packetIds,
         sent: 0,
@@ -26630,13 +26718,23 @@ var MulticastTransport = class {
     this.#delivery = void 0;
     this.#packetIds = null;
     this.#protected = false;
+    this.#protectedSource = void 0;
+    this.#matchedSource = void 0;
     this.#providerFilter = null;
     this.#context = void 0;
     this.#withdrawnPacketIds.clear();
   }
   /** The ingress filter; an accepted packet is counted here, once. */
   #acceptPacket(packet, sourceAddress) {
-    const owner = this.#lockedTo?.() ?? this.#sender;
+    const source = this.#protectedSource;
+    if (source !== void 0 && (sourceAddress === void 0 || sourceAddress !== this.#matchedSource)) {
+      if (sourceAddress === void 0 || !sameIpAddress(sourceAddress, source)) {
+        this.#stats.packetsDroppedForeignSender++;
+        return false;
+      }
+      this.#matchedSource = sourceAddress;
+    }
+    const owner = source === void 0 ? this.#lockedTo?.() ?? this.#sender : void 0;
     if (sourceAddress !== void 0 && owner !== void 0 && sourceAddress !== owner) {
       this.#stats.packetsDroppedForeignSender++;
       return false;
@@ -27160,9 +27258,7 @@ function repairTrackNamesBySource(tracks) {
 }
 function boundRepairNames(binding) {
   if (binding?.status !== "ok") return [];
-  const names = binding.layers.map((layer) => layer.repairTrackName);
-  if (binding.overlay) names.push(binding.overlay.repairTrackName);
-  return names;
+  return binding.layers.map((layer) => layer.repairTrackName);
 }
 var MulticastManager = class {
   #fec;
@@ -27928,7 +28024,11 @@ var MulticastManager = class {
         console.warn("[MulticastManager] repair group release failed", error);
       }
     };
-    const repairOwners = endpoints.flatMap((endpoint) => endpoint.repairOwners);
+    const repairOwners = endpoints.flatMap((endpoint) => endpoint.repairOwners.map((owner) => owner.instance !== "keyframe" ? owner : {
+      ...owner,
+      ownerTrackName: endpoint.tracks.find((t) => t.packetId === owner.ownerPacketId)?.name,
+      repairTrackName: endpoint.tracks.find((t) => t.packetId === owner.packetId)?.name
+    }));
     this.#applyRepairOwners(repairOwners);
     for (const endpoint of endpoints) {
       const ingress = {
@@ -27976,9 +28076,17 @@ var MulticastManager = class {
     return release;
   }
   #applyRepairOwners(owners) {
-    for (const { packetId, ownerPacketId } of owners) {
+    for (const { packetId, ownerPacketId, instance, ownerTrackName, repairTrackName } of owners) {
       this.#router.setPacketIdRole(packetId, "repair");
-      this.#router.setRepairPacketIdOwner(packetId, ownerPacketId);
+      if (instance === "keyframe") {
+        this.#router.setKeyframeOverlayLeg(packetId, {
+          sourcePacketId: ownerPacketId,
+          ...ownerTrackName === void 0 ? {} : { sourceCatalogTrackName: ownerTrackName },
+          ...repairTrackName === void 0 ? {} : { repairTrackName }
+        });
+      } else {
+        this.#router.setRepairPacketIdOwner(packetId, ownerPacketId);
+      }
     }
   }
   // ---------------------------------------------------------------------------
@@ -28242,8 +28350,8 @@ var MulticastManager = class {
     this.#fec.setMulticastSymbolDelivery(delivery);
   }
   /** Process a repair packet from MoQ (reliable QUIC). */
-  processRepairFromMoQ(packet, ownerPacketId, catalogTrackName) {
-    this.#router.feedRepairPacket(packet, ownerPacketId, catalogTrackName);
+  processRepairFromMoQ(packet, ownerPacketId, catalogTrackName, repairTrackName) {
+    this.#router.feedRepairPacket(packet, ownerPacketId, catalogTrackName, repairTrackName);
   }
   /** Route a Worker-recovered FEC block through the MMTP parser + dedup pipeline. */
   routeRecoveredBlock(blockId, data, packetId, catalogTrackName) {
@@ -28295,7 +28403,10 @@ var MulticastManager = class {
     const ownedRepairNames = /* @__PURE__ */ new Set();
     const claimed = /* @__PURE__ */ new Map();
     for (const binding of bindings.values()) {
-      for (const name of boundRepairNames(binding)) claimed.set(name, (claimed.get(name) ?? 0) + 1);
+      const overlay = binding.status === "ok" ? binding.overlay?.repairTrackName : void 0;
+      for (const name of [...boundRepairNames(binding), ...overlay === void 0 ? [] : [overlay]]) {
+        claimed.set(name, (claimed.get(name) ?? 0) + 1);
+      }
     }
     for (const [name, count] of claimed) if (count === 1) ownedRepairNames.add(name);
     const repairOwnerGroup = /* @__PURE__ */ new Map();
@@ -28426,6 +28537,14 @@ var MulticastManager = class {
               this.#router.setRepairPacketIdOwner(repairTrack.packetId, track.packetId);
             }
           }
+          const overlayName = binding.overlay?.repairTrackName;
+          if (overlayName !== void 0 && ownedRepairNames.has(overlayName)) {
+            this.#router.setKeyframeOverlayLeg(catalogTracksByName.get(overlayName)?.packetId, {
+              sourcePacketId: track.packetId,
+              sourceCatalogTrackName: track.name,
+              repairTrackName: overlayName
+            });
+          }
         }
         const wasmDecoder = fecDecoders.get(i);
         if (track.packetId !== void 0 && wasmDecoder !== void 0) {