@blockcast/mmt-container 2.2.0-main.da2e7cd1dd5d → 2.2.0-main.e75bbd7576a6

package/src/mmtp-container-parser.ts

@@ -365,10 +365,19 @@ export type MmtpFeedDropReason =
   /** No timing resolver, or it refused the initialization segment. */
   | 'init-timing-refused'
   | 'fragment-unexpected-fragmentation'
+  /** FT=1 before an FT=0 has bound the stream's timing track. */
   | 'fragment-no-resolver'
   /** addMovieFragment refused — includes the pending-timing-sample budget. */
   | 'fragment-timing-refused'
   | 'unknown-fragment-type'
+  /** Stable code, no longer produced: an FT=2 with no timing (before the
+   *  stream's first FT=0, or after setTrack dropped it) now waits for its
+   *  timing like one whose FT=1 has not arrived. A head counts as
+   *  `drop:mfu-sample-timing-missing` (parked) and a FI=2/FI=3 continuation
+   *  as the `pending` record. A continuation that completes a head the
+   *  reassembler buffered before the timing was dropped counts as
+   *  `drop:assembled-timing-missing`. A panel keyed on this code reads zero:
+   *  a re-attribution, not lost coverage. Re-key on both drop codes. */
   | 'mfu-no-resolver'
   | 'mfu-empty-payload'
   | 'mfu-du-header-missing'
