@blockcast/mmt-container 2.1.0 → 2.2.0-main.050b52fb9b00

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
@@ -535,6 +535,9 @@ export class TrackSession {
     // via unsubscribe(), which has already disarmed). A bare assignment there
     // drops the host's decoder without a fec-teardown -- a leaked Worker.
     this.#disarmFec()
+    // A retired manager must release any decoder suppression it acquired.
+    // Unlike unsubscribe(), dispose() is called directly by SessionManager.
+    this.#unsuppress()
   }
 
   // -----------------------------------------------------------------------