@blockcast/mmt-container 2.1.0 → 2.2.0-main.079cd7664c0b

package/src/multicast-manager.ts

@@ -50,7 +50,11 @@ import {
   type StreamSwitchCommit,
   type TrackPacketCallback,
 } from "./mmtp-router.js";
-import { isMulticastTrackPacketId, type WindowMulticastGateway } from "@blockcast/mmt-transport";
+import {
+  isMulticastTrackPacketId,
+  userAgentVerifiedIngress,
+  type WindowMulticastGateway,
+} from "@blockcast/mmt-transport";
 import {
   MulticastTransport,
   type MulticastFailbackReason,
@@ -94,6 +98,8 @@ export interface MulticastRepairEndpoint {
   mode?: string;
   amtRelay?: string;
   amtRelayPort?: number;
+  /** The media join's `'driad'` discovery (no relay pinned), carried so the repair group rides the same relay. */
+  amtDiscovery?: 'driad';
   /** The repair packet IDs this group carries. */
   packetIds: number[];
   /** Each repair packet ID bound to the media packet ID it repairs. */
@@ -2353,10 +2359,20 @@ export class MulticastManager {
    * repair roles and owners are registered here; in-band owners stay the
    * caller's. Joining is best effort: a group that fails to join is logged
    * and leaves the media join as it was.
+   *
+   * `options.gateway` names the gateway a subscribe callback reads through.
+   * When it is the browser's own MulticastReceiver provider, the callback's
+   * packets are fed as admitted by the user agent
+   * (`userAgentVerifiedIngress`); nothing the callback passes can mark them.
+   * The mark rests on this statement, not on the data path: every packet the
+   * callback delivers must come from a subscription opened on
+   * `options.gateway`. A callback that also merges another source (a MoQ or
+   * WebSocket repair feed) must not name a native provider here.
    */
   joinRepairEndpoints(
     endpoints: readonly MulticastRepairEndpoint[],
     provider?: WindowMulticastGateway | MulticastRepairSubscribe,
+    options?: { gateway?: WindowMulticastGateway },
   ): () => void {
     const releases: Array<() => void> = [];
     let released = false;
@@ -2382,22 +2398,26 @@ export class MulticastManager {
         ...(endpoint.flow === undefined ? {} : { flow: endpoint.flow }),
       };
       let sender: string | undefined;
-      const onPacket = (packet: Uint8Array, sourceAddress?: string) => {
+      const feed = (packet: Uint8Array, sourceAddress: string | undefined, ingressToFeed: MmtpIngressContext) => {
         if (released) return;
         // The media join's sender owns the repair too; this group's own first
         // sender stands in only until the media join has one.
         if (sourceAddress !== undefined && !sameDatagramSource(sourceAddress, this.#transport.sender ?? (sender ??= sourceAddress))) return;
-        this.#router.feedPacket(packet, "multicast", ingress);
+        this.#router.feedPacket(packet, "multicast", ingressToFeed);
       };
       const fail = (error: unknown) =>
         console.warn(`[MulticastManager] repair group ${endpoint.group}:${endpoint.port} not joined`, error);
       if (typeof provider === "function") {
+        const marked = userAgentVerifiedIngress(ingress, options?.gateway);
+        const onPacket = (packet: Uint8Array, sourceAddress?: string) => feed(packet, sourceAddress, marked);
         Promise.resolve()
           .then(() => provider(endpoint, onPacket))
           .then((release) => (released ? safely(release) : releases.push(release)), fail);
         continue;
       }
-      const transport = new MulticastTransport((packet) => onPacket(packet), {
+      // The transport marks what it delivers when its gateway is the user
+      // agent's MulticastReceiver provider; feedPacket would not.
+      const transport = new MulticastTransport<MmtpIngressContext>((packet, delivered) => feed(packet, undefined, delivered ?? ingress), {
         gateway: provider,
         lockedTo: () => this.#transport.sender,
       });
@@ -2409,11 +2429,12 @@ export class MulticastManager {
         mode: endpoint.mode as MulticastEndpointConfig["mode"],
         amtRelay: endpoint.amtRelay,
         amtRelayPort: endpoint.amtRelayPort ?? (endpoint.amtRelay?.trim() ? DEFAULT_AMT_RELAY_PORT : undefined),
+        amtDiscovery: endpoint.amtDiscovery,
         packetIds: endpoint.packetIds,
         tracks: endpoint.tracks.map(({ name, packetId }) => ({ name, packetId })),
         // A protected repair group's records ride in band on its port (7.2.3).
         ...(endpoint.flow === undefined ? {} : { protected: true }),
-      }).then((joined) => {
+      }, ingress).then((joined) => {
         if (!joined && !released) fail(transport.lastJoinOutcome);
       });
     }

package/src/multicast-transport.ts

@@ -6,7 +6,10 @@
 
 import {
   isMulticastTrackPacketId,
+  isUserAgentVerifiedGateway,
+  resolveMulticastGateway,
   subscriptionDeliversPacketBatches,
+  userAgentVerifiedIngress,
   toWindowMulticastSubscribeConfig,
   type WindowMulticastDelivery,
   type WindowMulticastGateway,
@@ -52,7 +55,13 @@ export interface MulticastTransportConfig {
   protected?: boolean
 }
 
-export type ResolvedMulticastTransport = 'native' | 'amt'
+/**
+ * The leg a join resolved to. `'user-agent'`: the browser's own
+ * `MulticastReceiver` delivers it, which picks native or AMT itself and does
+ * not say which. CMCD has no user-agent value, so a caller reports a
+ * `'user-agent'` join as `'native'` (`TransportSnapshot.transport`).
+ */
+export type ResolvedMulticastTransport = 'native' | 'amt' | 'user-agent'
 
 /**
  * Why a joined transport handed control back to MoQ.
@@ -211,16 +220,8 @@ function providerErrorOf(error: unknown): MulticastJoinProviderError | undefined
  */
 const MAX_TRACKED_DROPPED_PIDS = 16
 
-type MulticastGlobals = typeof globalThis & {
-  multicast?: WindowMulticastGateway
-}
-
-function getMulticastGlobals(): MulticastGlobals {
-  return globalThis as MulticastGlobals
-}
-
 function hasMulticastGateway(): boolean {
-  return typeof getMulticastGlobals().multicast?.subscribe === 'function'
+  return typeof resolveMulticastGateway()?.subscribe === 'function'
 }
 
 /**
@@ -371,6 +372,9 @@ export class MulticastTransport<TPacketContext = never> {
   // listener closure, so an in-place admission change (setContext) applies
   // from the next packet on without rejoining.
   #context: TPacketContext | undefined = undefined
+  #deliveredContext: TPacketContext | undefined = undefined
+  /** The live join's gateway, when it is the user agent's MulticastReceiver provider. */
+  #userAgentGateway: WindowMulticastGateway | undefined = undefined
   // The live join's provider-side filter. An in-place widening must reach it,
   // or the provider never delivers the new ID; null without a live join.
   #providerFilter: ProviderFilter | null = null
@@ -415,7 +419,7 @@ export class MulticastTransport<TPacketContext = never> {
     this.#sender = undefined
 
     if (this.#disposed) return this.#declined(generation, 'disposed')
-    const gateway = this.#gateway ?? getMulticastGlobals().multicast
+    const gateway = this.#gateway ?? resolveMulticastGateway()
     if (typeof gateway?.subscribe !== 'function') {
       console.warn('[MulticastTransport] Multicast API not available')
       return this.#declined(generation, 'unavailable')
@@ -435,15 +439,18 @@ export class MulticastTransport<TPacketContext = never> {
       console.log(
         `[MulticastTransport] window.multicast.subscribe(${config.sourceAddress ?? config.senderAddress ?? '*'}, ${config.groupAddress}, ${config.port})`,
       )
+      // The browser's MulticastReceiver picks native or AMT, and the relay,
+      // itself: ask it for the group only.
+      const userAgent = isUserAgentVerifiedGateway(gateway)
       const subscribeConfig = toWindowMulticastSubscribeConfig({
         source: config.sourceAddress,
         senderAddress: config.senderAddress,
         group: config.groupAddress,
         port: config.port,
-        mode: config.mode,
-        amtRelay: config.amtRelay,
-        amtRelayPort: config.amtRelayPort,
-        amtDiscovery: config.amtDiscovery,
+        mode: userAgent ? 'native' : config.mode,
+        amtRelay: userAgent ? undefined : config.amtRelay,
+        amtRelayPort: userAgent ? undefined : config.amtRelayPort,
+        amtDiscovery: userAgent ? undefined : config.amtDiscovery,
         packetIds: config.packetIds,
         tracks: config.tracks,
         atsc3: config.atsc3,
@@ -506,7 +513,8 @@ export class MulticastTransport<TPacketContext = never> {
         acknowledgedUpdate: 0,
         inFlight: 0,
       }
-      this.#context = context
+      this.#userAgentGateway = userAgent ? gateway : undefined
+      this.#setContext(context)
       // Seed the allow-list's counters so accepted packets never insert. An
       // id already counted by an earlier join keeps its count: the counters
       // are cumulative across rejoins, as bytesReceived is.
@@ -521,7 +529,7 @@ export class MulticastTransport<TPacketContext = never> {
       // gateway no longer exposes a mutable transport/transportchange
       // surface, so assign this only after subscribe() has resolved and the
       // returned subscription has passed the event-surface check above.
-      this.#resolvedTransport = subscribeConfig.origin === 'amt' ? 'amt' : 'native'
+      this.#resolvedTransport = userAgent ? 'user-agent' : subscribeConfig.origin === 'amt' ? 'amt' : 'native'
       // The provider alone knows whether its packets are independent
       // datagrams or an ordered relay of one socket; undeclared promises no
       // ordering. Announce it before the listener can deliver a packet. A
@@ -630,7 +638,7 @@ export class MulticastTransport<TPacketContext = never> {
     // Read per packet: a callback that changes the admission (an in-place
     // rendition switch committing on this very packet) takes effect from the
     // next packet, including the rest of a batch.
-    this.#onPacket(packet, this.#context)
+    this.#onPacket(packet, this.#deliveredContext)
     return liveness
   }
 
@@ -872,8 +880,10 @@ export class MulticastTransport<TPacketContext = never> {
   }
 
   /**
-   * What the live join delivers with every accepted packet (the join's
-   * `context`, or the last setContext), or undefined without a live join.
+   * The live join's context as the caller gave it (the join's `context`, or
+   * the last setContext), or undefined without a live join. On a native
+   * provider each accepted packet is delivered with a marked copy of it
+   * (`userAgentVerifiedIngress`); this getter never carries the mark.
    */
   get context(): TPacketContext | undefined {
     return this.#context
@@ -899,7 +909,19 @@ export class MulticastTransport<TPacketContext = never> {
         '[MulticastTransport] setContext needs a live join; join() carries the first context',
       )
     }
+    this.#setContext(context)
+  }
+
+  /**
+   * The join's context, and what the subscription delivers with each packet:
+   * marked admitted by the user agent when the gateway is its native
+   * MulticastReceiver provider. feedPacket never marks.
+   */
+  #setContext(context: TPacketContext | undefined): void {
     this.#context = context
+    this.#deliveredContext = this.#userAgentGateway !== undefined && typeof context === 'object' && context !== null
+      ? userAgentVerifiedIngress(context, this.#userAgentGateway)
+      : context
   }
 
   /**
@@ -1040,6 +1062,8 @@ export class MulticastTransport<TPacketContext = never> {
     this.#matchedSource = undefined
     this.#providerFilter = null
     this.#context = undefined
+    this.#deliveredContext = undefined
+    this.#userAgentGateway = undefined
     this.#withdrawnPacketIds.clear()
   }
 

package/src/repair-layer-subscriptions.ts

@@ -0,0 +1,261 @@
+/**
+ * MoQ repair-layer subscriptions by measured loss (BLO-35456).
+ *
+ * MoQ is per-track subscribe, so a repair layer the receiver does not
+ * subscribe costs nothing past the relay. This is the mechanism that decides
+ * which of a source's repair tracks to hold: it measures loss from the MMTP
+ * `packet_sequence_number` gaps the receiver already sees on the source track
+ * (no new signalling), holds base layers 0..n-1 (draft-ramadan-moq-fec 6.3,
+ * `resolveRepairLayers`), and holds the keyframe overlay track while any base
+ * layer is held. The policy here is deliberately the simplest per-layer
+ * add/drop; the join policy proper is BLO-35457.
+ *
+ * Every repair packet is handed to `feed` with the repair track it arrived on,
+ * so libmmt routes an overlay packet to the overlay instance and never to the
+ * base (`MmtpRouter.feedRepairPacket(..., repairTrackName)`).
+ *
+ * `stream` delivery means QUIC retransmits: no repair track is ever
+ * subscribed (FEC only for unreliable transports). The mode is the source's
+ * `deliveryMode` (`catalogTrackDeliveryMode`); absent is `datagram`. It is
+ * read from the current source, so on a catalog refresh re-feed the updated
+ * source through `switchSource` for a changed `deliveryMode` to take effect.
+ *
+ * ABR switch R -> R' (`switchSource`): R's subscriptions are closed, the layer
+ * count carries to R', and any packet R's subscriptions deliver after the
+ * switch is dropped, never fed.
+ */
+
+import { serial32Distance } from '@blockcast/mmt-base'
+import type { RepairLayerParams, RepairOverlayParams } from './repair-layers.js'
+
+export type MoqRepairDelivery = 'datagram' | 'stream'
+
+/** The source's FEC shape, as `fecParams` resolves it. */
+export interface RepairLayerSource {
+  /** K: source symbols per base block. */
+  fecK: number
+  /** Base layers, layer 0 first (`TrackFecParams.repairLayers`). */
+  repairLayers?: readonly RepairLayerParams[]
+  /** Keyframe overlays (`TrackFecParams.repairOverlays`); at most one is used. */
+  repairOverlays?: readonly RepairOverlayParams[]
+  /** The publisher's MoQ delivery mode; absent is `datagram`. */
+  deliveryMode?: MoqRepairDelivery
+}
+
+export interface RepairTrackSubscription {
+  close(): void
+}
+
+export interface RepairLayerSubscriptionsOptions {
+  source: RepairLayerSource
+  /** Subscribe one repair track; every object payload goes to `onPacket`. */
+  subscribe(
+    repairTrackName: string,
+    priority: number,
+    onPacket: (packet: Uint8Array) => void,
+  ): RepairTrackSubscription
+  /** Hand one repair packet to the decoder, e.g. `processRepairFromMoQ`. */
+  feed(packet: Uint8Array, repairTrackName: string): void
+  /** Expected source packets per loss window. Default 500. */
+  windowPackets?: number
+  /** Repair held per unit of measured loss. Default 2. */
+  margin?: number
+  /** Consecutive windows wanting fewer layers before one is dropped. Default 3. */
+  dropAfterWindows?: number
+}
+
+export interface RepairLayerSubscriptionsSnapshot {
+  delivery: MoqRepairDelivery
+  layerCount: number
+  subscribedTracks: string[]
+  repairPackets: number
+  repairBytes: number
+  /** Packets a closed subscription delivered after its switch or drop. */
+  staleDropped: number
+  /** Loss rate of the last closed window; null before the first. */
+  lossRate: number | null
+}
+
+const SERIAL32_HALF = 0x80000000
+
+export class RepairLayerSubscriptions {
+  readonly #opts: RepairLayerSubscriptionsOptions
+  readonly #windowPackets: number
+  readonly #margin: number
+  readonly #dropAfterWindows: number
+  #source: RepairLayerSource
+  #layerCount = 0
+  #subs = new Map<string, { sub: RepairTrackSubscription }>()
+  #disposed = false
+  #lastSeq: number | undefined
+  #expected = 0
+  #lost = 0
+  #wantFewer = 0
+  #lossRate: number | null = null
+  #repairPackets = 0
+  #repairBytes = 0
+  #staleDropped = 0
+
+  constructor(opts: RepairLayerSubscriptionsOptions) {
+    this.#opts = opts
+    this.#source = opts.source
+    this.#windowPackets = opts.windowPackets ?? 500
+    this.#margin = opts.margin ?? 2
+    this.#dropAfterWindows = opts.dropAfterWindows ?? 3
+  }
+
+  get layerCount(): number {
+    return this.#layerCount
+  }
+
+  /**
+   * One source packet's MMTP `packet_sequence_number`, in arrival order.
+   * The sequence is per `packet_id`: pass the packets of ONE packet_id only,
+   * or interleaved sequences read as loss.
+   */
+  noteSourceSequence(seq: number): void {
+    if (this.#disposed || this.#delivery() === 'stream') return
+    seq >>>= 0
+    if (this.#lastSeq === undefined) {
+      this.#lastSeq = seq
+      return
+    }
+    const d = serial32Distance(this.#lastSeq, seq)
+    if (d === 0) return
+    const back = d >= SERIAL32_HALF ? 2 ** 32 - d : 0
+    if (d > this.#windowPackets && (back === 0 || back > this.#windowPackets)) {
+      // A step wider than one window, either way, is a discontinuity (a
+      // publisher restart), not loss or reorder: restart the window from here.
+      // ponytail: a real outage longer than a window is also read as a restart;
+      // FEC cannot repair that anyway.
+      this.#lastSeq = seq
+      this.#expected = 0
+      this.#lost = 0
+      return
+    }
+    if (back === 0) {
+      this.#expected += d
+      this.#lost += d - 1
+      this.#lastSeq = seq
+    } else if (this.#lost > 0) {
+      // A late packet fills a hole counted as lost. Holes are not tracked
+      // individually, so one whose window already closed cancels a hole in
+      // this window instead: a bias toward lower loss of at most the reorder
+      // depth per window.
+      this.#lost -= 1
+    }
+    if (this.#expected >= this.#windowPackets) this.#closeWindow()
+  }
+
+  /** ABR switch R -> R': close R's tracks, carry the layer count to R'. */
+  switchSource(next: RepairLayerSource): void {
+    if (this.#disposed) return
+    this.#closeAll()
+    this.#source = next
+    this.#lastSeq = undefined
+    this.#expected = 0
+    this.#lost = 0
+    this.#wantFewer = 0
+    this.#layerCount = this.#delivery() === 'stream' ? 0 : Math.min(this.#layerCount, this.#layers().length)
+    this.#reconcile()
+  }
+
+  snapshot(): RepairLayerSubscriptionsSnapshot {
+    return {
+      delivery: this.#delivery(),
+      layerCount: this.#layerCount,
+      subscribedTracks: [...this.#subs.keys()],
+      repairPackets: this.#repairPackets,
+      repairBytes: this.#repairBytes,
+      staleDropped: this.#staleDropped,
+      lossRate: this.#lossRate,
+    }
+  }
+
+  dispose(): void {
+    if (this.#disposed) return
+    this.#closeAll()
+    this.#disposed = true
+  }
+
+  #delivery(): MoqRepairDelivery {
+    return this.#source.deliveryMode === 'stream' ? 'stream' : 'datagram'
+  }
+
+  #layers(): readonly RepairLayerParams[] {
+    return this.#source.repairLayers ?? []
+  }
+
+  #closeWindow(): void {
+    const rate = this.#lost / this.#expected
+    this.#lossRate = rate
+    this.#expected = 0
+    this.#lost = 0
+    const target = this.#targetLayers(rate)
+    if (target > this.#layerCount) {
+      this.#wantFewer = 0
+      this.#layerCount = target
+    } else if (target < this.#layerCount) {
+      this.#wantFewer += 1
+      if (this.#wantFewer >= this.#dropAfterWindows) {
+        this.#wantFewer = 0
+        this.#layerCount -= 1
+      }
+    } else {
+      this.#wantFewer = 0
+    }
+    this.#reconcile()
+  }
+
+  /** Fewest base layers whose summed P covers margin x the measured loss of K. */
+  #targetLayers(rate: number): number {
+    if (rate <= 0) return 0
+    const needed = Math.ceil(rate * this.#source.fecK * this.#margin)
+    const layers = this.#layers()
+    let held = 0
+    for (let n = 0; n < layers.length; n++) {
+      held += layers[n]!.repairSymbols
+      if (held >= needed) return n + 1
+    }
+    return layers.length
+  }
+
+  /** Stream delivery never leaves layer count 0, so it never subscribes. */
+  #reconcile(): void {
+    const want = new Map<string, number>()
+    for (const layer of this.#layers().slice(0, this.#layerCount)) {
+      want.set(layer.repairTrackName, layer.priority)
+    }
+    const overlay = this.#source.repairOverlays?.[0]
+    if (this.#layerCount > 0 && overlay) want.set(overlay.repairTrackName, overlay.priority)
+
+    for (const [name, entry] of this.#subs) {
+      if (!want.has(name)) {
+        entry.sub.close()
+        this.#subs.delete(name)
+      }
+    }
+    for (const [name, priority] of want) {
+      if (this.#subs.has(name)) continue
+      const entry = {} as { sub: RepairTrackSubscription }
+      entry.sub = this.#opts.subscribe(name, priority, (packet) => this.#onPacket(name, entry, packet))
+      this.#subs.set(name, entry)
+    }
+  }
+
+  /** Fenced on the entry itself, so a closed subscription is stale even if its track is re-added. */
+  #onPacket(name: string, entry: { sub: RepairTrackSubscription }, packet: Uint8Array): void {
+    if (this.#disposed || this.#subs.get(name) !== entry) {
+      this.#staleDropped += 1
+      return
+    }
+    this.#repairPackets += 1
+    this.#repairBytes += packet.byteLength
+    this.#opts.feed(packet, name)
+  }
+
+  #closeAll(): void {
+    for (const entry of this.#subs.values()) entry.sub.close()
+    this.#subs.clear()
+  }
+}

package/src/track-session.ts

@@ -58,7 +58,7 @@ export interface TrackSessionConfig {
    * This is runtime join state, not catalog geometry: a receiver on a clean
    * path joins layer 0 only while a lossy one adds layers, so the catalog's
    * total P is not what this receiver is receiving. Diagnostics that report P
-   * (the worker snapshot, CMCD `x-bc-fec-p`) must read this.
+   * (the worker snapshot, CMCD `com.blockcast-fp`) must read this.
    *
    * Absent when the caller joins no layers explicitly, in which case P_0 is
    * what was joined. That is an identity on a single-layer track, not a