@blockcast/mmt-container 0.3.0 → 0.4.0-main.1cd3cdea89da

package/src/mmtp-container-parser.ts

@@ -2,7 +2,6 @@ import {
   parseMMTPHeader,
   extractMFUPayloadWithHeader,
   sourceFecPayloadIdOf,
-  extractAltaTrailer,
   PACKET_TYPE_MPU,
   PACKET_TYPE_REPAIR,
   type MMTPHeader,
@@ -453,16 +452,6 @@ export function isMfuKeyframeMetadata(rapFlag: boolean, priority?: number): bool
   return rapFlag || (priority ?? 0) > 0x80
 }
 
-/** Per-packet detached ALTA authenticator trailer (08-07 Path 2).
- *  - `auth`: the authenticator bytes (length-prefixed at packet end).
- *  - `payloadEnd`: byte offset within the source packet where signed
- *     payload ends — consumers reconstruct `payload = packet[0..payloadEnd]`
- *     for verify_detached. */
-export interface ParsedAltaTrailer {
-  auth: Uint8Array
-  payloadEnd: number
-}
-
 /** Source-symbol exposure for FEC consumers.
  *
  *  Fires from {@link MmtpContainerParser.feed} once per FEC-protected source
@@ -475,7 +464,6 @@ export interface ParsedAltaTrailer {
  *  - `rawSymbol` – packet bytes minus the 4-byte fec_payload_id trailer.
  *                  NOT zero-padded to FEC symbol size — consumer pads if needed
  *                  (FEC symbol size is FEC-config, not parser-config).
- *  - `alta`      – detached ALTA authenticator if present, else undefined
  *
  *  Designed so consumers (player, Shaka shim, upstream moqtail) can wire
  *  source-symbol delivery to whatever FEC pipeline they own, without depending
@@ -484,7 +472,6 @@ type SourceSymbolCallback = (
   packetId: number,
   ssId: number,
   rawSymbol: Uint8Array,
-  alta: ParsedAltaTrailer | undefined,
 ) => void
 
 export interface ParseHeaderOptions {
@@ -758,6 +745,48 @@ class FecReleaseSequencer {
     return total
   }
 
+  #deferDepth = 0
+  #deferredStreams = new Set<GatedStream>()
+
+  /**
+   * Run `work` with the drains its pushes would run deferred to its end. A
+   * recovered FEC block is routed one frame at a time, and its block is
+   * already resolved when the first frame is pushed: draining on that push
+   * would release past the gap before the block's other recovered frames
+   * arrive (deciding a conceal or stall for media that is about to land),
+   * and those frames would then be dropped as stale. Nests.
+   */
+  defer(work: () => void): void {
+    this.#deferDepth++
+    let threw = true
+    try {
+      work()
+      threw = false
+    } finally {
+      this.#deferDepth--
+      if (this.#deferDepth === 0 && this.#deferredStreams.size > 0) {
+        const streams = [...this.#deferredStreams]
+        this.#deferredStreams.clear()
+        if (!threw) {
+          for (const stream of streams) this.#drain(stream)
+        } else {
+          // `work` is unwinding: still release what it pushed, but never let
+          // a drain failure replace the exception that is propagating.
+          try {
+            for (const stream of streams) this.#drain(stream)
+          } catch {
+            // The original exception wins; the next push or poke drains again.
+          }
+        }
+      }
+    }
+  }
+
+  #drainUnlessDeferred(stream: GatedStream): void {
+    if (this.#deferDepth > 0) this.#deferredStreams.add(stream)
+    else this.#drain(stream)
+  }
+
   push(streamKey: string, data: Uint8Array, meta: FrameMeta, seq: number): void {
     const frame: GatedFrame = { data, meta: { ...meta }, seq, arrivedAtMs: performance.now() }
     const stream = this.#streamFor(streamKey, meta)
@@ -781,7 +810,7 @@ class FecReleaseSequencer {
         return
       }
       this.#release(stream, frame, undefined)
-      this.#drain(stream)
+      this.#drainUnlessDeferred(stream)
       return
     }
     let lo = 0
@@ -792,7 +821,24 @@ class FecReleaseSequencer {
       else hi = mid
     }
     stream.buf.splice(lo, 0, frame)
-    this.#drain(stream)
+    this.#drainUnlessDeferred(stream)
+  }
+
+  /**
+   * Arrival time of the earliest frame a stream of `packetId` holds behind a
+   * gap (the gate forces it out `holdLimitMs` after that), or undefined when
+   * none is held. Without `catalogTrackName`, every stream of the packetId.
+   */
+  earliestHeldArrivalMs(packetId: number, catalogTrackName?: string): number | undefined {
+    let earliest: number | undefined
+    for (const stream of this.#streams.values()) {
+      if (stream.packetId !== packetId) continue
+      if (catalogTrackName !== undefined && stream.catalogTrackName !== catalogTrackName) continue
+      for (const frame of stream.buf) {
+        if (earliest === undefined || frame.arrivedAtMs < earliest) earliest = frame.arrivedAtMs
+      }
+    }
+    return earliest
   }
 
   /** Re-evaluate held gaps after FEC state changed. */
