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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blockcast/mmt-container",
-  "version": "2.0.0",
+  "version": "2.0.1-main.0f2de6af487b",
   "description": "MMTP/LOC container parsing for MMT over MoQ and SSM",
   "type": "module",
   "main": "dist/index.js",
@@ -169,10 +169,10 @@
     "test:watch": "vitest"
   },
   "dependencies": {
-    "@blockcast/fec-worker": "^2.0.0",
-    "@blockcast/mmt-base": "^2.0.0",
-    "@blockcast/mmt-fec": "^2.0.0",
-    "@blockcast/mmt-manifest-verify": "^2.0.0",
+    "@blockcast/fec-worker": "2.0.1-main.0f2de6af487b",
+    "@blockcast/mmt-base": "2.0.1-main.0f2de6af487b",
+    "@blockcast/mmt-fec": "2.0.1-main.0f2de6af487b",
+    "@blockcast/mmt-manifest-verify": "2.0.1-main.0f2de6af487b",
     "@noble/curves": "^1.9.7",
     "@noble/hashes": "^1.8.0",
     "ajv": "^8.17.1",

package/src/index.ts

@@ -274,6 +274,7 @@ export {
   type FrameCallback,
   type FECManagerLike,
   type MmtpIngressContext,
+  type KeyframeOverlayLeg,
   type MmtpStreamIdentity,
   type RoutedPacketMeta,
   type StagedStreamSwitch,

package/src/mmtp-router.ts

@@ -175,6 +175,13 @@ export type RoutedFrameMeta = {
   gapBefore?: FrameGapDecision;
 };
 
+/** A keyframe-overlay repair leg: the source its FEC instance protects. */
+export interface KeyframeOverlayLeg {
+  sourcePacketId: number;
+  sourceCatalogTrackName?: string;
+  repairTrackName?: string;
+}
+
 export interface MmtpIngressContext {
   tracks: readonly Readonly<{ name: string; packetId: number }>[];
   /**
@@ -1031,6 +1038,14 @@ export class MmtpRouter {
   #packetIdRoles: Map<number, TrackRole> = new Map();
   /** Explicit catalog ownership for dedicated repair-track packet IDs. */
   #repairOwnersByPacketId = new Map<number, Set<number>>();
+  /** 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 = new Map<number, KeyframeOverlayLeg>();
+  /** Keyframe-overlay repair track names, which name a leg too: a catalog
+   *  may state no PID for it (learned at subscribe time). */
+  #overlayRepairNames = new Map<string, KeyframeOverlayLeg>();
+  #overlayStats = { repairDropped: 0, ownerRefused: 0 };
   /** Callback fired when a delta-track FEC block completes or fails. */
   #onDeltaBlockCompleteCb:
     | ((packetId: number, failed: boolean) => void)
@@ -1775,15 +1790,61 @@ export class MmtpRouter {
   /** Replace catalog-derived repair ownership before a catalog reconfiguration. */
   clearRepairPacketIdOwners(): void {
     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: number, ownerPacketId: number): void {
+    if (this.#overlayLegs.has(repairPacketId)) {
+      this.#overlayStats.ownerRefused++;
+      return;
+    }
     const owners = this.#repairOwnersByPacketId.get(repairPacketId) ?? new Set<number>();
     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: number | undefined, leg: KeyframeOverlayLeg): void {
+    if (leg.repairTrackName !== undefined) this.#overlayRepairNames.set(leg.repairTrackName, { ...leg });
+    if (repairPacketId === undefined) return;
+    this.#repairOwnersByPacketId.delete(repairPacketId);
+    this.#overlayLegs.set(repairPacketId, { ...leg });
+  }
+
+  /** The keyframe-overlay leg registered on `repairPacketId`, if any. */
+  keyframeOverlayLeg(repairPacketId: number): Readonly<KeyframeOverlayLeg> | undefined {
+    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(): Readonly<{ repairDropped: number; ownerRefused: number }> {
+    return { ...this.#overlayStats };
+  }
+
+  #isOverlayRepair(repairPacketId: number, repairTrackName?: string): boolean {
+    return this.#overlayLegs.has(repairPacketId) ||
+      (repairTrackName !== undefined && 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: number): void {
+    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.
    *
@@ -2316,6 +2377,10 @@ export class MmtpRouter {
     // A dedicated repair track can carry a packet ID that differs from the
     // media packet ID. The subscribing track supplies the authoritative owner.
     const repairPacketId = header.packetId;
+    if (this.#isOverlayRepair(repairPacketId, repairTrackName)) {
+      this.#dropOverlayRepair(repairPacketId);
+      return;
+    }
 
     const hintedOwner =
       ownerPacketIdHint != null && this.#classifyPacketId(ownerPacketIdHint) !== null
@@ -2803,6 +2868,13 @@ export class MmtpRouter {
     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];
@@ -3075,6 +3147,8 @@ export class MmtpRouter {
     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();
@@ -3550,6 +3624,11 @@ export class MmtpRouter {
       // Repair packet — per ISO 23008-1 §C.5.3, carries (SS_Start, SSB_length, RS_ID).
       // Read from the header parsed above rather than parsing it again
       // (BLO-36599).
+        // The track a repair packet arrives on names its instance (7.4.2).
+        if (this.#isOverlayRepair(info.packetId, catalogTrackNameForPacket(ingress, info.packetId))) {
+          this.#dropOverlayRepair(info.packetId);
+          return;
+        }
         const ownerPacketId = this.#resolveRepairOwnerPacketId(info.packetId, ingress);
         // An ambiguous name attributes the packet to no instance, so it is
         // dropped before admission can count or fail closed against one.

package/src/multicast-manager.ts

@@ -97,7 +97,7 @@ export interface MulticastRepairEndpoint {
   /** The repair packet IDs this group carries. */
   packetIds: number[];
   /** Each repair packet ID bound to the media packet ID it repairs. */
-  repairOwners: ReadonlyArray<{ packetId: number; ownerPacketId: number }>;
+  repairOwners: ReadonlyArray<{ packetId: number; ownerPacketId: number; instance?: "keyframe" }>;
   /** Ingress tracks: the owners' source tracks and the repair tracks. */
   tracks: MmtpIngressContext["tracks"];
   /** The protected flow (`MmtpRouter.registerProvenanceFlow`) this group's datagrams belong to. */
@@ -1257,14 +1257,18 @@ function repairTrackNamesBySource(
   return bySource;
 }
 
-/** The repair tracks an `ok` binding joins: base layers, then the overlay. */
+/** The base repair layers an `ok` binding joins. The keyframe overlay is
+ *  not among them: it is its own FEC instance (draft-ramadan-mmt-fec-02 7.4). */
 function boundRepairNames(binding: FecSourceBinding | undefined): string[] {
   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);
 }
 
+type RepairOwnerEntry = MulticastRepairEndpoint["repairOwners"][number] & {
+  ownerTrackName?: string;
+  repairTrackName?: string;
+};
+
 export class MulticastManager {
   readonly #fec: FECManager;
   readonly #router: MmtpRouter;
@@ -1276,7 +1280,7 @@ export class MulticastManager {
   #failbackHooked = false;
   /** Live joinRepairEndpoints() releases → the repair owners they registered,
    *  re-applied after configureMultiTrack() clears catalog-derived owners. */
-  readonly #repairReleases = new Map<() => void, MulticastRepairEndpoint["repairOwners"]>();
+  readonly #repairReleases = new Map<() => void, RepairOwnerEntry[]>();
   #reportedFecDiagnosticsFailure = false;
 
   // ── Stream-global FEC timing reduction ──
@@ -2291,7 +2295,14 @@ export class MulticastManager {
         console.warn("[MulticastManager] repair group release failed", error);
       }
     };
-    const repairOwners = endpoints.flatMap((endpoint) => endpoint.repairOwners);
+    // An overlay leg's source and repair track names come from the
+    // endpoint's ingress tracks.
+    const repairOwners: RepairOwnerEntry[] = 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: MmtpIngressContext = {
@@ -2344,10 +2355,18 @@ export class MulticastManager {
     return release;
   }
 
-  #applyRepairOwners(owners: MulticastRepairEndpoint["repairOwners"]): void {
-    for (const { packetId, ownerPacketId } of owners) {
+  #applyRepairOwners(owners: RepairOwnerEntry[]): void {
+    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 === undefined ? {} : { sourceCatalogTrackName: ownerTrackName }),
+          ...(repairTrackName === undefined ? {} : { repairTrackName }),
+        });
+      } else {
+        this.#router.setRepairPacketIdOwner(packetId, ownerPacketId);
+      }
     }
   }
 
@@ -2668,8 +2687,10 @@ export class MulticastManager {
     packet: Uint8Array,
     ownerPacketId?: number,
     catalogTrackName?: string,
+    /** The repair track it arrived on: names its FEC instance (mmt-02 7.4.2). */
+    repairTrackName?: string,
   ) {
-    this.#router.feedRepairPacket(packet, ownerPacketId, catalogTrackName);
+    this.#router.feedRepairPacket(packet, ownerPacketId, catalogTrackName, repairTrackName);
   }
 
   /** Route a Worker-recovered FEC block through the MMTP parser + dedup pipeline. */
@@ -2759,7 +2780,10 @@ export class MulticastManager {
     const ownedRepairNames = new Set<string>();
     const claimed = new Map<string, number>();
     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 : undefined;
+      for (const name of [...boundRepairNames(binding), ...(overlay === undefined ? [] : [overlay])]) {
+        claimed.set(name, (claimed.get(name) ?? 0) + 1);
+      }
     }
     for (const [name, count] of claimed) if (count === 1) ownedRepairNames.add(name);
     const repairOwnerGroup = new Map<string, string>();
@@ -2928,10 +2952,12 @@ export class MulticastManager {
       const binding = bindings.get(track.name);
       if (binding?.status === "ok") {
         const fecCfg = binding.base;
-        // Every repair layer and the keyframe overlay route to this source's
-        // decoder, not only layer 0. A layer whose packetId had no registered
-        // owner would have its repair symbols dropped as an unknown owner, and
-        // two sources whose RS_ID ranges overlap would be indistinguishable.
+        // Every base repair layer routes to this source's decoder, not only
+        // layer 0. A layer whose packetId had no registered owner would have
+        // its repair symbols dropped as an unknown owner, and two sources whose
+        // RS_ID ranges overlap would be indistinguishable. The keyframe overlay
+        // is another FEC instance: it is recorded as an overlay leg, never
+        // owned by this source's base decoder (draft-ramadan-mmt-fec-02 7.4.4).
         if (track.packetId !== undefined) {
           for (const repairName of boundRepairNames(binding)) {
             if (!ownedRepairNames.has(repairName)) continue;
@@ -2940,6 +2966,16 @@ export class MulticastManager {
               this.#router.setRepairPacketIdOwner(repairTrack.packetId, track.packetId);
             }
           }
+          // By its name too: a catalog that states no PID for it (learned at
+          // subscribe time) must still keep its MoQ repair from the base.
+          const overlayName = binding.overlay?.repairTrackName;
+          if (overlayName !== undefined && 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 !== undefined && wasmDecoder !== undefined) {

package/src/multicast-transport.ts

@@ -16,6 +16,7 @@ import {
   MMTP_PACKET_ID_MAX,
   MMTP_SIGNALING_PACKET_ID,
   readMMTPPacketId,
+  sameIpAddress,
 } from '@blockcast/mmt-base'
 import { isBcpV2RecordCandidate } from '@blockcast/mmt-manifest-verify'
 
@@ -41,6 +42,12 @@ export interface MulticastTransportConfig {
    * are "MHM2" passes ahead of the packet_id read and the allow-list, and is
    * never counted toward a packet_id. On an unprotected join it is an
    * unparseable MMTP packet, as before.
+   *
+   * A protected join admits only datagrams whose reported sender is the
+   * flow's S (`sourceAddress`, or `senderAddress` on ASM), compared as IP
+   * addresses, before anything hashes them (multicast-02 7.2.7). A datagram
+   * with no reported sender is dropped, and a join that cannot report one
+   * (no S, or an ATSC 3.0 tuner) is declined `invalid-request`.
    */
   protected?: boolean
 }
@@ -148,7 +155,8 @@ export interface MulticastTransportStats {
    * one (G, port, packet_id); the first sender whose packet is accepted owns
    * the sub-flow until the next join, and every other sender is dropped here,
    * before any gap, duplicate or FEC ledger sees it. A join or a silence
-   * failback releases the lock.
+   * failback releases the lock. On a protected join it also counts every
+   * datagram whose sender is not the flow's S, or is not reported.
    */
   packetsDroppedForeignSender: number
 }
@@ -215,7 +223,14 @@ function hasMulticastGateway(): boolean {
   return typeof getMulticastGlobals().multicast?.subscribe === 'function'
 }
 
-/** The `bytes` event's sender (multicast-contract 1.3.0); undefined when unknown. */
+/**
+ * The `bytes` event's sender (multicast-contract 1.3.0); undefined when unknown.
+ *
+ * The provider filters (S, G, port) and owns the multicast-02 7.2.7
+ * destination MUST: the event carries no destination address, so libmmt
+ * cannot discard a datagram whose IP destination is not G (pim BLO-51627).
+ * On a protected flow libmmt checks the sender itself, against S.
+ */
 function senderOf(event: CustomEvent<unknown>): string | undefined {
   const sourceAddress = (event as { sourceAddress?: unknown }).sourceAddress
   return typeof sourceAddress === 'string' ? sourceAddress : undefined
@@ -343,6 +358,10 @@ export class MulticastTransport<TPacketContext = never> {
   readonly #acceptedBytesByPacketId = new Map<number, { bytes: number }>()
   #packetIds: ReadonlySet<number> | null = 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: string | undefined = undefined
+  #matchedSource: string | undefined = undefined
   // 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.
@@ -406,6 +425,11 @@ export class MulticastTransport<TPacketContext = never> {
     // failure before it runs, so the catch classifies a decline by where the
     // join stopped, never by what the error says.
     let failure: MulticastJoinDeclineReason = 'invalid-request'
+    const protectedSource = config.protected === true ? config.sourceAddress ?? config.senderAddress : undefined
+    if (config.protected === true && (protectedSource === undefined || 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(
@@ -454,8 +478,9 @@ export class MulticastTransport<TPacketContext = never> {
       // costs batching on every any-source join, including one on a pre-1.3.0
       // provider that sends no sender and so gets no lock for it; keep it
       // unless the provider can say it carries the sender.
+      // A protected join checks every datagram's sender, so it listens to `bytes` too.
       const anySource = !config.sourceAddress && !config.senderAddress && !config.atsc3
-      const packetListener: PacketListener = !anySource && subscriptionDeliversPacketBatches(subscription)
+      const packetListener: PacketListener = !anySource && protectedSource === undefined && subscriptionDeliversPacketBatches(subscription)
         ? {
             type: 'packets',
             listener: (event) => {
@@ -473,6 +498,8 @@ export class MulticastTransport<TPacketContext = never> {
       this.#packetListener = packetListener
       this.#packetIds = packetIds
       this.#protected = config.protected === true
+      this.#protectedSource = protectedSource
+      this.#matchedSource = undefined
       this.#providerFilter = {
         acknowledged: packetIds,
         sent: 0,
@@ -1009,6 +1036,8 @@ export class MulticastTransport<TPacketContext = never> {
     this.#delivery = undefined
     this.#packetIds = null
     this.#protected = false
+    this.#protectedSource = undefined
+    this.#matchedSource = undefined
     this.#providerFilter = null
     this.#context = undefined
     this.#withdrawnPacketIds.clear()
@@ -1016,8 +1045,18 @@ export class MulticastTransport<TPacketContext = never> {
 
   /** The ingress filter; an accepted packet is counted here, once. */
   #acceptPacket(packet: Uint8Array, sourceAddress?: string): boolean {
+    const source = this.#protectedSource
+    if (source !== undefined && (sourceAddress === undefined || sourceAddress !== this.#matchedSource)) {
+      if (sourceAddress === undefined || !sameIpAddress(sourceAddress, source)) {
+        this.#stats.packetsDroppedForeignSender++
+        return false
+      }
+      this.#matchedSource = sourceAddress
+    }
     // Absent means unknown (a pre-1.3.0 provider, a tuner): never a new sender.
-    const owner = this.#lockedTo?.() ?? this.#sender
+    // A protected flow's S check above replaces the first-seen lock, which
+    // compares spellings and would refuse S written another way.
+    const owner = source === undefined ? this.#lockedTo?.() ?? this.#sender : undefined
     if (sourceAddress !== undefined && owner !== undefined && sourceAddress !== owner) {
       this.#stats.packetsDroppedForeignSender++
       return false