@@ -679,7 +688,10 @@ class FrameSequencer {
 // ── FecReleaseSequencer ─────────────────────────────────────────────
 
 /** Authored decode-time adjacency: the next frame starts where this one ends. */
-function authoredAdjacent(before: FrameMeta, after: FrameMeta): boolean {
+export function authoredAdjacent(
+  before: Pick<FrameMeta, 'authoredTiming'>,
+  after: Pick<FrameMeta, 'authoredTiming'>,
+): boolean {
   const a = before.authoredTiming
   const b = after.authoredTiming
   if (!a || !b || a.mediaTimescale !== b.mediaTimescale) return false
@@ -1089,9 +1101,30 @@ interface AwaitingTimingHead {
   mpuSequenceNumber: number
   movieFragmentSequenceNumber: number
   sampleNumber: number
+  /** MMTP packet sequence number; a recovered copy carries its source's. */
+  sequenceNumber: number
   arrivedAt: number
 }
 
+/** FEC-recovered heads that went through the awaiting-timing queue. Every
+ * count but `pending` is cumulative. A held head is pending or has left the
+ * queue exactly once, so `held - expired - discarded - superseded - pending`
+ * is the number fed again once their FT=1 landed. That feed can still refuse
+ * one (size, offset, dispose from a frame callback); the refusal is counted in
+ * `feedStats.deferredOutcomes`, not here. */
+export interface MmtpRecoveredHeadTimingStats {
+  /** Held because their sample's FT=1 had not arrived yet. */
+  held: number
+  /** Left without timing: the reassembler-timeout deadline, or pushed out by the queue's capacity. */
+  expired: number
+  /** Dropped with their stream (track reconfigure, reset or retire) or by dispose(). */
+  discarded: number
+  /** Gave way to their arriving source copy, which takes their place in the queue. */
+  superseded: number
+  /** In the queue now; current occupancy, not cumulative. */
+  pending: number
+}
+
 const MAX_AWAITING_TIMING_HEADS = 8
 
 // ── MmtpContainerParser ─────────────────────────────────────────────
@@ -1129,6 +1162,9 @@ export class MmtpContainerParser {
   #reclaimedTimingSamples = 0
   #evictedTimingSamples = 0
   #rejectedMovieFragments = 0
+  #recoveredHeadsAwaitingTiming: Omit<MmtpRecoveredHeadTimingStats, 'pending'> = {
+    held: 0, expired: 0, discarded: 0, superseded: 0,
+  }
   #sequencers = new Map<string, { packetId: number; sequencer: FrameSequencer }>()
   #fecGate: FecReleaseGate | null = null
   #fecSequencer: FecReleaseSequencer | null = null
@@ -1346,6 +1382,15 @@ export class MmtpContainerParser {
     }
   }
 
+  /** Recovered heads parked for FT=1 timing (BLO-53369). Survives dispose(). */
+  get recoveredHeadsAwaitingTiming(): Readonly<MmtpRecoveredHeadTimingStats> {
+    let pending = 0
+    for (const { awaitingTiming } of this.#timingStreams.values()) {
+      for (const head of awaitingTiming) if (head.options?.recovered) pending++
+    }
+    return { ...this.#recoveredHeadsAwaitingTiming, pending }
+  }
+
   get reorderStats(): Readonly<MmtpReorderStats> {
     let bufferedFrames = this.#fecSequencer?.buffered ?? 0
     for (const { sequencer } of this.#sequencers.values()) bufferedFrames += sequencer.buffered
@@ -1541,7 +1586,7 @@ export class MmtpContainerParser {
     const now = Date.now()
     for (const { awaitingTiming } of this.#timingStreams.values()) {
       while (awaitingTiming.length > 0 && now - awaitingTiming[0]!.arrivedAt > timeoutMs) {
-        awaitingTiming.shift()
+        this.#leaveAwaitingTiming(awaitingTiming.shift()!, 'expired')
       }
     }
   }
@@ -1711,11 +1756,16 @@ export class MmtpContainerParser {
       if (mpu.fragmentationIndicator !== 0 || mpu.fragmentCounter !== 0)
         return this.#drop('fragment-unexpected-fragmentation')
       const resolver = this.#timingResolver(streamKey, info.packetId, false)
-      if (!resolver) return this.#drop('fragment-no-resolver')
+      if (!resolver?.initialized) return this.#drop('fragment-no-resolver')
       const pendingBefore = resolver.pendingSampleCount
       const evictedBefore = resolver.evictedSampleCount
       const remaining = this.#maxPendingTimingSamples - this.#pendingTimingSamples
-      const admitted = resolver.addMovieFragment(mpu.mpuSequenceNumber, data, remaining)
+      const admitted = resolver.addMovieFragment(
+        mpu.mpuSequenceNumber,
+        data,
+        remaining,
+        options?.recovered === true,
+      )
       // Sync on BOTH paths: the resolver can displace stale timing and still
       // refuse the fragment in hand, and a global count that missed those
       // freed slots would keep refusing on a budget that is no longer full.
@@ -1739,7 +1789,11 @@ export class MmtpContainerParser {
     }
     if (fragmentType !== 2) return this.#drop('unknown-fragment-type')
 
-    const resolver = this.#timingResolver(streamKey, info.packetId, false)
+    // An FT=2 before the stream's first FT=0 (a join, a track reset) is taken
+    // like one whose FT=1 has not arrived: a head waits for its timing, a
+    // continuation parks in the reassembler, and a later or FEC-recovered
+    // FT=0/FT=1 can still time them.
+    const resolver = this.#timingResolver(streamKey, info.packetId, true)
     if (!resolver) return this.#drop('mfu-no-resolver')
     if (!Number.isSafeInteger(data.byteLength) || data.byteLength <= 0)
       return this.#drop('mfu-empty-payload')
@@ -1761,6 +1815,7 @@ export class MmtpContainerParser {
           mpuSequenceNumber: mpu.mpuSequenceNumber,
           movieFragmentSequenceNumber: mfuDuHeader.movieFragmentSequenceNumber,
           sampleNumber: mfuDuHeader.sampleNumber,
+          sequenceNumber: info.sequenceNumber,
           arrivedAt: Date.now(),
         })
         return this.#drop('mfu-sample-timing-missing')
@@ -2228,6 +2283,9 @@ export class MmtpContainerParser {
     for (const { sequencer } of this.#sequencers.values()) sequencer.discard()
     this.#sequencers.clear()
     this.#fecSequencer?.discard()
+    for (const { awaitingTiming } of this.#timingStreams.values()) {
+      for (const head of awaitingTiming) this.#leaveAwaitingTiming(head, 'discarded')
+    }
     this.#timingStreams.clear()
     this.#pendingTimingSamples = 0
     this.#reliableMoqStartupGate.clear()
@@ -2253,10 +2311,27 @@ export class MmtpContainerParser {
   }
 
   #awaitTiming(streamKey: string, head: AwaitingTimingHead): void {
-    const awaitingTiming = this.#timingStreams.get(streamKey)?.awaitingTiming
-    if (!awaitingTiming) return
+    const state = this.#timingStreams.get(streamKey)
+    if (!state) return
+    // The source copy of a held recovered head takes its place, so the frame
+    // is delivered with source provenance once FT=1 lands.
+    if (!head.options?.recovered) {
+      const kept = state.awaitingTiming.filter(queued =>
+        !queued.options?.recovered || queued.sequenceNumber !== head.sequenceNumber)
+      this.#recoveredHeadsAwaitingTiming.superseded += state.awaitingTiming.length - kept.length
+      state.awaitingTiming = kept
+    }
+    const awaitingTiming = state.awaitingTiming
     awaitingTiming.push(head)
-    if (awaitingTiming.length > MAX_AWAITING_TIMING_HEADS) awaitingTiming.shift()
+    if (head.options?.recovered) this.#recoveredHeadsAwaitingTiming.held++
+    if (awaitingTiming.length > MAX_AWAITING_TIMING_HEADS) {
+      this.#leaveAwaitingTiming(awaitingTiming.shift()!, 'expired')
+    }
+  }
+
+  /** Count a recovered head leaving the queue other than by replay or its source copy. */
+  #leaveAwaitingTiming(head: AwaitingTimingHead, outcome: 'expired' | 'discarded'): void {
+    if (head.options?.recovered) this.#recoveredHeadsAwaitingTiming[outcome]++
   }
 
   /**
@@ -2286,6 +2361,7 @@ export class MmtpContainerParser {
     const state = this.#timingStreams.get(streamKey)
     if (!state) return
     this.#timingStreams.delete(streamKey)
+    for (const head of state.awaitingTiming) this.#leaveAwaitingTiming(head, 'discarded')
     this.#pendingTimingSamples -= state.resolver.pendingSampleCount
     if (this.#pendingTimingSamples < 0) {
       throw new Error('[MmtpContainerParser] pending timing sample accounting underflow')