@@ -855,6 +901,24 @@ class FecReleaseSequencer {
     }
   }
 
+  /**
+   * The packet's FEC ended, so no block will resolve a held gap: release its
+   * frames in order, each gap stalled as a discontinuity, and forget its
+   * streams, so FEC configured on it again starts from a fresh one.
+   */
+  endPacket(packetId: number): void {
+    for (const [key, stream] of this.#streams) {
+      if (stream.packetId !== packetId) continue
+      // Frames are held only behind a released one, so `last` is set; each
+      // pass releases at least the head.
+      while (stream.buf.length > 0 && stream.last !== null) {
+        stream.discontinuity = true
+        this.#drain(stream)
+      }
+      this.#streams.delete(key)
+    }
+  }
+
   discardPacket(packetId: number): void {
     for (const [key, stream] of this.#streams) {
       if (stream.packetId !== packetId) continue
@@ -1248,6 +1312,24 @@ export class MmtpContainerParser {
       : null
   }
 
+  /**
+   * Run `work` with the FEC release gate's drains deferred to its end, so
+   * every frame it pushes is in place before any held gap is decided (see
+   * FecReleaseSequencer.defer).
+   */
+  deferFecRelease(work: () => void): void {
+    if (!this.#fecSequencer) {
+      work()
+      return
+    }
+    this.#fecSequencer.defer(work)
+  }
+
+  /** See FecReleaseSequencer.earliestHeldArrivalMs. */
+  fecReleaseEarliestHeldAtMs(packetId: number, catalogTrackName?: string): number | undefined {
+    return this.#fecSequencer?.earliestHeldArrivalMs(packetId, catalogTrackName)
+  }
+
   /** Re-evaluate held gaps after FEC block state changed. */
   pokeFecRelease(packetId?: number, catalogTrackName?: string): void {
     if (!this.#fecSequencer) return
@@ -1264,6 +1346,14 @@ export class MmtpContainerParser {
     this.#fecSequencer?.markDiscontinuity(this.#streamKey(packetId, catalogTrackName))
   }
 
+  /**
+   * The FEC of a packet ID ended: release the frames the FEC release gate
+   * holds for it in order, each gap stalled, and forget its gated streams.
+   */
+  endFecRelease(packetId: number): void {
+    this.#fecSequencer?.endPacket(packetId)
+  }
+
   /**
    * MPU and data-unit identity of one MMTP packet, parsed in place (no copy,
    * no reassembly). Null for non-MPU packets and packets that do not parse.
@@ -1502,12 +1592,8 @@ export class MmtpContainerParser {
       // Symbol-size zero-padding is the consumer's responsibility — FEC
       // symbol size is a FEC-config concern, not a parser concern.
       const rawSymbol = packet.subarray(0, packet.length - 4)
-      const altaTrailer = extractAltaTrailer(packet)
-      const alta = altaTrailer
-        ? { auth: altaTrailer.auth, payloadEnd: altaTrailer.signedEnd }
-        : undefined
       try {
-        this.#sourceSymbolCb(info.packetId, info.fecPayloadId.ssId, rawSymbol, alta)
+        this.#sourceSymbolCb(info.packetId, info.fecPayloadId.ssId, rawSymbol)
       } catch {
         // Source-symbol consumer threw — never block MFU extraction on
         // FEC-pipeline errors. The frame path stays viable; the consumer